What are you trying to achieve?

With the definition of Events storing their payload into the Log Body as defined in Semantic Conventions and as part of the Event Api there is a need to identify "how" the payload is described and encoded so that implementers and downstream consumers have a deterministic method of defining, decoding, processing and possible validating the content.

Therefore, we need to have a consistent way to describe the Log body.

There are 2 levels of definition that need to be considered, this issue will only focus on the Data Modeling of the body and not the transport encoding.

• Data Model: How is the body described in semantic conventions from a data model perspective for yaml, code generation and documentation
• Transport Encoding: How are the values encoded (with deterministic context) in the body of the Log
  • As this issue along could be quite large, I will assume the default position is as defined by Logs and the OTLP protocol as explicitly identifying the encoding does not necessarily need to be part of the data model.
  • And I would suggested that encoding should be discussed as part of a separate issue as it is a complex topic that will require a lot of discussion and agreement.

As the body is defined as an <any> we need to define how the body will be described in yaml and ultimately encoded for transportation.

Data Model

The body of a Log is defined as a value of type <any> which means that it can be a complex type that needs to be described in a consistent manner.

The following are some possible yaml representations for the body of a Log describing the expected content of the contents that will be included. These is based on the assumption that the body is a single value that can be described as a map<string, any>, array<any>, <scalar value> or a <byte array>.

Basic Modeling Rules

• Every body definition is unique only to the encompassing Semantic Convention that is declaring it.
• There will be no id assigned to the body definition, as it cannot be shared with other Data Models.
• Different body definitions may define the same or similar structure, but they will be considered to be unique to the encompassing Semantic Convention.

Extensions to theses basic modeling rules will be defined for each of the possible body definitions and can be extended in future releases of the specification if required.

map< string, any >

Additional Modeling Rules

• A body definition may have multiple field definitions.
• Each field definition within the body definition is unique to the encompassing body definition and may include an id that is unique to the body definition only.
• Any "fields" defined within the body definition are not global and are not available outside of their declared body definition. ie. They are not part of the global semantic conventions attributes.
• Fields within different body definitions may re-use the same id as they are unique to the encompassing body definition only, are not global and should not be considered as the same field definition.
• Any id defined within the body definition SHOULD not repeated withing the same fields definition.

body:
  fields:
    - id: <id>
      type: <type>
      brief: <brief>
      note: <note>
      examples: [<examples>]
    - id: <id>
      type: <type>
      brief: <brief>
      note: <note>
      examples: [<examples>]

Where fields is a list of field definitions where each field has an id that represents the key of the map and is described in the same manner as an Attribute with the biggest difference that the described fields are NOT added to the global semantic conventions attributes but are instead associated with the body of the encompassing Log.

Examples of using fields in a full semantic convention definition can be found in the Build tools draft PR to add log_event support

• yaml: Simple single field with generated markdown
• yaml: Simple single field with attributes with generated markdown
• yaml: Multiple fields with constraibts with generated markdown

This is the primary proposal for the event working group to support defining the body of an event in a consistent manner, so that it can be used for code generation, documentation and validation.

Open Questions

• Should Nested fields be allowed? ie. map<string, <any>> within the fields definition.
• Should the initial definition be that a map<string, <any>>, should the <any> be limited to not support nesting (map<string, <any>>) or do we allow the values to be encoded based on the identified "standard".
  • If nesting is allowed, there should also be a recommended defined "depth" for this nested.

array< any >

For completeness to describe the support OTLP protocol, it is possible to have an array of values as the body of a Log. This would be a list of values that are of type <any>.

body:
  array:
    brief: <brief>
    note: <note>
    examples: [<examples>]

Where array represents that there will be an unspecified list of values of type <any>, while it would contain the detail fields of an Attribute (brief, note, examples, etc) it would NOT provide an id. As the
array would assume to be numeric index based. Specific example will be required to identify if there are any specific "fields" that are expected to be present in the array. Like min/max length, min/max values, etc.

Open Question

• How or do we want to define the types of values that may be present in the array, along with additional attributes (Like min/max length, min/max values, etc).

scalar value

Also For completeness to describe the support OTLP protocol, it is possible to have an array of values as the body of a Log. This would be a list of values that are of type <any>.

body: 
  value:
    type: <type>
    brief: <brief>
    note: <note>
    examples: [<examples>]

Where <value> is described in the same manner as an Attribute and as with the array it would not include the id (key).

byte array

Also For completeness to describe the support OTLP protocol, it is possible to have an array of values as the body of a Log. This would be a list of values that are of type <any>.

This could also be rolled into the value definition as a type of binary but it may be better to have it as a separate definition to make it clear that the value is a binary blob.

body:
  binary:
    brief: <brief>
    note: <note>
    examples: [<examples>]

Where binary is described in the same manner as an Attribute and as with the array it would not include the id (key).