New UUID Formats

4.3.1. UUIDv6 Basic Creation Algorithm

The following implementation algorithm is based on [RFC4122] but with changes specific to UUIDv6:¶

1. From a system-wide shared stable store (e.g., a file) or global variable, read the UUID generator state: the values of the timestamp and clock sequence used to generate the last UUID.¶

2. Obtain the current time as a 60 bit count of 100-nanosecond intervals since 00:00:00.00, 15 October 1582.¶

3. Set the time_low field to the 12 least significant bits of the starting 60 bit timestamp.¶

4. Truncate the timestamp to the 48 most significant bits in order to create time_high_and_time_mid.¶

5. Set the time_high field to the 32 most significant bits of the truncated timestamp.¶

6. Set the time_mid field to the 16 least significant bits of the truncated timestamp.¶

7. Create the 16 bit time_low_and_version by concatenating the 4 bit UUIDv6 version with the 12 bit time_low.¶

8. If the state was unavailable (e.g., non-existent or corrupted) or the timestamp is greater than the current timestamp generate a random 14 bit clock sequence value.¶

9. If the state was available, but the saved timestamp is less than or equal to the current timestamp, increment the clock sequence value.¶

10. Complete the 16 bit clock sequence high, low and reserved creation by concatenating the clock sequence onto UUID variant bits which take the most significant position in the 16 bit value.¶

11. Generate a 48 bit pseudo-random node.¶

12. Format by concatenating the 128 bits from each parts: time_high|time_mid|time_low_and_version|variant_clk_seq|node¶

13. Save the state (current timestamp and clock sequence) back to the stable store¶

The steps for splitting time_high_and_time_mid into time_high and time_mid are optional since the 48 bits of time_high and time_mid will remain in the same order as time_high_and_time_mid during the final concatenation. This extra step of splitting into the most significant 32 bits and least significant 16 bits proves useful when reusing an existing UUIDv1 implementation. In which the following logic can be applied to reshuffle the bits with minimal modifications.¶

4.4.1. UUIDv7 Timestamp Usage

UUIDv7 utilizes a 36 bit big-endian unsigned Unix Timestamp value (number of seconds since the epoch of 1 Jan 1970, leap seconds excluded so each hour is exactly 3600 seconds long). The 36 bit value was selected in order to provide more available time to the unix timestamp and avoid the Year 2038 problem by extending the maximum timestamp to the year 4147.¶

To achieve a 36 bit UUIDv7 timestamp, the lower 36 bits of a 64 bit unix time are extracted verbatim into UUIDv7¶

In the event that 32 bit Unix Timestamp are in use; four zeros MUST be appended at the start in the most significant (left-most) bits of the 32 bit Unix timestamp creating the 36 bit Unix timestamp. This ensures sorting compatibility with 64 bit unix timestamp which have been truncated to 36 bits.¶

Additional sub-second precision (millisecond, nanosecond, microsecond, etc) MAY be provided for encoding and decoding in the remaining bits in the layout.¶

UUIDv8 SHOULD be used in place of UUIDv7 if an application or implementation does not want to truncate a 64 bit Unix Epoch to the lower 36 bits.¶

4.4.2. UUIDv7 Clock Sequence Usage

UUIDv7 SHOULD utilize a monotonic sequence counter to provide additional sequencing guarantees when multiple UUIDv7 values are created in the same UNIXTS and SUBSEC timestamp. The amount of bits allocates to the sequence counter depend on the precision of the timestamp. For example, a more accurate timestamp source using nanosecond precision will require less clock sequence bits than a timestamp source utilizing seconds for precision. For best sequencing results the sequence counter SHOULD be placed immediately after available sub-second bits.¶

The clock sequence MUST start at zero and increment monotonically for each new UUIDv7 created on by the application on the same timestamp. When the timestamp increments the clock sequence MUST be reset to zero. The clock sequence MUST NOT rollover or reset to zero unless the timestamp has incremented. Care MUST be given to ensure that an adequate sized clock sequence is selected for a given application based on expected timestamp precision and expected UUIDv7 generation rates.¶

4.4.3. UUIDv7 Node Usage

UUIDv7 implementations, even with very detailed sub-second precision and the optional sequence counter, MAY have leftover bits that will be identified as the Node for this section. The UUIDv7 Node MAY contain any set of data an implementation desires however the node MUST NOT be set to all 0s which does not ensure global uniqueness. In most scenarios the node SHOULD be filled with pseudo-random data.¶

4.4.4. UUIDv7 Encoding and Decoding

