|
| 1 | +# Semantic Convention YAML Language |
| 2 | + |
| 3 | +First, the syntax with a pseudo [EBNF](https://en.wikipedia.org/wiki/Extended_Backus-Naur_form) grammar is presented. |
| 4 | +Then, the semantic of each field is described. |
| 5 | + |
| 6 | +## Syntax |
| 7 | + |
| 8 | +All attributes are lower case. |
| 9 | + |
| 10 | +```bnf |
| 11 | +groups ::= semconv |
| 12 | + | semconv groups |
| 13 | +
|
| 14 | +semconv ::= id brief [note] [prefix] [extends] [span_kind] attributes [constraints] |
| 15 | +
|
| 16 | +id ::= string |
| 17 | +brief ::= string |
| 18 | +note ::= string |
| 19 | +
|
| 20 | +prefix ::= string |
| 21 | +
|
| 22 | +# extends MUST point to an existing semconv id |
| 23 | +extends ::= string |
| 24 | +
|
| 25 | +span_kind ::= "client" |
| 26 | + | "server" |
| 27 | + | "producer" |
| 28 | + | "consumer" |
| 29 | + | "internal" |
| 30 | +
|
| 31 | +attributes ::= (id type brief examples | ref [brief] [examples]) [required] [note] |
| 32 | +
|
| 33 | +# ref MUST point to an existing attribute id |
| 34 | +ref ::= id |
| 35 | +
|
| 36 | +type ::= "string" |
| 37 | + | "number" |
| 38 | + | "boolean" |
| 39 | + | "string[]" |
| 40 | + | "number[]" |
| 41 | + | "boolean[]" |
| 42 | + | enum |
| 43 | +
|
| 44 | +enum ::= [allow_custom_values] members |
| 45 | +
|
| 46 | +allow_custom_values := boolean |
| 47 | +
|
| 48 | +members ::= member {member} |
| 49 | +
|
| 50 | +member ::= id value [brief] [note] |
| 51 | +
|
| 52 | +required ::= "always" |
| 53 | + | "conditional" <condition> |
| 54 | +
|
| 55 | +examples ::= <example_value> {<example_value>} |
| 56 | +
|
| 57 | +constraints ::= constraint {constraint} |
| 58 | +
|
| 59 | +constraint ::= any_of |
| 60 | + | include |
| 61 | +
|
| 62 | +any_of ::= id {id} |
| 63 | +
|
| 64 | +include ::= id |
| 65 | +
|
| 66 | +``` |
| 67 | + |
| 68 | +## Semantics |
| 69 | + |
| 70 | +### Groups |
| 71 | + |
| 72 | +Groups contain the list of semantic conventions and it is the root node of each yaml file. |
| 73 | + |
| 74 | +### Semantic Convention |
| 75 | + |
| 76 | +The field `semconv` represents a semantic convention and it is made by: |
| 77 | + |
| 78 | +- `id`, string that uniquely identifies the semantic convention. |
| 79 | +- `brief`, string, a brief description of the semantic convention. |
| 80 | +- `note`, optional string, a more elaborate description of the semantic convention. |
| 81 | + It defaults to an empty string. |
| 82 | +- `prefix`, optional string, prefix for the attributes for this semantic convention. |
| 83 | + It defaults to an empty string. |
| 84 | +- `extends`, optional string, reference another semantic convention `id`. |
| 85 | + It inherits the prefix, constraints, and all attributes defined in the specified semantic convention. |
| 86 | +- `span_kind`, optional enum, specifies the kind of the span. |
| 87 | +- `attributes`, list of attributes that belong to the semantic convention. |
| 88 | +- `constraints`, optional list, additional constraints (See later). It defaults to an empty list. |
| 89 | + |
| 90 | +### Attributes |
| 91 | + |
| 92 | +An attribute is defined by: |
| 93 | + |
| 94 | +- `id`, string that uniquely identifies the attribute. |
| 95 | +- `type`, either a string literal denoting the type or an enum definition (See later). |
| 96 | + The accepted strings literals are: |
| 97 | + * "string": String attributes. |
| 98 | + * "number": Numeric attributes. |
| 99 | + * "boolean": Boolean attributes. |
| 100 | + * "string[]": Array of strings attributes. |
| 101 | + * "number[]": Array of numbers attributes. |
| 102 | + * "boolean[]": Array of booleans attributes. |
| 103 | +- `ref`, optional string, reference an existing attribute, see later. |
| 104 | +- `required`, optional, specifies if the attribute is mandatory. |
| 105 | + Can be "always", or "conditional". When omitted, the attribute is not required. |
| 106 | + When set to "conditional",the string provided as `<condition>` MUST specify |
| 107 | + the conditions under which the attribute is required. |
| 108 | +- `brief`, string, brief description of the attribute. |
| 109 | +- `note`, optional string, additional notes to the attribute. It defaults to an empty string. |
| 110 | +- `examples`, sequence/dictionary of example values for the attribute. |
| 111 | + They are optional for boolean and enum attributes. |
| 112 | + Example values must be of the same type of the attribute. |
| 113 | + If only a single example is provided, it can directly be reported without encapsulating it into a sequence/dictionary. |
| 114 | + |
| 115 | +Examples for setting the `examples` field: |
| 116 | + |
| 117 | +A single example value for a string attribute. All the following three representations are equivalent: |
| 118 | + |
| 119 | +```yaml |
| 120 | +examples: 'this is a single string' |
| 121 | +``` |
| 122 | +
|
| 123 | +or |
| 124 | +
|
| 125 | +```yaml |
| 126 | +examples: ['this is a single string'] |
| 127 | +``` |
| 128 | +
|
| 129 | +or |
| 130 | +
|
| 131 | +```yaml |
| 132 | +examples: |
| 133 | + - 'this is a single string' |
| 134 | +``` |
| 135 | +
|
| 136 | +Attention, the following will throw a type mismatch error because a string type as example value is expected and not an array of string: |
| 137 | +
|
| 138 | +```yaml |
| 139 | +examples: |
| 140 | + - ['this is an error'] |
| 141 | + |
| 142 | +examples: [['this is an error']] |
| 143 | +``` |
| 144 | +
|
| 145 | +Multiple example values for a string attribute: |
| 146 | +
|
| 147 | +```yaml |
| 148 | +examples: ['this is a single string', 'this is another one'] |
| 149 | +``` |
| 150 | +
|
| 151 | +or |
| 152 | +
|
| 153 | +```yaml |
| 154 | +examples: |
| 155 | + - 'this is a single string' |
| 156 | + - 'this is another one' |
| 157 | +``` |
| 158 | +
|
| 159 | +A single example value for an array of strings attribute: |
| 160 | +
|
| 161 | +```yaml |
| 162 | +examples: ['first element of first array', 'second element of first array'] |
| 163 | +``` |
| 164 | +
|
| 165 | +or |
| 166 | +
|
| 167 | +```yaml |
| 168 | +examples: |
| 169 | + - ['first element of first array', 'second element of first array'] |
| 170 | +``` |
| 171 | +
|
| 172 | +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: |
| 173 | +
|
| 174 | +```yaml |
| 175 | +examples: 'this is an error' |
| 176 | +``` |
| 177 | +
|
| 178 | +Multiple example values for an array of string attribute: |
| 179 | +
|
| 180 | +```yaml |
| 181 | +examples: [ ['first element of first array', 'second element of first array'], ['first element of second array', 'second element of second array'] ] |
| 182 | +``` |
| 183 | +
|
| 184 | +or |
| 185 | +
|
| 186 | +```yaml |
| 187 | +examples: |
| 188 | + - ['first element of first array', 'second element of first array'] |
| 189 | + - ['first element of second array', 'second element of second array'] |
| 190 | +``` |
| 191 | +
|
| 192 | +### Ref |
| 193 | +
|
| 194 | +`ref` MUST have an id of an existing attribute. When it is set, `id` and `type` MUST not be present. |
| 195 | +`ref` is useful for specifying that an existing attribute of another semantic convention is part of |
| 196 | +the current semantic convention and inherit its `brief`, `note`, and `example` values. However, if these |
| 197 | +fields are present in the current attribute definition, they override the inherited values. |
| 198 | + |
| 199 | +### Type |
| 200 | + |
| 201 | +An attribute type can either be a string, number, boolean, array of strings, array of numbers, |
| 202 | +array of booleans, or an enumeration. If it is an enumeration, additional fields are required: |
| 203 | + |
| 204 | +- `allow_custom_values`, optional boolean, set to false to not accept values |
| 205 | + other than the specified members. It defaults to `true`. |
| 206 | +- `members`, list of enum entries. |
| 207 | + |
| 208 | +An enum entry has the following fields: |
| 209 | + |
| 210 | +- `id`, string that uniquely identifies the enum entry. |
| 211 | +- `value`, string, number, or boolean, value of the enum entry. |
| 212 | +- `brief`, optional string, brief description of the enum entry value. It defaults to the value of `id`. |
| 213 | +- `note`, optional string, longer description. It defaults to an empty string. |
| 214 | + |
| 215 | +### Constraints |
| 216 | + |
| 217 | +Allow to define additional requirements on the semantic convention. |
| 218 | +Currently, it supports `any_of` and `include`. |
| 219 | + |
| 220 | +#### Any Of |
| 221 | + |
| 222 | +`any_of` accepts a list of sequences. Each sequence contains a list of attribute ids that are required. |
| 223 | +`any_of` enforces that all attributes of at least one of the sequences are set. |
| 224 | + |
| 225 | +#### Include |
| 226 | + |
| 227 | +`include` accepts a semantic conventions `id`. It includes as part of this semantic convention all constraints |
| 228 | +and required attributes that are not already defined in the current semantic convention. |
0 commit comments