Specification: Ballerina UUID Library

Owners: @daneshk @MadhukaHarith92
Reviewers: @daneshk
Created: 2021/11/16
Updated: 2022/02/08
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 Slack channel. 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

  1. Overview
  2. Generating UUIDs
  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.

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.

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

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.

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

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.

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

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.

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

2.5. Nil UUID

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

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

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.

4. Validating UUIDs

The uuid:validate() function validates a UUID.

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.

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

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