Update details about event.data SHOULD only be used for schema define…

…d values.

specification/logs/event-api.md

@@ -56,9 +56,15 @@ This function MAY be named `logEvent`.
   to not override or delete this attribute while the Event is emitted to
   preserve its identity.
 * `event_data` - this argument should of type [`Attributes`](../common/README.md#attribute)
-  and MUST recorded as a `LogRecod` attribute with the key `event.data`.
-* `other_attributes` - this argument should of type [`Attributes`](../common/README.md#attribute)
-  and MUST recorded as attributes on the `LogRecod`. Care MUST be taken by the
+  and MUST only contain the values as defined by the defined domain-specific schema
+  for the `event` (identified by the event domain + name combination) and is
+  recorded as a `LogRecod` attribute with the key `event.data`. It is optional to
+  support simple ping style events which do not require any form of payload, when
+  a payload is required `events` SHOULD provide a `event_data` and not simply use
+  `other_attributes` as a replacement.
+* `other_attributes` - this argument is used to provide additional context about
+  an `event`, it should of type [`Attributes`](../common/README.md#attribute)
+  and MUST be recorded as attributes on the `LogRecod`. Care MUST be taken by the
   implementation to not override already recorded attributes with names
   `event.name`, `event.domain` and `event.data`.
 
@@ -72,3 +78,10 @@ after making the following changes:
   when [creating the EventLogger](#create-eventlogger) MUST be set as
   the `event.domain` attribute on the `logRecord`.
 * The `event_name` MUST be set as the `event.name` attribute on the `logRecord`.
+* The `event_data` if provided MUST be set as the `event.data` attribute on the
+ `logRecord`. Validation of the domain-specific contents of the `event_data` is
+  optional and not required at the API level, as validation SHOULD occur downstream
+  of the API.
+* `other_attributes` should be optional and is only provided to enable additional
+  context about an `event` it is NOT a replacement for payload of an event which
+  is represented by the contents of `event.data`.

specification/logs/semantic_conventions/events.md

@@ -26,38 +26,82 @@ such that the name identifies the event structurally. It is also recommended tha
 the event names have low-cardinality, so care must be taken to use fields
 that identify the class of Events but not the instance of the Event.
 
-Events MAY include domain-specific information about the occurrence (`payload`)
-of the `event`, when present this information MUST be included in the `event.data`
-attribute the values included SHOULD conform to the domain-specific defined schema
-for the identified `event`. This is the primary container for details about the
-`event`.
+The primary container for (`payload`) details describing an `event` SHOULD
+include the domain-specific information about the occurrence in the `event.data`
+attribute, where the definition of the values included SHOULD conform to the
+domain-specific schema. The schema SHOULD be identified by the `domain` and
+`name` combination.
 
-Events MAY also include one or more additional Attributes which can be used to
-provide additional context about the `event`, whether an Attribute is required
-or optional SHOULD be defined by the domain-specific schema definition of the
-`event`.
+The `event.data` MUST only include the values as defined by it's domain-specific
+schema, and if required one or more additional top-level Attributes MAY be added
+to provide additional context about the `event`, but these attitional Attributes
+SHOULD not be treated as a replacement for the details (`payload`) of the `event`.
+For custom (Non-OpenTelemetry / User / System defined) `events` SHOULD define
+their own domain-specific schema (domain + name combination) and include their
+payload in the `event.data`.
+
+This allows a standard processing model of an `event` as represented by a `LogRecord`
+so that systems MAY choose how to route, validate and/or process known `events`
+based on the domain-specific schema semantic-conventions for the `event.data`.
+For example, common known events MAY have special meaning or representation while
+unknown events are simply treated as generic custom events.
 
 | Attribute  | Type | Description  | Examples  | Requirement Level |
 |---|---|---|---|---|
 | `event.name` | string | The name identifies the event. | `click`; `exception` | Required |
 | `event.domain` | string | The domain identifies the business context for the events. [1] | `browser` | Required |
-| `event.data` | [any](../data-model.md#type-any) \| [map<string, any>](../data-model.md#type-mapstring-any) | The domain-specific `payload` of the `event` which provides details about the occurrence of the named event. | `{ connectStart: 100, connectEnd: 103, domainLookupStart: 80, domainLookupEnd: 90 }` | Optional |
+| `event.data` | [any](../data-model.md#type-any) \| [map<string, any>](../data-model.md#type-mapstring-any) | The domain-specific [2] `payload` of the `event` which provides details about the occurrence of the named event. | `{ connectStart: 100, connectEnd: 103, domainLookupStart: 80, domainLookupEnd: 90 }` | Optional [3] |
 
 **[1]:** Events across different domains may have same `event.name`, yet be
 unrelated events.
 
-`event.domain` has the following list of well-known values. If one of them applies, then the respective value MUST be used, otherwise a custom value MAY be used.
+`event.domain` has the following list of well-known values. If one of them applies,
+then the respective value MUST be used, otherwise a custom value MAY be used.
+To avoid clashes custom event domains SHOULD use a reversed internet domain name
+style [`com.github`, `com.example`]
 
 | Value  | Description |
 |---|---|
 | `browser` | Events from browser apps |
 | `device` | Events from mobile apps |
 | `k8s` | Events from Kubernetes |
 
-`event.data` contains the domain-specific information about the occurrence of the
-`event` (ie. the payload of the event). And may include details about the occurrence
-or data that was change (depending on the schema of the domain-specific named event)
+**[2]:** Each OpenTelemetry defined event will have it's own documented
+semantic-conventions for `event.data`, while custom events SHOULD define
+and document their own.
+
+`event.data` MUST only contain the values as defined by it's domain-specific
+schema which identifies information about the occurrence of the `event` (the
+`payload` of the event). Which may include details about the occurrence
+or data that was changed (depending on the schema of the domain-specific named
+event)
 
 The specification does not place any restriction on the fields or type of the
 information included in the `event.data` Attribute as it's contents SHOULD conform
 to the `schema` of the domain-specific event.
+
+**[3]:** `event.data` is optional to support simple events which do not require
+any form of payload, when a payload is required `events` SHOULD define a schema
+and include an `event.data` with the payload over adding a collection of top-level
+general Attributes.
+
+#### Possible Open [Experimental](../../document-status.md) Extensions
+
+- `event.data` schema versioning support, options include :-
+  - Defined at a higher OpenTelemetry level for Logs;
+  - Included as part of the `event.name`;
+  - Additional `event.schema` (Seems overkill for now);
+
+- User/Application provided custom data
+  - This is data that does not conform to any OpenTelemetry semantic conventions
+    and is purely user provided data that they want persisted with the event,
+    options include (with suggested names only):-
+  - Define an OpenTelemetry semantic convention Attribute for `user.data` which
+    would be un-validated / defined a nested Attributes (no-schema);
+  - Define an event specific semantic convention Attribute for `event.user_data`
+    which would also be an un-validated / defined nested Attributes (no-schema);
+  - Explicitly excluded, would be an Attribute within the `event.data` to
+    contain the same as this would overly complicate backend processing and could
+    cause a name clash within the `event.data` as some `event` schema(s) are
+    being defined in terms of existing external definitions (`browser`+`FetchTiming`
+    `event.data` is based on [W3C PerformanceResourceTiming](https://w3c.github.io/resource-timing/#sec-performanceresourcetiming) ).