Skip to content

Latest commit

 

History

History
235 lines (164 loc) · 6.89 KB

syntax.md

File metadata and controls

235 lines (164 loc) · 6.89 KB

Semantic Convention YAML Language

First, the syntax with a pseudo EBNF grammar is presented. Then, the semantic of each field is described.

Syntax

All attributes are lower case.

groups ::= semconv
       | semconv groups

semconv ::= id brief [note] [prefix] [extends] [span_kind] attributes [constraints]

id    ::= string
brief ::= string
note  ::= string

prefix ::= string

# extends MUST point to an existing semconv id
extends ::= string

span_kind ::= "client"
          |   "server"
          |   "producer"
          |   "consumer"
          |   "internal"

attributes ::= (id type brief examples | ref [brief] [examples]) [required] [note]

# ref MUST point to an existing attribute id
ref ::= id

type ::= "string"
     |   "int"
     |   "double"
     |   "boolean"
     |   "string[]"
     |   "int[]"
     |   "double[]"
     |   "boolean[]"
     |   enum

enum ::= [allow_custom_values] members

allow_custom_values := boolean

members ::= member {member}

member ::= id value [brief] [note]

required ::= "always"
         |   "conditional" <condition>

examples ::= <example_value> {<example_value>}

constraints ::= constraint {constraint}

constraint ::= any_of
           |   include

any_of ::= id {id}

include ::= id

Semantics

Groups

Groups contain the list of semantic conventions and it is the root node of each yaml file.

Semantic Convention

The field semconv represents a semantic convention and it is made by:

  • id, string that uniquely identifies the semantic convention.
  • brief, string, a brief description of the semantic convention.
  • note, optional string, a more elaborate description of the semantic convention. It defaults to an empty string.
  • prefix, optional string, prefix for the attributes for this semantic convention. It defaults to an empty string.
  • extends, optional string, reference another semantic convention id. It inherits the prefix, constraints, and all attributes defined in the specified semantic convention.
  • span_kind, optional enum, specifies the kind of the span.
  • attributes, list of attributes that belong to the semantic convention.
  • constraints, optional list, additional constraints (See later). It defaults to an empty list.

Attributes

An attribute is defined by:

  • id, string that uniquely identifies the attribute.

  • type, either a string literal denoting the type or an enum definition (See later). The accepted string literals are:

    • "string": String attributes.
    • "int": Integer attributes.
    • "double": Double attributes.
    • "boolean": Boolean attributes.
    • "string[]": Array of strings attributes.
    • "int[]": Array of integer attributes.
    • "double[]": Array of double attributes.
    • "boolean[]": Array of booleans attributes.

    See the specification of Attributes for the definition of the value types.

  • ref, optional string, reference an existing attribute, see later.

  • required, optional, specifies if the attribute is mandatory. Can be "always", or "conditional". When omitted, the attribute is not required. When set to "conditional",the string provided as <condition> MUST specify the conditions under which the attribute is required.

  • brief, string, brief description of the attribute.

  • note, optional string, additional notes to the attribute. It defaults to an empty string.

  • examples, sequence/dictionary of example values for the attribute. They are optional for boolean and enum attributes. Example values must be of the same type of the attribute. If only a single example is provided, it can directly be reported without encapsulating it into a sequence/dictionary.

Examples for setting the examples field:

A single example value for a string attribute. All the following three representations are equivalent:

examples: 'this is a single string'

or

examples: ['this is a single string']

or

examples:
   - 'this is a single string'

Attention, the following will throw a type mismatch error because a string type as example value is expected and not an array of string:

examples:
   - ['this is an error']

examples: [['this is an error']]

Multiple example values for a string attribute:

examples: ['this is a single string', 'this is another one']

or

examples:
   - 'this is a single string'
   - 'this is another one'

A single example value for an array of strings attribute:

examples: ['first element of first array', 'second element of first array']

or

examples:
   - ['first element of first array', 'second element of first array']

Attention, the following will throw a type mismatch error because an array of strings as type for the example values is expected and not a string:

examples: 'this is an error'

Multiple example values for an array of string attribute:

examples: [ ['first element of first array', 'second element of first array'], ['first element of second array', 'second element of second array'] ]

or

examples:
   - ['first element of first array', 'second element of first array']
   - ['first element of second array', 'second element of second array']

Ref

ref MUST have an id of an existing attribute. When it is set, id and type MUST NOT be present. ref is useful for specifying that an existing attribute of another semantic convention is part of the current semantic convention and inherit its brief, note, and example values. However, if these fields are present in the current attribute definition, they override the inherited values.

Type

An attribute type can either be a string, int, double, boolean, array of strings, array of int, array of double, array of booleans, or an enumeration. If it is an enumeration, additional fields are required:

  • allow_custom_values, optional boolean, set to false to not accept values other than the specified members. It defaults to true.
  • members, list of enum entries.

An enum entry has the following fields:

  • id, string that uniquely identifies the enum entry.
  • value, string, int, or boolean; value of the enum entry.
  • brief, optional string, brief description of the enum entry value. It defaults to the value of id.
  • note, optional string, longer description. It defaults to an empty string.

Constraints

Allow to define additional requirements on the semantic convention. Currently, it supports any_of and include.

Any Of

any_of accepts a list of sequences. Each sequence contains a list of attribute ids that are required. any_of enforces that all attributes of at least one of the sequences are set.

Include

include accepts a semantic conventions id. It includes as part of this semantic convention all constraints and required attributes that are not already defined in the current semantic convention.