This repository has been archived by the owner on Jul 9, 2024. It is now read-only.
-
Notifications
You must be signed in to change notification settings - Fork 11
/
draft-peabody-dispatch-new-uuid-format-04.txt
1736 lines (1137 loc) · 63.2 KB
/
draft-peabody-dispatch-new-uuid-format-04.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
dispatch BGP. Peabody
Internet-Draft
Updates: 4122 (if approved) K. Davis
Intended status: Standards Track 23 June 2022
Expires: 25 December 2022
New UUID Formats
draft-peabody-dispatch-new-uuid-format-04
Abstract
This document presents new Universally Unique Identifier (UUID)
formats for use in modern applications and databases.
Status of This Memo
This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
This Internet-Draft will expire on 25 December 2022.
Copyright Notice
Copyright (c) 2022 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents (https://trustee.ietf.org/
license-info) in effect on the date of publication of this document.
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. Code Components
extracted from this document must include Revised BSD License text as
described in Section 4.e of the Trust Legal Provisions and are
provided without warranty as described in the Revised BSD License.
Peabody & Davis Expires 25 December 2022 [Page 1]
Internet-Draft new-uuid-format June 2022
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
2.1. Requirements Language . . . . . . . . . . . . . . . . . . 4
2.2. Abbreviations . . . . . . . . . . . . . . . . . . . . . . 5
3. Summary of Changes . . . . . . . . . . . . . . . . . . . . . 5
3.1. changelog . . . . . . . . . . . . . . . . . . . . . . . . 5
4. Variant and Version Fields . . . . . . . . . . . . . . . . . 7
5. New Formats . . . . . . . . . . . . . . . . . . . . . . . . . 8
5.1. UUID Version 6 . . . . . . . . . . . . . . . . . . . . . 8
5.2. UUID Version 7 . . . . . . . . . . . . . . . . . . . . . 10
5.3. UUID Version 8 . . . . . . . . . . . . . . . . . . . . . 11
5.4. Max UUID . . . . . . . . . . . . . . . . . . . . . . . . 12
6. UUID Best Practices . . . . . . . . . . . . . . . . . . . . . 12
6.1. Timestamp Granularity . . . . . . . . . . . . . . . . . . 12
6.2. Monotonicity and Counters . . . . . . . . . . . . . . . . 14
6.3. Distributed UUID Generation . . . . . . . . . . . . . . . 17
6.4. Collision Resistance . . . . . . . . . . . . . . . . . . 18
6.5. Global and Local Uniqueness . . . . . . . . . . . . . . . 18
6.6. Unguessability . . . . . . . . . . . . . . . . . . . . . 19
6.7. Sorting . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.8. Opacity . . . . . . . . . . . . . . . . . . . . . . . . . 19
6.9. DBMS and Database Considerations . . . . . . . . . . . . 19
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 20
8. Security Considerations . . . . . . . . . . . . . . . . . . . 20
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . 20
10. Normative References . . . . . . . . . . . . . . . . . . . . 20
11. Informative References . . . . . . . . . . . . . . . . . . . 21
Appendix A. Example Code . . . . . . . . . . . . . . . . . . . . 23
A.1. Creating a UUIDv6 Value . . . . . . . . . . . . . . . . . 23
A.2. Creating a UUIDv7 Value . . . . . . . . . . . . . . . . . 23
A.3. Creating a UUIDv8 Value . . . . . . . . . . . . . . . . . 25
Appendix B. Test Vectors . . . . . . . . . . . . . . . . . . . . 26
B.1. Example of a UUIDv6 Value . . . . . . . . . . . . . . . . 27
B.2. Example of a UUIDv7 Value . . . . . . . . . . . . . . . . 28
B.3. Example of a UUIDv8 Value . . . . . . . . . . . . . . . . 28
Appendix C. Version and Variant Tables . . . . . . . . . . . . . 29
C.1. Variant 10xx Versions . . . . . . . . . . . . . . . . . . 29
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 30
Peabody & Davis Expires 25 December 2022 [Page 2]
Internet-Draft new-uuid-format June 2022
1. Introduction
Many things have changed in the time since UUIDs were originally
created. Modern applications have a need to create and utilize UUIDs
as the primary identifier for a variety of different items in complex
computational systems, including but not limited to database keys,
file names, machine or system names, and identifiers for event-driven
transactions.
One area UUIDs have gained popularity is as database keys. This
stems from the increasingly distributed nature of modern
applications. In such cases, "auto increment" schemes often used by
databases do not work well, as the effort required to coordinate
unique numeric identifiers across a network can easily become a
burden. The fact that UUIDs can be used to create unique, reasonably
short values in distributed systems without requiring synchronization
makes them a good alternative, but UUID versions 1-5 lack certain
other desirable characteristics:
1. Non-time-ordered UUID versions such as UUIDv4 have poor database
index locality. Meaning new values created in succession are not
close to each other in the index and thus require inserts to be
performed at random locations. The negative performance effects
of which on common structures used for this (B-tree and its
variants) can be dramatic.
2. The 100-nanosecond, Gregorian epoch used in UUIDv1 timestamps is
uncommon and difficult to represent accurately using a standard
number format such as [IEEE754].
3. Introspection/parsing is required to order by time sequence; as
opposed to being able to perform a simple byte-by-byte
comparison.
4. Privacy and network security issues arise from using a MAC
address in the node field of Version 1 UUIDs. Exposed MAC
addresses can be used as an attack surface to locate machines and
reveal various other information about such machines (minimally
manufacturer, potentially other details). Additionally, with the
advent of virtual machines and containers, MAC address uniqueness
is no longer guaranteed.
5. Many of the implementation details specified in [RFC4122] involve
trade offs that are neither possible to specify for all
applications nor necessary to produce interoperable
implementations.
Peabody & Davis Expires 25 December 2022 [Page 3]
Internet-Draft new-uuid-format June 2022
6. [RFC4122] does not distinguish between the requirements for
generation of a UUID versus an application which simply stores
one, which are often different.
Due to the aforementioned issue, many widely distributed database
applications and large application vendors have sought to solve the
problem of creating a better time-based, sortable unique identifier
for use as a database key. This has lead to numerous implementations
over the past 10+ years solving the same problem in slightly
different ways.
While preparing this specification the following 16 different
implementations were analyzed for trends in total ID length, bit
Layout, lexical formatting/encoding, timestamp type, timestamp
format, timestamp accuracy, node format/components, collision
handling and multi-timestamp tick generation sequencing.
1. [ULID] by A. Feerasta
2. [LexicalUUID] by Twitter
3. [Snowflake] by Twitter
4. [Flake] by Boundary
5. [ShardingID] by Instagram
6. [KSUID] by Segment
7. [Elasticflake] by P. Pearcy
8. [FlakeID] by T. Pawlak
9. [Sonyflake] by Sony
10. [orderedUuid] by IT. Cabrera
11. [COMBGUID] by R. Tallent
12. [SID] by A. Chilton
13. [pushID] by Google
14. [XID] by O. Poitrey
15. [ObjectID] by MongoDB
16. [CUID] by E. Elliott
An inspection of these implementations and the issues described above
has led to this document which attempts to adapt UUIDs to address
these issues.
2. Terminology
2.1. Requirements Language
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and
"OPTIONAL" in this document are to be interpreted as described in BCP
14 [RFC2119] [RFC8174] when, and only when, they appear in all
capitals, as shown here.
Peabody & Davis Expires 25 December 2022 [Page 4]
Internet-Draft new-uuid-format June 2022
2.2. Abbreviations
The following abbreviations are used in this document:
UUID Universally Unique Identifier [RFC4122]
CSPRNG Cryptographically Secure Pseudo-Random Number Generator
MAC Media Access Control
MSB Most Significant Bit
DBMS Database Management System
3. Summary of Changes
The following UUIDs are hereby introduced:
UUID version 6 (UUIDv6)
A re-ordering of UUID version 1 so it is sortable as an opaque
sequence of bytes. Easy to implement given an existing UUIDv1
implementation. See Section 5.1
UUID version 7 (UUIDv7)
An entirely new time-based UUID bit layout sourced from the widely
implemented and well known Unix Epoch timestamp source. See
Section 5.2
UUID version 8 (UUIDv8)
A free-form UUID format which has no explicit requirements except
maintaining backward compatibility. See Section 5.3
Max UUID
A specialized UUID which is the inverse of [RFC4122],
Section 4.1.7 See Section 5.4
3.1. changelog
RFC EDITOR PLEASE DELETE THIS SECTION.
draft-04
- Fixed bad title in IEEE754 Normative Reference
- Fixed bad GMT offset in Test Vector Appendix
- Removed MAY in Counters section
- Condensed Counter Type into Counter Methods to reduce text
- Removed option for random increment along with fixed-length
counter
Peabody & Davis Expires 25 December 2022 [Page 5]
Internet-Draft new-uuid-format June 2022
- Described how to handle scenario where New UUID less than Old
UUID
- Allow timestamp increment if counter overflows
- Replaced UUIDv8 C code snippet with full generation example
- Fixed RFC4086 Reference link
- Describe reseeding best practice for CSPRNG
- Changed MUST to SHOULD removing requirement for absolute
monotonicity
draft-03
- Reworked the draft body to make the content more concise
- UUIDv6 section reworked to just the reorder of the timestamp
- UUIDv7 changed to simplify timestamp mechanism to just
millisecond Unix timestamp
- UUIDv8 relaxed to be custom in all elements except version and
variant
- Introduced Max UUID.
- Added C code samples in Appendix.
- Added test vectors in Appendix.
- Version and Variant section combined into one section.
- Changed from pseudo-random number generators to
cryptographically secure pseudo-random number generator (CSPRNG).
- Combined redundant topics from all UUIDs into sections such as
Timestamp granularity, Monotonicity and Counters, Collision
Resistance, Sorting, and Unguessability, etc.
- Split Encoding and Storage into Opacity and DBMS and Database
Considerations
- Reworked Global Uniqueness under new section Global and Local
Uniqueness
- Node verbiage only used in UUIDv6 all others reference random/
rand instead
- Clock sequence verbiage changed simply to counter in any section
other than UUIDv6
- Added Abbreviations section
- Updated IETF Draft XML Layout
- Added information about little-endian UUIDs
draft-02
- Added Changelog
- Fixed misc. grammatical errors
- Fixed section numbering issue
- Fixed some UUIDvX reference issues
- Changed all instances of "motonic" to "monotonic"
- Changed all instances of "#-bit" to "# bit"
- Changed "proceeding" verbiage to "after" in section 7
Peabody & Davis Expires 25 December 2022 [Page 6]
Internet-Draft new-uuid-format June 2022
- Added details on how to pad 32 bit Unix timestamp to 36 bits in
UUIDv7
- Added details on how to truncate 64 bit Unix timestamp to 36
bits in UUIDv7
- Added forward reference and bullet to UUIDv8 if truncating 64
bit Unix Epoch is not an option.
- Fixed bad reference to non-existent "time_or_node" in section
4.5.4
draft-01
- Complete rewrite of entire document.
- The format, flow and verbiage used in the specification has been
reworked to mirror the original RFC 4122 and current IETF
standards.
- Removed the topics of UUID length modification, alternate UUID
text formats, and alternate UUID encoding techniques.
- Research into 16 different historical and current
implementations of time-based universal identifiers was completed
at the end of 2020 in attempt to identify trends which have
directly influenced design decisions in this draft document
(https://github.com/uuid6/uuid6-ietf-draft/tree/master/research)
- Prototype implementation have been completed for UUIDv6, UUIDv7,
and UUIDv8 in various languages by many GitHub community members.
(https://github.com/uuid6/prototypes)
4. Variant and Version Fields
The variant bits utilized by UUIDs in this specification remain in
the same octet as originally defined by [RFC4122], Section 4.1.1.
The next table details Variant 10xx (8/9/A/B) and the new versions
defined by this specification. A complete guide to all versions
within this variant has been includes in Appendix C.1.
Peabody & Davis Expires 25 December 2022 [Page 7]
Internet-Draft new-uuid-format June 2022
+------+------+------+------+---------+---------------------------+
| Msb0 | Msb1 | Msb2 | Msb3 | Version | Description |
+------+------+------+------+---------+---------------------------+
| 0 | 1 | 1 | 0 | 6 | Reordered Gregorian time- |
| | | | | | based UUID specified in |
| | | | | | this document. |
+------+------+------+------+---------+---------------------------+
| 0 | 1 | 1 | 1 | 7 | Unix Epoch time-based |
| | | | | | UUID specified in this |
| | | | | | document. |
+------+------+------+------+---------+---------------------------+
| 1 | 0 | 0 | 0 | 8 | Reserved for custom UUID |
| | | | | | formats specified in this |
| | | | | | document |
+------+------+------+------+---------+---------------------------+
Table 1: New UUID variant 10xx (8/9/A/B) versions defined by this
specification
For UUID version 6, 7 and 8 the variant field placement from
[RFC4122] are unchanged. An example version/variant layout for
UUIDv6 follows the table where M is the version and N is the variant.
00000000-0000-6000-8000-000000000000
00000000-0000-6000-9000-000000000000
00000000-0000-6000-A000-000000000000
00000000-0000-6000-B000-000000000000
xxxxxxxx-xxxx-Mxxx-Nxxx-xxxxxxxxxxxx
Figure 1: UUIDv6 Variant Examples
5. New Formats
The UUID format is 16 octets; the variant bits in conjunction with
the version bits described in the next section in determine finer
structure.
5.1. UUID Version 6
UUID version 6 is a field-compatible version of UUIDv1, reordered for
improved DB locality. It is expected that UUIDv6 will primarily be
used in contexts where there are existing v1 UUIDs. Systems that do
not involve legacy UUIDv1 SHOULD consider using UUIDv7 instead.
Instead of splitting the timestamp into the low, mid and high
sections from UUIDv1, UUIDv6 changes this sequence so timestamp bytes
are stored from most to least significant. That is, given a 60 bit
timestamp value as specified for UUIDv1 in [RFC4122], Section 4.1.4,
Peabody & Davis Expires 25 December 2022 [Page 8]
Internet-Draft new-uuid-format June 2022
for UUIDv6, the first 48 most significant bits are stored first,
followed by the 4 bit version (same position), followed by the
remaining 12 bits of the original 60 bit timestamp.
The clock sequence bits remain unchanged from their usage and
position in [RFC4122], Section 4.1.5.
The 48 bit node SHOULD be set to a pseudo-random value however
implementations MAY choose to retain the old MAC address behavior
from [RFC4122], Section 4.1.6 and [RFC4122], Section 4.5. For more
information on MAC address usage within UUIDs see the Section 8
The format for the 16-byte, 128 bit UUIDv6 is shown in Figure 1
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| time_high |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| time_mid | time_low_and_version |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|clk_seq_hi_res | clk_seq_low | node (0-1) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| node (2-5) |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 2: UUIDv6 Field and Bit Layout
time_high:
The most significant 32 bits of the 60 bit starting timestamp.
Occupies bits 0 through 31 (octets 0-3)
time_mid:
The middle 16 bits of the 60 bit starting timestamp. Occupies
bits 32 through 47 (octets 4-5)
time_low_and_version:
The first four most significant bits MUST contain the UUIDv6
version (0110) while the remaining 12 bits will contain the least
significant 12 bits from the 60 bit starting timestamp. Occupies
bits 48 through 63 (octets 6-7)
clk_seq_hi_res:
The first two bits MUST be set to the UUID variant (10) The
remaining 6 bits contain the high portion of the clock sequence.
Occupies bits 64 through 71 (octet 8)
Peabody & Davis Expires 25 December 2022 [Page 9]
Internet-Draft new-uuid-format June 2022
clock_seq_low:
The 8 bit low portion of the clock sequence. Occupies bits 72
through 79 (octet 9)
node:
48 bit spatially unique identifier Occupies bits 80 through 127
(octets 10-15)
With UUIDv6 the steps for splitting the timestamp into time_high and
time_mid are OPTIONAL since the 48 bits of time_high and time_mid
will remain in the same order. An extra step of splitting the first
48 bits of the timestamp into the most significant 32 bits and least
significant 16 bits proves useful when reusing an existing UUIDv1
implementation.
5.2. UUID Version 7
UUID version 7 features a time-ordered value field derived from the
widely implemented and well known Unix Epoch timestamp source, the
number of milliseconds seconds since midnight 1 Jan 1970 UTC, leap
seconds excluded. As well as improved entropy characteristics over
versions 1 or 6.
Implementations SHOULD utilize UUID version 7 over UUID version 1 and
6 if possible.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| unix_ts_ms | ver | rand_a |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var| rand_b |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| rand_b |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 3: UUIDv7 Field and Bit Layout
unix_ts_ms:
48 bit big-endian unsigned number of Unix epoch timestamp as per
Section 6.1.
ver:
4 bit UUIDv7 version set as per Section 4
Peabody & Davis Expires 25 December 2022 [Page 10]
Internet-Draft new-uuid-format June 2022
rand_a:
12 bits pseudo-random data to provide uniqueness as per
Section 6.2 and Section 6.6.
var:
The 2 bit variant defined by Section 4.
rand_b:
The final 62 bits of pseudo-random data to provide uniqueness as
per Section 6.2 and Section 6.6.
5.3. UUID Version 8
UUID version 8 provides an RFC-compatible format for experimental or
vendor-specific use cases. The only requirement is that the variant
and version bits MUST be set as defined in Section 4. UUIDv8's
uniqueness will be implementation-specific and SHOULD NOT be assumed.
The only explicitly defined bits are the Version and Variant leaving
122 bits for implementation specific time-based UUIDs. To be clear:
UUIDv8 is not a replacement for UUIDv4 where all 122 extra bits are
filled with random data.
Some example situations in which UUIDv8 usage could occur:
* An implementation would like to embed extra information within the
UUID other than what is defined in this document.
* An implementation has other application/language restrictions
which inhibit the use of one of the current UUIDs.
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
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| custom_a |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| custom_a | ver | custom_b |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
|var| custom_c |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
| custom_c |
+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
Figure 4: UUIDv8 Field and Bit Layout
custom_a:
The first 48 bits of the layout that can be filled as an
implementation sees fit.
Peabody & Davis Expires 25 December 2022 [Page 11]
Internet-Draft new-uuid-format June 2022
ver:
The 4 bit version field as defined by Section 4
custom_b:
12 more bits of the layout that can be filled as an implementation
sees fit.
var:
The 2 bit variant field as defined by Section 4.
custom_c:
The final 62 bits of the layout immediatly following the var field
to be filled as an implementation sees fit.
5.4. Max UUID
The Max UUID is special form of UUID that is specified to have all
128 bits set to 1. This UUID can be thought of as the inverse of Nil
UUID defined in [RFC4122], Section 4.1.7
FFFFFFFF-FFFF-FFFF-FFFF-FFFFFFFFFFFF
Figure 5: Max UUID Format
6. UUID Best Practices
The minimum requirements for generating UUIDs are described in this
document for each version. Everything else is an implementation
detail and up to the implementer to decide what is appropriate for a
given implementation. That being said, various relevant factors are
covered below to help guide an implementer through the different
trade-offs among differing UUID implementations.
6.1. Timestamp Granularity
UUID timestamp source, precision and length was the topic of great
debate while creating this specification. As such choosing the right
timestamp for your application is a very important topic. This
section will detail some of the most common points on this topic.
Peabody & Davis Expires 25 December 2022 [Page 12]
Internet-Draft new-uuid-format June 2022
Reliability:
Implementations SHOULD use the current timestamp from a reliable
source to provide values that are time-ordered and continually
increasing. Care SHOULD be taken to ensure that timestamp changes
from the environment or operating system are handled in a way that
is consistent with implementation requirements. For example, if
it is possible for the system clock to move backward due to either
manual adjustment or corrections from a time synchronization
protocol, implementations must decide how to handle such cases.
(See Altering, Fuzzing, or Smearing bullet below.)
Source:
UUID version 1 and 6 both utilize a Gregorian epoch timestamp
while UUIDv7 utilizes a Unix Epoch timestamp. If other timestamp
sources or a custom timestamp epoch are required UUIDv8 SHOULD be
leveraged.
Sub-second Precision and Accuracy:
Many levels of precision exist for timestamps: milliseconds,
microseconds, nanoseconds, and beyond. Additionally fractional
representations of sub-second precision may be desired to mix
various levels of precision in a time-ordered manner.
Furthermore, system clocks themselves have an underlying
granularity and it is frequently less than the precision offered
by the operating system. With UUID version 1 and 6,
100-nanoseconds of precision are present while UUIDv7 features
fixed millisecond level of precision within the Unix epoch that
does not exceed the granularity capable in most modern systems.
For other levels of precision UUIDv8 SHOULD be utilized.
Length:
The length of a given timestamp directly impacts how long a given
UUID will be valid. That is, how many timestamp ticks can be
contained in a UUID before the maximum value for the timestamp
field is reached. Care should be given to ensure that the proper
length is selected for a given timestamp. UUID version 1 and 6
utilize a 60 bit timestamp and UUIDv7 features a 48 bit timestamp.
Altering, Fuzzing, or Smearing:
Implementations MAY alter the actual timestamp. Some examples
included security considerations around providing a real clock
value within a UUID, to correct inaccurate clocks or to handle
leap seconds. This specification makes no requirement or
guarantee about how close the clock value needs to be to actual
time.
Peabody & Davis Expires 25 December 2022 [Page 13]
Internet-Draft new-uuid-format June 2022
Padding:
When timestamp padding is required, implementations MUST pad the
most significant bits (left-most) bits with zeros. An example is
padding the most significant, left-most bits of a 32 bit Unix
timestamp with zero's to fill out the 48 bit timestamp in UUIDv7.
Truncating:
Similarly, when timestamps need to be truncated: the lower, least
significant bits MUST be used. An example would be truncating a
64 bit Unix timestamp to the least significant, right-most 48 bits
for UUIDv7.
6.2. Monotonicity and Counters
Monotonicity is the backbone of time-based sortable UUIDs. Naturally
time-based UUIDs from this document will be monotonic due to an
embedded timestamp however implementations can guarantee additional
monotonicity via the concepts covered in this section.
Additionally, care SHOULD be taken to ensure UUIDs generated in
batches are also monotonic. That is, if one-thousand UUIDs are
generated for the same timestamp; there is sufficient logic for
organizing the creation order of those one-thousand UUIDs. For batch
UUID creation implementions MAY utilize a monotonic counter which
SHOULD increment for each UUID created during a given timestamp.
For single-node UUID implementations that do not need to create
batches of UUIDs, the embedded timestamp within UUID version 1, 6,
and 7 can provide sufficient monotonicity guarantees by simply
ensuring that timestamp increments before creating a new UUID. For
the topic of Distributed Nodes please refer to Section 6.3
Implementations SHOULD choose one method for single-node UUID
implementations that require batch UUID creation.
Peabody & Davis Expires 25 December 2022 [Page 14]
Internet-Draft new-uuid-format June 2022
Fixed-Length Dedicated Counter Bits (Method 1):
This references the practice of allocating a specific number of
bits in the UUID layout to the sole purpose of tallying the total
number of UUIDs created during a given UUID timestamp tick.
Positioning of a fixed bit-length counter SHOULD be immediatly
after the embedded timestamp. This promotes sortability and
allows random data generation for each counter increment. With
this method rand_a section of UUIDv7 SHOULD be utilized as fixed-
length dedicated counter bits that are incremented by one for
every UUID generation. The trailing random bits generated for
each new UUID in rand_b can help produce unguessable UUIDs. In
the event more counter bits are required the most significant,
left-most, bits of rand_b MAY be leveraged as additional counter
bits.
Monotonic Random (Method 2):
With this method the random data is extended to also double as a
counter. This monotonic random can be thought of as a "randomly
seeded counter" which MUST be incremented in the least significant
position for each UUID created on a given timestamp tick.
UUIDv7's rand_b section SHOULD be utilized with this method to
handle batch UUID generation during a single timestamp tick. The
increment value for every UUID generation SHOULD be a random
integer of any desired length larger than zero. It ensures the
UUIDs retain the required level of unguessability characters
provided by the underlying entropy. The increment value MAY be
one when the amount of UUIDs generated in a particular period of
time is important and guessability is not an issue. However, it
SHOULD NOT be used by implementations that favor unguessiblity, as
the resulting values are easily guessable.
The following sub-topics cover topics related solely with creating
reliable fixed-length dedicated counters:
Fixed-Length Dedicated Counter Seeding:
Implementations utilizing fixed-length counter method SHOULD
randomly initialize the counter with each new timestamp tick.
However, when the timestamp has not incremented; the counter
SHOULD be frozen and incremented via the desired increment logic.
When utilizing a randomly seeded counter alongside Method 1; the
random MAY be regenerated with each counter increment without
impacting sortability. The downside is that Method 1 is prone to
overflows if a counter of adequate length is not selected or the
random data generated leaves little room for the required number
of increments. Implementations utilizing fixed-length counter
method MAY also choose to randomly initialize a portion counter
rather than the entire counter. For example, a 24 bit counter
could have the 23 bits in least-significant, right-most, position
Peabody & Davis Expires 25 December 2022 [Page 15]
Internet-Draft new-uuid-format June 2022
randomly initialized. The remaining most significant, left-most
counter bits are initialized as zero for the sole purpose of
guarding against counter rollovers.
Fixed-Length Dedicated Counter Length:
Care MUST be taken to select a counter bit-length that can
properly handle the level of timestamp precision in use. For
example, millisecond precision SHOULD require a larger counter
than a timestamp with nanosecond precision. General guidance is
that the counter SHOULD be at least 12 bits but no longer than 42
bits. Care SHOULD also be given to ensure that the counter length
selected leaves room for sufficient entropy in the random portion
of the UUID after the counter. This entropy helps improve the
unguessability characteristics of UUIDs created within the batch.
The following sub-topics cover rollover handling with either type of
counter method:
Counter Rollover Guards:
The technique from Fixed-Length Dedicated Counter Seeding which
describes allocating a segment of the fixed-length counter as a
rollover guard is also helpful to mitigate counter rollover
issues. This same technique can be leveraged with Monotonic
random counter methods by ensuring the total length of a possible
increment in the least significant, right most position is less
than the total length of the random being incremented. As such
the most significant, left-most, bits can be incremented as
rollover guarding.
Counter Rollover Handling:
Counter rollovers SHOULD be handled by the application to avoid
sorting issues. The general guidance is that applications that
care about absolute monotonicity and sortability SHOULD freeze the
counter and wait for the timestamp to advance which ensures
monotonicity is not broken. Alternatively, implementations MAY
increment the timestamp ahead of the actual time and reinitialize
the counter.
Implementations MAY use the following logic to ensure UUIDs featuring
embedded counters are monotonic in nature:
1. Compare the current timestamp against the previously stored
timestamp.
2. If the current timestamp is equal to the previous timestamp;
increment the counter according to the desired method.
Peabody & Davis Expires 25 December 2022 [Page 16]
Internet-Draft new-uuid-format June 2022
3. If the current timestamp is greater than the previous timestamp;
re-initialize the desired counter method to the new timestamp and
generate new random bytes (if the bytes were frozen or being used
as the seed for a monotonic counter).
Implementations SHOULD check if the the currently generated UUID is
greater than the previously generated UUID. If this is not the case
then any number of things could have occurred. Such as, but not
limited to, clock rollbacks, leap second handling or counter
rollovers. Applications SHOULD embed sufficient logic to catch these
scenarios and correct the problem ensuring the next UUID generated is
greater than the previous. To handle this scenario, the general
guidance is that application MAY reuse the previous timestamp and
increment the previous counter method.
6.3. Distributed UUID Generation
Some implementations MAY desire to utilize multi-node, clustered,
applications which involve two or more nodes independently generating
UUIDs that will be stored in a common location. While UUIDs already
feature sufficient entropy to ensure that the chances of collision
are low as the total number of nodes increase; so does the likelihood
of a collision. This section will detail the approaches that MAY be
utilized by multi-node UUID implementations in distributed
environments.
Centralized Registry:
With this method all nodes tasked with creating UUIDs consult a
central registry and confirm the generated value is unique. As
applications scale the communication with the central registry
could become a bottleneck and impact UUID generation in a negative
way. Utilization of shared knowledge schemes with central/global
registries is outside the scope of this specification.
Node IDs:
With this method, a pseudo-random Node ID value is placed within
the UUID layout. This identifier helps ensure the bit-space for a
given node is unique, resulting in UUIDs that do not conflict with
any other UUID created by another node with a different node id.
Implementations that choose to leverage an embedded node id SHOULD
utilize UUIDv8. The node id SHOULD NOT be an IEEE 802 MAC address
as per Section 8. The location and bit length are left to
implementations and are outside the scope of this specification.
Furthermore, the creation and negotiation of unique node ids among
nodes is also out of scope for this specification.
Peabody & Davis Expires 25 December 2022 [Page 17]
Internet-Draft new-uuid-format June 2022
Utilization of either a Centralized Registry or Node ID are not
required for implementing UUIDs in this specification. However
implementations SHOULD utilize one of the two aforementioned methods
if distributed UUID generation is a requirement.
6.4. Collision Resistance
Implementations SHOULD weigh the consequences of UUID collisions
within their application and when deciding between UUID versions that
use entropy (random) versus the other components such as Section 6.1
and Section 6.2. This is especially true for distributed node
collision resistance as defined by Section 6.3.
There are two example scenarios below which help illustrate the
varying seriousness of a collision within an application.
Low Impact
A UUID collision generated a duplicate log entry which results in
incorrect statistics derived from the data. Implementations that
are not negatively affected by collisions may continue with the
entropy and uniqueness provided by the traditional UUID format.
High Impact:
A duplicate key causes an airplane to receive the wrong course
which puts people's lives at risk. In this scenario there is no
margin for error. Collisions MUST be avoided and failure is
unacceptable. Applications dealing with this type of scenario
MUST employ as much collision resistance as possible within the
given application context.
6.5. Global and Local Uniqueness
UUIDs created by this specification MAY be used to provide local
uniqueness guarantees. For example, ensuring UUIDs created within a
local application context are unique within a database MAY be
sufficient for some implementations where global uniqueness outside
of the application context, in other applications, or around the
world is not required.
Although true global uniqueness is impossible to guarantee without a
shared knowledge scheme; a shared knowledge scheme is not required by
UUID to provide uniqueness guarantees. Implementations MAY implement
a shared knowledge scheme introduced in Section 6.3 as they see fit
to extend the uniqueness guaranteed this specification and [RFC4122].