Add the concept of reference attributes to the spec

.chloggen/attribute_references.yaml

@@ -0,0 +1,4 @@
+change_type: enhancement
+component: specification
+note: Defines "reference attribute" concept
+issues: [1428]

docs/general/attribute-naming.md

@@ -46,17 +46,20 @@ Names SHOULD follow these rules:
   indicate entity hierarchies. This purpose should primarily drive the decision
   about forming nested namespaces.
 
+- The special namespace `*.blob_ref.*` is reserved for "reference attributes".
+
 - For each multi-word dot-delimited component of the attribute name separate the
   words by underscores (i.e. use snake_case). For example
   `http.response.status_code` denotes the status code in the http namespace.
 
 - Names SHOULD NOT coincide with namespaces. For example if
-  `service.instance.id` is an attribute name then it is no longer valid to have
-  an attribute named `service.instance` because `service.instance` is already a
+  `service.instance.id` is an attribute name, then it is no longer valid to have
+  an attribute named `service.instance`, because `service.instance` is already a
   namespace. Because of this rule be careful when choosing names: every existing
   name prohibits existence of an equally named namespace in the future, and vice
   versa: any existing namespace prohibits existence of an equally named
-  attribute key in the future.
+  attribute key in the future. Note that "reference attributes" are exempt
+  from this rule, because they are/replace the original attribute.
 
 ## Name Pluralization Guidelines
 
@@ -173,5 +176,31 @@ and protocols.
 Any additions to the `otel.*` namespace MUST be approved as part of
 OpenTelemetry specification.
 
+## Reference Attributes
+
+A "reference attribute" is a set of derived attribute names that are used to
+provide the value of an attribute indirectly via a URI reference to a storage
+system where the value of the attribute may be retrieved.
+
+In general, if there exists an attribute `somekey`, then there is implicitly
+defined another attribute `somekey.blob_ref.uri` which may be used to provide
+the value of the attribute `somekey` by reference to an external storage
+system from which the value of `somekey` may be fetched.
+
+Additional `*.blob_ref.*` attributes, beyond `.blob_ref.uri`, may be used to
+provide additional information concerning the external reference, including:
+
+  - `*.blob_ref.content_type`: the MIME type of the data (e.g. `text/plain`, `application/json`, `application/octet-stream`)
+  - `*.blob_ref.size`: the size of the attribute value in bytes
+  - `*.blob_ref.hash_value`: a hash of the data for validation
+  - `*.blob_ref.hash_algorithm`: the algorithm used to compute the hash
+
+If both a reference attribute and its non-reference variant appear together
+within a signal (e.g. both `somekey` and `somekey.blob_ref.uri` are present),
+it should be assumed that only the reference attribute references the full,
+complete, original value of the data; the non-reference variant may be used
+to preview/summarize the data but should be assumed to potentially contain
+a modified, truncated, redacted, or otherwise non-original value within it.
+
 [DocumentStatus]:
   https://opentelemetry.io/docs/specs/otel/document-status

docs/general/events.md

@@ -98,6 +98,15 @@ Recommendations on using attributes vs. body fields:
   * The _fields_ are unique to the named event (`event.name`) and different events
     may use the same _field_ name to represent different data, due to the unique
     nature of the event.
+  * The _fields_ SHOULD NOT use the `*.blob_ref.*` name, except when applying the
+    same principle/data model as "attribute references" but in relation to
+    event fields (e.g. using `somefield.blob_ref.uri` to relay the value of the
+    field `somefield` via indirection to an external storage system).
+  * For any _field_ name `somefield`, there exist a set of corresponding
+    fields `somefield.blob_ref.*` that may be used to relay the value of
+    `somefield` via reference to an external storage system, following the same
+    rules as "attribute references" as outlined in the attribute naming
+    conventions.
 
 ## External event compatibility