YAML Model - Draft

yaml/allowed_syntax.md

@@ -0,0 +1,223 @@
+# 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] [sampling_relevant] [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 ::= "yes"
+         |   "conditional"
+
+sampling_relevant ::= boolean
+
+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 and all attributes defined in the specified semantic convention.
+- `span_kind`, optional enum, specifies the kind of the span.
+    Leaf semconv nodes (in the hierarchy tree) that do not have this field set will generate a warning.
+- `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 it set to "conditional", `note` is expected to contain a description of
+    the conditions under which the attribute is required.
+- `sampling_relevant`, optional boolean, specifies if it is relevant for sampling. It defaults to `false`.
+- `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.

yaml/span_attribute/faas.yaml

@@ -0,0 +1,108 @@
+groups:
+  - id: faas
+    prefix: faas
+    brief: >
+        This document defines how to describe an instance of a function that
+        runs without provisioning or managing of servers (also known as
+        serverless) with spans.
+    attributes:
+      - id: trigger
+        required: always
+        sampling_relevant: true
+        brief: 'Type of the trigger on which the function is executed.'
+        type:
+          allow_custom_values: false
+          members:
+            - id: datasource
+              value: 'datasource'
+              brief: 'A response to some data source operation such as a database or filesystem read/write.'
+            - id: http
+              value: 'http'
+              brief: 'To provide an answer to an inbound HTTP request'
+            - id: pubsub
+              value: 'pubsub'
+              brief: 'A function is set to be executed when messages are sent to a messaging system.'
+            - id: timer
+              value: 'timer'
+              brief: 'A function is scheduled to be executed regularly.'
+            - id: other
+              value: 'other'
+      - id: execution
+        type: string
+        brief: "The execution id of the current function execution."
+        examples: 'af9d5aa4-a685-4c5f-a22b-444f80b3cc28'
+  - id: faas.datasource
+    prefix: faas.document
+    extends: faas
+    brief: >
+      Semantic Convention for FaaS triggered as a response to some data
+      source operation such as a database or filesystem read/write.
+    attributes:
+      - id: collection
+        type: string
+        required: always
+        brief: 'The name of the source on which the triggering operation was performed.'
+        note: >
+          For example, in Cloud Storage or S3 corresponds to the bucket name,
+          and in Cosmos DB to the database name.
+        examples: ['myBucketName', 'myDbName']
+      - id: operation
+        required: always
+        type:
+          allow_custom_values: true
+          members:
+            - id: insert
+              value: 'insert'
+            - id: edit
+              value: 'edit'
+            - id: delete
+              value: 'delete'
+        brief: 'Describes the type of the operation that was performed on the data.'
+      - id: time
+        type: string
+        required: always
+        brief: >
+          A string containing the time when the data was accessed in the
+          [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
+          format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime).
+        examples: "2020-01-23T13:47:06Z"
+      - id: name
+        type: string
+        brief: 'The document name/table subjected to the operation.'
+        note: >
+          For example, in Cloud Storage or S3 is the name of
+          the file, and in Cosmos DB the table name.
+        examples: ["myFile.txt", "myTableName"]
+  - id: faas.http
+    extends: faas
+    brief: >
+      Semantic Convention for FaaS triggered as a response to some data
+      source operation such as a database or filesystem read/write.
+    constraints:
+      - include: http.server
+  - id: faas.pubsub
+    extends: faas
+    brief: >
+      Semantic Convention for FaaS set to be executed when messages are
+      sent to a messaging system.
+    constraints:
+      - include: messaging
+  - id: faas.timer
+    extends: faas
+    brief: >
+      Semantic Convention for FaaS scheduled to be executed regularly.
+    attributes:
+      - id: time
+        type: string
+        required: always
+        brief: >
+          A string containing the function invocation time in the
+          [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html)
+          format expressed in [UTC](https://www.w3.org/TR/NOTE-datetime).
+        examples: "2020-01-23T13:47:06Z"
+      - id: cron
+        type: string
+        brief: >
+           A string containing the schedule period as
+           [Cron Expression](https://docs.oracle.com/cd/E12058_01/doc/doc.1014/e12030/cron_expressions.htm).
+        examples: "0/5 * * * ? *"