Merge pull request #84 from uuid6/draft-03-phase-3

Draft 03 PR 3

draft-peabody-dispatch-new-uuid-format-03.html

@@ -12,7 +12,7 @@
  This document presents three new Universally Unique Identifier (UUID) formats.
        
        
- A common case for modern applications is to create a unique identifier for use as a primary key in a database table.
+ A common case for modern applications is to create a unique identifier for use as a database key.
  This identifier usually implements an embedded timestamp that is sortable using the monotonic creation time in the most significant bits. 
  In addition the identifier is highly collision resistant, difficult to guess, and provides minimal security attack surfaces.
  None of the existing UUID versions, including UUIDv1, fulfill each of these requirements in the most efficient possible way.
@@ -40,7 +40,7 @@
     setuptools 40.6.2
     six 1.15.0
 -->
-<link href="/tmp/xbPhdFAIsk.dir/draft-peabody-dispatch-new-uuid-format-03.xml" rel="alternate" type="application/rfc+xml">
+<link href="/tmp/h0xIfLwVNj.dir/draft-peabody-dispatch-new-uuid-format-03.xml" rel="alternate" type="application/rfc+xml">
 <link href="#copyright" rel="license">
 <style type="text/css">/*
 
@@ -1199,7 +1199,7 @@
 </tr></thead>
 <tfoot><tr>
 <td class="left">Peabody &amp; Davis</td>
-<td class="center">Expires 4 September 2022</td>
+<td class="center">Expires 5 September 2022</td>
 <td class="right">[Page]</td>
 </tr></tfoot>
 </table>
@@ -1215,12 +1215,12 @@
 <a href="https://www.rfc-editor.org/rfc/rfc4122" class="eref">4122</a> (if approved)</dd>
 <dt class="label-published">Published:</dt>
 <dd class="published">
-<time datetime="2022-03-03" class="published">3 March 2022</time>
+<time datetime="2022-03-04" class="published">4 March 2022</time>
     </dd>
 <dt class="label-intended-status">Intended Status:</dt>
 <dd class="intended-status">Standards Track</dd>
 <dt class="label-expires">Expires:</dt>
-<dd class="expires"><time datetime="2022-09-04">4 September 2022</time></dd>
+<dd class="expires"><time datetime="2022-09-05">5 September 2022</time></dd>
 <dt class="label-authors">Authors:</dt>
 <dd class="authors">
 <div class="author">
@@ -1238,7 +1238,7 @@ <h2 id="abstract"><a href="#abstract" class="selfRef">Abstract</a></h2>
 <p id="section-abstract-1">
  This document presents three new Universally Unique Identifier (UUID) formats.<a href="#section-abstract-1" class="pilcrow">¶</a></p>
 <p id="section-abstract-2">
- A common case for modern applications is to create a unique identifier for use as a primary key in a database table.
+ A common case for modern applications is to create a unique identifier for use as a database key.
  This identifier usually implements an embedded timestamp that is sortable using the monotonic creation time in the most significant bits. 
  In addition the identifier is highly collision resistant, difficult to guess, and provides minimal security attack surfaces.
  None of the existing UUID versions, including UUIDv1, fulfill each of these requirements in the most efficient possible way.
@@ -1263,7 +1263,7 @@ <h2 id="name-status-of-this-memo">
         time. It is inappropriate to use Internet-Drafts as reference
         material or to cite them other than as "work in progress."<a href="#section-boilerplate.1-3" class="pilcrow">¶</a></p>
 <p id="section-boilerplate.1-4">
-        This Internet-Draft will expire on 4 September 2022.<a href="#section-boilerplate.1-4" class="pilcrow">¶</a></p>
+        This Internet-Draft will expire on 5 September 2022.<a href="#section-boilerplate.1-4" class="pilcrow">¶</a></p>
 </section>
 </div>
 <div id="copyright">
@@ -1388,7 +1388,7 @@ <h2 id="name-copyright-notice">
                 <p id="section-toc.1-1.11.2.2.1"><a href="#appendix-A.2" class="xref">A.2</a>.  <a href="#name-creating-a-uuidv7e-value" class="xref">Creating a UUIDv7E Value</a></p>
 </li>
               <li class="compact toc ulBare ulEmpty" id="section-toc.1-1.11.2.3">
-                <p id="section-toc.1-1.11.2.3.1"><a href="#appendix-A.3" class="xref">A.3</a>.  <a href="#name-creating-a-uuidv7e-value-2" class="xref">Creating a UUIDv7E Value</a></p>
+                <p id="section-toc.1-1.11.2.3.1"><a href="#appendix-A.3" class="xref">A.3</a>.  <a href="#name-creating-a-uuidv8e-value" class="xref">Creating a UUIDv8E Value</a></p>
 </li>
             </ul>
 </li>
@@ -1433,10 +1433,10 @@ <h2 id="name-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 primary keys, file names, machine
+ including but not limited to database keys, file names, machine
  or system names, identifiers for transactions or other objects or processes.<a href="#section-1-1" class="pilcrow">¶</a></p>
 <p id="section-1-2">
- A specific use case for UUIDs which has gained popularity is as database primary keys.
+ A specific use case for UUIDs which has gained popularity is as database keys.
  The motivation for this stems primarily from the fact that applications
  are increasingly distributed in nature. Simplistic "auto increment" schemes
  with integers in sequence do not work well in a distributed system since the effort required to
@@ -1796,7 +1796,7 @@ <h3 id="name-variant-and-version-fields">
 <span id="name-new-uuid-variant-10xx-versi"></span><table class="center" id="table-2">
           <caption>
 <a href="#table-2" class="selfRef">Table 2</a>:
-<a href="#name-new-uuid-variant-10xx-versi" class="selfRef">New UUID variant 10xx versions</a>
+<a href="#name-new-uuid-variant-10xx-versi" class="selfRef">New UUID variant 10xx versions defined by this specification</a>
           </caption>
 <thead>
             <tr>
@@ -1859,15 +1859,15 @@ <h3 id="name-variant-and-version-fields">
               <td class="text-left" rowspan="1" colspan="1">1</td>
               <td class="text-left" rowspan="1" colspan="1">1</td>
               <td class="text-left" rowspan="1" colspan="1">1</td>
-              <td class="text-left" rowspan="1" colspan="1">7</td>
+              <td class="text-left" rowspan="1" colspan="1">7E</td>
               <td class="text-left" rowspan="1" colspan="1">Unix Epoch time-based UUID specified in this document.</td>
             </tr>
             <tr>
               <td class="text-left" rowspan="1" colspan="1">1</td>
               <td class="text-left" rowspan="1" colspan="1">0</td>
               <td class="text-left" rowspan="1" colspan="1">0</td>
               <td class="text-left" rowspan="1" colspan="1">0</td>
-              <td class="text-left" rowspan="1" colspan="1">8</td>
+              <td class="text-left" rowspan="1" colspan="1">8E</td>
               <td class="text-left" rowspan="1" colspan="1">Reserved for custom UUID formats specified in this document</td>
             </tr>
           </tbody>
@@ -2211,7 +2211,7 @@ <h3 id="name-monotonicity-and-counters">
           <dd class="break"></dd>
 <dt id="section-5.2-5.5">Fixed-Length Dedicated Counter Seeding:</dt>
           <dd style="margin-left: 1.5em" id="section-5.2-5.6">
- Implementations utilizing fixed-length counter bits SHOULD initialize the counter at zero to ensure the full bit-space is utilized and help avoid counter rollovers.<a href="#section-5.2-5.6" class="pilcrow">¶</a>
+ Implementations utilizing either fixed-length counter method MAY randomly initialize the counter with each new timestamp tick. However, when the timestamp has not incremented; the counter SHOULD be frozen and incremented by one. 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. A randomly seeded counter alongside Method 2 is more-or-less the same as Monotonic Random (Method 3). Implementations utilizing either fixed-length counter method MAY also choose to initialize the counter at zero to ensure the full bit-space is utilized and help avoid counter rollovers. This approach has less entropy and more guessibility but ensures the most of the counter bit space.<a href="#section-5.2-5.6" class="pilcrow">¶</a>
 </dd>
           <dd class="break"></dd>
 <dt id="section-5.2-5.7">Fixed-Length Dedicated Counter Length</dt>
@@ -2330,7 +2330,7 @@ <h3 id="name-sorting">
  As a result objects can much more easily be clustered together for better performance.  
  The real-world differences in this approach of index locality vs random data inserts can be quite large.<a href="#section-5.7-2" class="pilcrow">¶</a></p>
 <p id="section-5.7-3">
- UUIDs formats created by this specification SHOULD be Lexicographically sortable while in the textual representation..<a href="#section-5.7-3" class="pilcrow">¶</a></p>
+ UUIDs formats created by this specification SHOULD be Lexicographically sortable while in the textual representation.<a href="#section-5.7-3" class="pilcrow">¶</a></p>
 <p id="section-5.7-4">
  UUIDs created by this specification are crafted with big-ending byte order (network byte order) in mind. If Little-endian style is required a custom UUID format SHOULD be created using UUIDv8E.<a href="#section-5.7-4" class="pilcrow">¶</a></p>
 </section>
@@ -2364,12 +2364,7 @@ <h3 id="name-storing-uuids-opacity">
 </li>
         </ul>
 <p id="section-5.8-5">
- UUIDs SHOULD be treated as opaque values and implementations SHOULD NOT examine the bits in a UUID to whatever extent is possible.<a href="#section-5.8-5" class="pilcrow">¶</a></p>
-<p id="section-5.8-6">
- Where necessary, the version number can be extracted by first verifying the variant field bits 64 and 65 contain 1 and 0 respectively, and then extract the version from bits 48 through 51.
- UUID versions 7 and 8 can be identified by checking octet 8 for the values 0xE7 or 0xE8 respectively.
- The version number can then be used to inspect the remainder of the UUID according to the specification for that version.
- See <a href="#variant_and_version_fields" class="xref">Section 4.1</a> for more information on determining a UUID version based on the inspected variant bits.<a href="#section-5.8-6" class="pilcrow">¶</a></p>
+ UUIDs SHOULD be treated as opaque values and implementations SHOULD NOT examine the bits in a UUID to whatever extent is possible. However, where necessary inspectors please review <a href="#variant_and_version_fields" class="xref">Section 4.1</a> for more information on determining a UUID version based on the inspected variant bits.<a href="#section-5.8-5" class="pilcrow">¶</a></p>
 </section>
 </div>
 </section>
@@ -2628,8 +2623,8 @@ <h3 id="name-creating-a-uuidv7e-value">
 </div>
 <div id="creating_a_uuidv8_value">
 <section id="appendix-A.3">
-        <h3 id="name-creating-a-uuidv7e-value-2">
-<a href="#appendix-A.3" class="section-number selfRef">A.3. </a><a href="#name-creating-a-uuidv7e-value-2" class="section-name selfRef">Creating a UUIDv7E Value</a>
+        <h3 id="name-creating-a-uuidv8e-value">
+<a href="#appendix-A.3" class="section-number selfRef">A.3. </a><a href="#name-creating-a-uuidv8e-value" class="section-name selfRef">Creating a UUIDv8E Value</a>
         </h3>
 <p id="appendix-A.3-1">UUIDv8E will vary greatly from implementation to implementation. A good candidate use case for UUIDv8E is to embed exotic timestamps like the one found in this example which employs approximately 0.25 milliseconds and approximately 5 microseconds per timestamp tick as a 48 bit value.<a href="#appendix-A.3-1" class="pilcrow">¶</a></p>
 <span id="name-uuid8-function-in-c"></span><figure id="figure-9">