The UUIDv7 bit layout for encoding and decoding are described separately in this document.¶

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                            unixts                             |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |unixts |         msec          |  ver  |          seq          |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |var|                         rand                              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                             rand                              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                            unixts                             |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |unixts |         usec          |  ver  |         usec          |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |var|             seq           |            rand               |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                             rand                              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

     0                   1                   2                   3
     0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                            unixts                             |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |unixts |         nsec          |  ver  |         nsec          |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |var|             nsec          |      seq      |     rand      |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
    |                             rand                              |
    +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+

4.5.1. UUIDv8 Timestamp Usage

UUIDv8's usage of timestamp relaxes both the timestamp source and timestamp length. Implementations are free to utilize any monotonically stable timestamp source for UUIDv8.¶

Some examples include:¶

• - Custom Epoch¶

• - NTP timestamp¶

• - ISO 8601 timestamp¶

• - Full, Non-truncated 64 bit Unix Epoch timestamp¶

The relaxed nature UUIDv8 timestamps also works to future proof this specification and allow implementations a method to create compliant time-based UUIDs using timestamp source that might not yet be defined.¶

Timestamps come in many sizes and UUIDv8 defines three fields that can easily used for the majority of timestamp lengths:¶

• 32 bit timestamp: using timestamp_32 and setting timestamp_48 to 0s¶

• 48 bit timestamp: using timestamp_32 and timestamp_48 entirely¶

• 60 bit timestamp: using timestamp_32, timestamp_48, and time_or_seq¶

• 64 bit timestamp: using timestamp_32, timestamp_48, and time_or_seq and truncating the timestamp the 60 most significant bits.¶

Although it is possible to create a timestamp larger than 64 bits in size The usage and bit layout of that timestamp format is up to the implementation. When a timestamp exceeds the 64th bit (octet 7), extra care must be taken to ensure the Variant bits are properly inserted at their respective location in the UUID. Likewise, the Version MUST always be implemented at the appropriate location.¶

Any timestamps that does not entirely fill the timestamp_32, timestamp_48 or time_or_seq MUST set all leftover bits in the least significant position of the respective field to 0. For example a 36 bit timestamp source would fully utilize timestamp_32 and 4 bits of timestamp_48. The remaining 12 bits in timestamp_48 MUST be set to 0.¶

By using implementation-specific timestamp sources it is not guaranteed that devices outside of the application context are able to extract and parse the timestamp from UUIDv8 without some pre-existing knowledge of the source timestamp used by the UUIDv8 implementation.¶

4.5.2. UUIDv8 Clock Sequence Usage

A clock sequence MUST be used with UUIDv8 as added sequencing guarantees when multiple UUIDv8 will be created on the same clock tick. The amount of bits allocated to the clock sequence depends on the precision of the timestamp source. For example, a more accurate timestamp source using nanosecond precision will require less clock sequence bits than a timestamp source utilizing seconds for precision.¶

The UUIDv8 layout in Figure 6 generically defines two possible clock sequence values that can leveraged:¶

• 12 bit clock sequence using time_or_seq for use when the timestamp is less than 48 bits which allows for 4095 UUIDs per clock tick.¶

• 8 bit clock sequence using seq_or_node when the timestamp uses more than 48 bits which allows for 255 UUIDs per clock tick.¶

An implementation MAY use both time_or_seq and seq_or_node for clock sequencing however it is highly unlikely that 20 bits of clock sequence are needed for a given clock tick. Furthermore, more bits from the node MAY be used for clock sequencing in the event that 8 bits is not sufficient.¶

The clock sequence MUST start at zero and increment monotonically for each new UUIDv8 created on by the application on the same timestamp. When the timestamp increments the clock sequence MUST be reset to zero. The clock sequence MUST NOT rollover or reset to zero unless the timestamp has incremented. Care MUST be given to ensure that an adequate sized clock sequence is selected for a given application based on expected timestamp precision and expected UUIDv8 generation rates.¶

4.5.3. UUIDv8 Node Usage

The UUIDv8 Node MAY contain any set of data an implementation desires however the node MUST NOT be set to all 0s which does not ensure global uniqueness. In most scenarios the node will be filled with pseudo-random data.¶

The UUIDv8 layout in Figure 6 defines 2 sizes of Node depending on the timestamp size:¶

• 62 bit node encompassing seq_or_node and node Used when a timestamp of 48 bits or less is leveraged.¶

• 54 bit node when all 60 bits of the timestamp are in use and the seq_or_node is used as clock sequencing.¶

An implementation MAY choose to allocate bits from the node to the timestamp, clock sequence or application-specific embedded field. It is recommended that implementation utilize a node of at least 48 bits to ensure global uniqueness can be guaranteed.¶

