Specification: Ballerina UUID Library

Owners: @daneshk @MadhukaHarith92
Reviewers: @daneshk
Created: 2021/11/16
Updated: 2023/10/04
Edition: Swan Lake

Introduction

This is the specification for the UUID standard library of Ballerina language, which provides APIs to generate UUIDs based on the RFC 4122.

The UUID library specification has evolved and may continue to evolve in the future. The released versions of the specification can be found under the relevant Github tag.

If you have any feedback or suggestions about the library, start a discussion via a GitHub issue or in the Discord server. Based on the outcome of the discussion, the specification and implementation can be updated. Community feedback is always welcome. Any accepted proposal, which affects the specification is stored under /docs/proposals. Proposals under discussion can be found with the label type/proposal in GitHub.

The conforming implementation of the specification is released and included in the distribution. Any deviation from the specification is considered a bug.

Contents

• Specification: Ballerina UUID Library
  • Introduction
  • Contents
  • 1. Overview
  • 2. Generating UUIDs
    • 2.1. Version 1
    • 2.2. Version 3
    • 2.3. Version 4
    • 2.4. Version 5
    • 2.5. Nil UUID
  • 3. Checking the Version of UUIDs
  • 4. Validating UUIDs
  • 5. UUID operations

1. Overview

This specification elaborates on the functions available in the UUID library.

2. Generating UUIDs

UUID module supports generating 4 versions of UUIDs. They are generated as UUID strings or UUID records. The following is the UUID record definition.

# Represents a UUID.
#
# + timeLow - The low field of the timestamp
# + timeMid - The middle field of the timestamp
# + timeHiAndVersion - The high field of the timestamp multiplexed with the version number
# + clockSeqHiAndReserved - The high field of the clock sequence multiplexed with the variant
# + clockSeqLo - The low field of the clock sequence
# + node - The spatially unique node identifier
public type Uuid readonly & record {
    ints:Unsigned32 timeLow;
    ints:Unsigned16 timeMid;
    ints:Unsigned16 timeHiAndVersion;
    ints:Unsigned8 clockSeqHiAndReserved;
    ints:Unsigned8 clockSeqLo;
    int node;
};

The uuid:createRandomUuid() function is a convenient alias for uuid:createType4AsString() that returns a random UUID as a string.

string uuid = uuid:createRandomUuid();

This function is sufficient for most use cases. However, if a specific UUID type is required, the following APIs are also available.

2.1. Version 1

This is generated using the MAC address of the computer and the time of generation.

The uuid:createType1AsString() function returns a UUID as a string.

string uuid1 = uuid:createType1AsString();

The uuid:createType1AsRecord() function returns a UUID as a Uuid record.

uuid:Uuid|uuid:Error uuid1 = uuid:createType1AsRecord();

2.2. Version 3

This is generated using cryptographic hashing and application-provided text strings. MD5 hashing is used.

UUID library has a set of pre-defined UUIDs strings of well known namespace IDs.

NAME_SPACE_DNS - Namespace is a fully-qualified domain name
NAME_SPACE_URL - Namespace is a URL
NAME_SPACE_OID - Namespace is an ISO OID
NAME_SPACE_X500 - Namespace is an X.500 DN (in DER or a text output format)
NAME_SPACE_NIL - Empty UUID

The uuid:createType3AsString() function returns a UUID as a string or else a uuid:Error.

string|uuid:Error uuid3 = uuid:createType3AsString(uuid:NAME_SPACE_DNS, “ballerina.io”);

The uuid:createType3AsRecord() function returns a UUID as a Uuid record or else a uuid:Error.

uuid:Uuid|uuid:Error uuid3 = uuid:createType3AsRecord(uuid:NAME_SPACE_DNS, “ballerina.io”);

2.3. Version 4

This is generated using a pseudo-random number generator. Every bit of the string is randomly generated.

The uuid:createType4AsString() function returns a UUID as a string.

string uuid4 = uuid:createType4AsString();

The uuid:createType4AsRecord() function returns a UUID as a Uuid record or else a uuid:Error.

uuid:Uuid|uuid:Error uuid4 = uuid:createType4AsRecord();

2.4. Version 5

This is generated using cryptographic hashing and application-provided text strings. SHA-1 hashing is used.

The uuid:createType5AsString() function returns a UUID as a string or else a uuid:Error.

string|uuid:Error uuid5 = uuid:createType5AsString(uuid:NAME_SPACE_DNS, “ballerina.io”);

The uuid:createType5AsRecord() function returns a UUID as a Uuid record or else a uuid:Error.

uuid:Uuid|uuid:Error uuid5 = uuid:createType5AsRecord(uuid:NAME_SPACE_DNS, “ballerina.io”);

2.5. Nil UUID

The nilAsString() function returns a nil UUID as a string.

string nilUUID = uuid:nilAsString();

The nilAsRecord() function returns a nil UUID as a UUID record.

uuid:Uuid nilUUID = uuid:nilAsRecord();

3. Checking the Version of UUIDs

The uuid:getVersion() function detects the RFC version of a UUID. This returns an error if the UUID is invalid.

uuid:Version|uuid:Error v = uuid:getVersion("4397465e-35f9-11eb-adc1-0242ac120002");

4. Validating UUIDs

The uuid:validate() function validates a UUID.

boolean valid = uuid:validate("4397465e-35f9-11eb-adc1-0242ac120002");

5. UUID operations

UUID module supports the conversion of a UUID between 3 data types; string, byte[], and Uuid record.

The toBytes() function converts a UUID string or a Uuid record to a byte[]. This returns an error if the UUID is invalid.

byte[]|uuid:Error b = uuid:toBytes(“6ec0bd7f-11c0-43da-975e-2aesass0b”);

The toString() function converts a Uuid record or a byte[] to a UUID string. This returns an error if the UUID is invalid.

string|uuid:Error s = uuid:toString([5, 12, 16, 35]);

The toRecord() function converts a UUID string or a byte[] to a Uuid record. This returns an error if the UUID is invalid.

uuid:Uuid|uuid:Error r1 = uuid:toRecord("4397465e-35f9-11eb-adc1-0242ac120002");
uuid:Uuid|uuid:Error r2 = uuid:toRecord([10, 20, 30]);