uuid: elaborate on the application behavior
1 files changed, 59 insertions(+), 6 deletions(-)

M proposed/uuid.md
M proposed/uuid.md +59 -6
@@ 18,8 18,23 @@ its internal representation possible.
 Definitions
 -----------
 
+Throughout this and any field definition documents, the key words "MUST",
+"MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT",
+"RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted
+as described in RFC 2119.
+
+Additionally, the following terms are used in this document:
+
+ADIF record
+    A set of ADIF fields delimited by the end-of-record tag as defined by
+    ADIF specification.
+
+QSO entry
+    An application-internal data about a QSO.  The format used by the
+    application is not relevant to this document.
+
 UUID
-    A version 4 UUID as defined by RFC 4122.
+    A UUID as defined by RFC 4122.
 
 
 Field Format: UUID

          
@@ 37,13 52,49 @@ The generated UUID MUST NOT be the nil U
 Application Behavior
 --------------------
 
-Records created in the application SHOULD be assigned a new UUID.
+The application MUST behave in a way that does not invalidate assumptions
+about UUID uniqueness and persistence.  These assumptions are:
+
+1. if the UUIDs of two QSO entries are the same, then it is the same QSO
+2. if the UUIDs are different then the entries are for different QSOs
+
+The rest of this section describes commonly encountered application
+operations to expand on the implications of these two assumptions.
+
+Importing an ADIF record: The application MUST import and persist the UUID
+from the ADIF record if a UUID is present.  If the ADIF record lacks a UUID,
+the application MAY generate a new UUID for the resulting QSO entry.
+
+Exporting a QSO entry: The application MUST include a `app_aaa_uuid` field
+in the generated ADIF record if the corresponding QSO entry has a UUID.  If
+the QSO entry lacks a UUID, the application MUST NOT include `app_aaa_uuid`
+in the ADIF record.
+
+Creating a new QSO entry: The application SHOULD assign a new UUID with a
+newly created QSO entry.
 
-Imported records SHOULD use the UUID present in data being imported.  If an
-imported record lacks a UUID, the application MAY generate one instead.
+Modifying an existing QSO entry: The application MUST NOT change the UUID of
+a QSO entry.  The application MAY assign a new UUID to a QSO entry without a
+UUID.
+
+Note that the application is permitted to assign UUIDs to QSO entries lazily
+(e.g., just prior to export).  However, these lazily generated UUIDs must be
+stored persistently in the QSO entries so that subsequent exports use the
+same UUIDs.
+
 
-During export, the application SHOULD output the UUID associated with each
-record.
+Compatibility
+-------------
+
+Existing applications should already be able to handle application-defined
+ADIF fields.  The addition of `app_aaa_uuid` should not cause them to fail
+to process the remainder of the ADIF file.
+
+However, application developers implementing this specification should be
+mindful of UUID-unaware applications potentially generating ADIF records
+that duplicate UUIDs.  Some applications generate multiple ADIF records from
+a single QSO entry because a field in the entry has multiple values.  A very
+common example of this is that POTA multi-park activations.
 
 
 Examples

          
@@ 59,6 110,8 @@ Examples
 References
 ----------
 
+RFC 2119: Key words for use in RFCs to Indicate Requirement Levels
+
 RFC 4122: A Universally Unique IDentifier (UUID) URN Namespace