229 lines
6.7 KiB
Markdown
229 lines
6.7 KiB
Markdown
# Semantic Convention YAML Language
|
|
|
|
First, the syntax with a pseudo [EBNF](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form) grammar is presented.
|
|
Then, the semantic of each field is described.
|
|
|
|
## Syntax
|
|
|
|
All attributes are lower case.
|
|
|
|
```bnf
|
|
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"
|
|
| "number"
|
|
| "boolean"
|
|
| "string[]"
|
|
| "number[]"
|
|
| "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 strings literals are:
|
|
* "string": String attributes.
|
|
* "number": Numeric attributes.
|
|
* "boolean": Boolean attributes.
|
|
* "string[]": Array of strings attributes.
|
|
* "number[]": Array of numbers attributes.
|
|
* "boolean[]": Array of booleans attributes.
|
|
- `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:
|
|
|
|
```yaml
|
|
examples: 'this is a single string'
|
|
```
|
|
|
|
or
|
|
|
|
```yaml
|
|
examples: ['this is a single string']
|
|
```
|
|
|
|
or
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
examples:
|
|
- ['this is an error']
|
|
|
|
examples: [['this is an error']]
|
|
```
|
|
|
|
Multiple example values for a string attribute:
|
|
|
|
```yaml
|
|
examples: ['this is a single string', 'this is another one']
|
|
```
|
|
|
|
or
|
|
|
|
```yaml
|
|
examples:
|
|
- 'this is a single string'
|
|
- 'this is another one'
|
|
```
|
|
|
|
A single example value for an array of strings attribute:
|
|
|
|
```yaml
|
|
examples: ['first element of first array', 'second element of first array']
|
|
```
|
|
|
|
or
|
|
|
|
```yaml
|
|
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:
|
|
|
|
```yaml
|
|
examples: 'this is an error'
|
|
```
|
|
|
|
Multiple example values for an array of string attribute:
|
|
|
|
```yaml
|
|
examples: [ ['first element of first array', 'second element of first array'], ['first element of second array', 'second element of second array'] ]
|
|
```
|
|
|
|
or
|
|
|
|
```yaml
|
|
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, number, boolean, array of strings, array of numbers,
|
|
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, number, 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.
|