Define the shape of a event by encapsulating the payload in event.data.

.gitignore

@@ -29,5 +29,8 @@ internal/tools/bin
 node_modules/
 package-lock.json
 
+# Visual Studio
+.vs/
+
 # Visual Studio Code
 .vscode

specification/logs/event-api.md

@@ -80,15 +80,33 @@ This function MAY be named `logEvent`.
  attribute with the key `event.name`. Care MUST be taken by the implementation
  to not override or delete this attribute while the Event is emitted to
  preserve its identity.
-* `logRecord` - the [LogRecord](./data-model.md#log-and-event-record-definition) representing the Event.
+* `event_data` - this argument should of type [`Attributes`](../common/README.md#attribute)
+ 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`.
 
 **Implementation Requirements:**
 
-The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the `logRecord` to
-the `logger` specified when [creating the EventLogger](#create-eventlogger)
+The implementation MUST [emit](./bridge-api.md#emit-a-logrecord) the [`LogRecord`](./data-model.md#log-and-event-record-definition)
+to the `logger` specified when [creating the EventLogger](#create-eventlogger)
 after making the following changes:
 
 * The `event_domain` specified
  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,20 +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.
 
-<!-- semconv 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.
+
+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 [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 |
-<!-- endsemconv -->
+
+**[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) Issues / 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) ).