4.5.4. UUIDv8 Basic Creation Algorithm

The entire usage of UUIDv8 is meant to be variable and allow as much customization as possible to meet specific application/language requirements. As such any UUIDv8 implementations will likely vary among applications.¶

The following algorithm is a generic implementation using Figure 6 and the recommendations outlined in this specification.¶

32 bit timestamp, 12 bit sequence counter, 62 bit node:¶

1. From a system-wide shared stable store (e.g., a file) or global variable, read the UUID generator state: the values of the timestamp and clock sequence used to generate the last UUID.¶

2. Obtain the current time from the selected clock source as 32 bits.¶

3. Set the 32 bit field timestamp_32 to the 32 bits from the timestamp¶

4. Set 16 bit timestamp_48 to all 0s¶

5. Set the version to 8 (1000)¶

6. If the state was unavailable (e.g., non-existent or corrupted) or the timestamp is greater than the current timestamp; set the 12 bit clock sequence value (time_or_seq) to 0¶

7. If the state was available, but the saved timestamp is less than or equal to the current timestamp, increment the clock sequence value (time_or_seq).¶

8. Set the variant to binary 10¶

9. Generate 62 random bits and fill in 8 bits for seq_or_node and 54 bits for the node.¶

10. Format by concatenating the 128 bits as: timestamp_32|timestamp_48|version|time_or_seq|variant|seq_or_node|node¶

11. Save the state (current timestamp and clock sequence) back to the stable store¶

48 bit timestamp, 12 bit sequence counter, 62 bit node:¶

1. From a system-wide shared stable store (e.g., a file) or global variable, read the UUID generator state: the values of the timestamp and clock sequence used to generate the last UUID.¶

2. Obtain the current time from the selected clock source as 32 bits.¶

3. Set the 32 bit field timestamp_32 to the 32 most significant bits from the timestamp¶

4. Set 16 bit timestamp_48 to the 16 least significant bits from the timestamp¶

5. The rest of the steps are the same as the previous example.¶

60 bit timestamp, 8 bit sequence counter, 54 bit node:¶

1. From a system-wide shared stable store (e.g., a file) or global variable, read the UUID generator state: the values of the timestamp and clock sequence used to generate the last UUID.¶

2. Obtain the current time from the selected clock source as 32 bits.¶

3. Set the 32 bit field timestamp_32 to the 32 bits from the timestamp¶

4. Set 16 bit timestamp_48 to the 16 middle bits from the timestamp¶

5. Set the version to 8 (1000)¶

6. Set 12 bit time_or_seq to the 12 least significant bits from the timestamp¶

7. Set the variant to 10¶

8. If the state was unavailable (e.g., non-existent or corrupted) or the timestamp is greater than the current timestamp; set the 12 bit clock sequence value (seq_or_node) to 0¶

9. If the state was available, but the saved timestamp is less than or equal to the current timestamp, increment the clock sequence value (seq_or_node).¶

10. Generate 54 random bits and fill in the node¶

11. Format by concatenating the 128 bits as: timestamp_32|timestamp_48|version|time_or_seq|variant|seq_or_node|node¶

12. Save the state (current timestamp and clock sequence) back to the stable store¶

64 bit timestamp, 8 bit sequence counter, 54 bit node:¶

1. The same steps as the 60 bit timestamp can be utilized if the 64 bit timestamp is truncated to 60 bits.¶

2. Implementations MAY chose to truncate the most or least significant bits but it is recommended to utilize the most significant 60 bits and lose 4 bits of precision in the nanoseconds or microseconds position.¶

General algorithm for generation of UUIDv8 not defined here:¶

1. From a system-wide shared stable store (e.g., a file) or global variable, read the UUID generator state: the values of the timestamp and clock sequence used to generate the last UUID.¶

2. Obtain the current time from the selected clock source as desired bit total¶

3. Set total amount of bits for timestamp as required in the most significant positions of the 128 bit UUID¶

4. Care MUST be taken to ensure that the UUID Version and UUID Variant are in the correct bit positions.¶

   UUID Version: Bits 48 through 51¶

   UUID Variant: Bits 64 and 65¶

5. If the state was unavailable (e.g., non-existent or corrupted) or the timestamp is greater than the current timestamp; set the desired clock sequence value to 0¶

6. If the state was available, but the saved timestamp is less than or equal to the current timestamp, increment the clock sequence value.¶

7. Set the remaining bits to the node as pseudo-random data¶

8. Format by concatenating the 128 bits together¶

9. Save the state (current timestamp and clock sequence) back to the stable store¶