From 636a64acebffda7f9ef89410484af205bd404dbd Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Wed, 7 Aug 2024 21:32:55 -0700 Subject: [PATCH 1/3] update schema and syntax --- semantic-conventions/semconv.schema.json | 136 ++++++++++++++++------- semantic-conventions/syntax.md | 35 ++---- 2 files changed, 105 insertions(+), 66 deletions(-) diff --git a/semantic-conventions/semconv.schema.json b/semantic-conventions/semconv.schema.json index a22365c8..a4d89018 100644 --- a/semantic-conventions/semconv.schema.json +++ b/semantic-conventions/semconv.schema.json @@ -1,5 +1,5 @@ { - "$schema": "http://json-schema.org/draft-07/schema#", + "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "description": "YAML schema for semantic convention generator, use for example with VS Code.", "additionalProperties": false, @@ -9,27 +9,44 @@ "items": { "anyOf": [ { - "allOf": [{"$ref": "#/definitions/SemanticConvention"}] + "allOf": [ + { + "$ref": "#/$defs/SemanticConvention" + } + ] }, { - "allOf": [{"$ref": "#/definitions/SpanSemanticConvention"}] + "allOf": [ + { + "$ref": "#/$defs/SpanSemanticConvention" + } + ] }, { - "allOf": [{"$ref": "#/definitions/EventSemanticConvention"}] + "allOf": [ + { + "$ref": "#/$defs/EventSemanticConvention" + } + ] }, { - "allOf": [{"$ref": "#/definitions/MetricSemanticConvention"}] + "allOf": [ + { + "$ref": "#/$defs/MetricSemanticConvention" + } + ] } ] } } }, - "definitions": { + "$defs": { "SemanticConventionBase": { "type": "object", "required": [ "id", - "brief" + "brief", + "stability" ], "anyOf": [ { @@ -67,29 +84,40 @@ "type": "string", "description": "a more elaborate description of the semantic convention. It defaults to an empty string" }, - "prefix": { - "type": "string", - "description": "prefix of the attribute for this semconv. It defaults to an empty string." - }, "extends": { "type": "string", - "description": "reference another semantic convention ID. It inherits all attributes from the specified semconv." + "description": "reference another semantic convention ID. It inherits all attributes from the specified semantic convention." }, "attributes": { "type": "array", "items": { - "$ref": "#/definitions/Attribute" + "$ref": "#/$defs/Attribute" }, - "description": "list of attributes that belong to the semconv" + "description": "list of attributes that belong to the semantic convention" }, "display_name": { "type": "string", "description": "the display name / title of the attribute group." + }, + "deprecated": { + "type": "string", + "description": "specifies if the attribute is deprecated. The string provided as MUST specify why it's deprecated and/or what to use instead." + }, + "stability": { + "allOf": [ + { + "$ref": "#/$defs/StabilityLevel" + } + ] } } }, "SpanSemanticConvention": { - "allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }], + "allOf": [ + { + "$ref": "#/$defs/SemanticConventionBase" + } + ], "properties": { "type": { "type": "string", @@ -104,12 +132,16 @@ "consumer", "internal" ], - "description": "specifies the kind of the span. Leaf semconv nodes (in the hierarchy tree) that do not have this field set will generate a warning." + "description": "specifies the kind of the span. Leaf semantic convention nodes (in the hierarchy tree) that do not have this field set will generate a warning." } } }, "EventSemanticConvention": { - "allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }], + "allOf": [ + { + "$ref": "#/$defs/SemanticConventionBase" + } + ], "properties": { "type": { "type": "string", @@ -117,16 +149,23 @@ }, "name": { "type": "string", - "description": "The name of the event. Required if no prefix is given." + "description": "The name of the event." } }, "anyOf": [ - {"required": ["prefix"]}, - {"required": ["name"]} + { + "required": [ + "name" + ] + } ] }, "MetricSemanticConvention": { - "allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }], + "allOf": [ + { + "$ref": "#/$defs/SemanticConventionBase" + } + ], "required": [ "type", "metric_name", @@ -159,13 +198,22 @@ } }, "SemanticConvention": { - "allOf": [{ "$ref": "#/definitions/SemanticConventionBase" }], - "required": ["type"], + "allOf": [ + { + "$ref": "#/$defs/SemanticConventionBase" + } + ], + "required": [ + "type" + ], "properties": { "type": { "type": "string", "not": { - "enum": ["span", "event"] + "enum": [ + "span", + "event" + ] } } } @@ -174,9 +222,6 @@ "type": "object", "additionalProperties": false, "properties": { - "allow_custom_values": { - "type": "boolean" - }, "members": { "type": "array", "items": { @@ -184,7 +229,8 @@ "additionalProperties": false, "required": [ "id", - "value" + "value", + "stability" ], "properties": { "id": { @@ -206,8 +252,16 @@ "type": "string", "description": "longer description. It defaults to an empty string." }, + "deprecated": { + "type": "string", + "description": "specifies if the attribute is deprecated. The string provided as MUST specify why it's deprecated and/or what to use instead." + }, "stability": { - "allOf": [{ "$ref": "#/definitions/StabilityLevel" }] + "allOf": [ + { + "$ref": "#/$defs/StabilityLevel" + } + ] } } } @@ -217,7 +271,8 @@ "AttributeFullSpec": { "required": [ "id", - "type" + "type", + "stability" ], "properties": { "id": { @@ -249,7 +304,7 @@ "description": "literal denoting the type" }, { - "$ref": "#/definitions/AttributeEnumType" + "$ref": "#/$defs/AttributeEnumType" } ] } @@ -362,30 +417,27 @@ }, "examples": { "anyOf": [ - { "$ref": "#/definitions/ValueType" }, + { + "$ref": "#/$defs/ValueType" + }, { "type": "array", - "items": { "$ref": "#/definitions/ValueType" } + "items": { + "$ref": "#/$defs/ValueType" + } } ], "description": "sequence/dictionary of example values for the attribute. They are optional for boolean, int, double, 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." - }, - "deprecated": { - "type": "string", - "description": "specifies if the attribute is deprecated. The string provided as MUST specify why it's deprecated and/or what to use instead." - }, - "stability": { - "allOf": [{ "$ref": "#/definitions/StabilityLevel" }] } } }, { "oneOf": [ { - "$ref": "#/definitions/AttributeFullSpec" + "$ref": "#/$defs/AttributeFullSpec" }, { - "$ref": "#/definitions/AttributeReference" + "$ref": "#/$defs/AttributeReference" } ] } diff --git a/semantic-conventions/syntax.md b/semantic-conventions/syntax.md index 15cdeb9b..97b3f4ce 100644 --- a/semantic-conventions/syntax.md +++ b/semantic-conventions/syntax.md @@ -40,7 +40,7 @@ All attributes are lower case. groups ::= semconv | semconv groups -semconv ::= id [convtype] brief [note] [prefix] [extends] [stability] [deprecated] attributes [specificfields] +semconv ::= id [convtype] brief [note] [extends] stability [deprecated] attributes [specificfields] id ::= string @@ -53,8 +53,6 @@ convtype ::= "span" # Default if not specified brief ::= string note ::= string -prefix ::= string - extends ::= string stability ::= "experimental" @@ -62,7 +60,7 @@ stability ::= "experimental" deprecated ::= -attributes ::= (id type brief examples | ref [brief] [examples]) [tag] [stability] [deprecated] [required] [sampling_relevant] [note] +attributes ::= (id type brief examples | ref [brief] [examples]) [tag] stability [deprecated] [required] [sampling_relevant] [note] # ref MUST point to an existing attribute id ref ::= id @@ -82,13 +80,11 @@ simple_type ::= "string" template_type ::= "template[" simple_type "]" # As a single string -enum ::= [allow_custom_values] members - -allow_custom_values := boolean +enum ::= members members ::= member {member} -member ::= id value [brief] [note] [stability] [deprecated] +member ::= id value [brief] [note] stability [deprecated] requirement_level ::= "required" | "conditionally_required" @@ -99,10 +95,6 @@ sampling_relevant ::= boolean examples ::= {} -any_of ::= id {id} - -include ::= id - specificfields ::= spanfields | eventfields | metricfields @@ -143,12 +135,11 @@ The field `semconv` represents a semantic convention and it is made by: - `id`, string that uniquely identifies the semantic convention. - `type`, optional enum, defaults to `span` (with a warning if not present). - `brief`, string, a brief description of the semantic convention. +- `stability`, required enum, either `stable` or `experimental`, specifies the stability of the attribute. - `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. + It inherits all attributes defined in the specified semantic convention. - `deprecated`, optional, when present marks the semantic convention as deprecated. The string provided as `` MUST specify why it's deprecated and/or what to use instead. - `attributes`, list of attributes that belong to the semantic convention. @@ -165,16 +156,14 @@ The following is only valid if `type` is `span` (the default): The following is only valid if `type` is `event`: -- `name`, conditionally required string. The name of the event. - If not specified, the `prefix` is used. If `prefix` is empty (or unspecified), - `name` is required. +- `name`, required, string. The name of the event. #### Metric Group semantic convention Metric group inherits all from the base semantic convention, and does not add any additional fields. -The metric group semconv is a group where related metric attributes +The metric group semantic convention is a group where related metric attributes can be defined and then referenced from other `metric` groups using `ref`. #### Metric semantic convention @@ -210,10 +199,10 @@ An attribute is defined by: * `"string[]"`: Array of strings attributes. * `"int[]"`: Array of integer attributes. * `"double[]"`: Array of double attributes. - * `"boolean[]"`: Array of booleans attributes. + * `"boolean[]"`: Array of boolean attributes. * _template type as string literal:_ `"template[]"` (See [below](#template-type)) See the [specification of Attributes](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/common/README.md#attribute) for the definition of the value types. -- `stability`, enum - either `stable` or `experimental`, specifies the stability of the attribute. Required. +- `stability`, required enum, either `stable` or `experimental`, specifies the stability of the attribute. - `ref`, optional string, reference an existing attribute, see [below](#ref). - `tag`, optional string, associates a tag ("sub-group") to the attribute. It carries no particular semantic meaning but can be used e.g. for filtering @@ -321,7 +310,7 @@ fields are present in the current attribute definition, they override the inheri #### Type An attribute type can either be a string, int, double, boolean, array of strings, array of int, array of double, -array of booleans, a template type or an enumeration. +array of boolean, a template type or an enumeration. ##### Template type @@ -355,8 +344,6 @@ In this example the definition will be resolved into a dictionary of attributes If the type 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: From 85e820d22f05831961827a1968eca6d470169e77 Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 8 Aug 2024 08:49:25 -0700 Subject: [PATCH 2/3] changelog --- semantic-conventions/CHANGELOG.md | 3 +++ semantic-conventions/syntax.md | 4 +++- 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/semantic-conventions/CHANGELOG.md b/semantic-conventions/CHANGELOG.md index 7ca682de..941620d1 100644 --- a/semantic-conventions/CHANGELOG.md +++ b/semantic-conventions/CHANGELOG.md @@ -4,6 +4,9 @@ Please update the changelog as part of any significant pull request. ## Unreleased +- Update json-schema version, remove properties that are not used anymore. + ([#344](https://github.com/open-telemetry/build-tools/pull/344)) + ## 0.25.0 - Added display_name as an allowed property on semconv attribute groups diff --git a/semantic-conventions/syntax.md b/semantic-conventions/syntax.md index 97b3f4ce..034fb0a8 100644 --- a/semantic-conventions/syntax.md +++ b/semantic-conventions/syntax.md @@ -40,7 +40,7 @@ All attributes are lower case. groups ::= semconv | semconv groups -semconv ::= id [convtype] brief [note] [extends] stability [deprecated] attributes [specificfields] +semconv ::= id [convtype] brief [note] [extends] stability [deprecated] [display_name] attributes [specificfields] id ::= string @@ -60,6 +60,8 @@ stability ::= "experimental" deprecated ::= +display_name ::= string + attributes ::= (id type brief examples | ref [brief] [examples]) [tag] stability [deprecated] [required] [sampling_relevant] [note] # ref MUST point to an existing attribute id From ffb95c41317f4c066416837af1b9e66a6fe50d6f Mon Sep 17 00:00:00 2001 From: Liudmila Molkova Date: Thu, 8 Aug 2024 08:55:11 -0700 Subject: [PATCH 3/3] fix array examples --- semantic-conventions/syntax.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/semantic-conventions/syntax.md b/semantic-conventions/syntax.md index 034fb0a8..88597346 100644 --- a/semantic-conventions/syntax.md +++ b/semantic-conventions/syntax.md @@ -272,20 +272,14 @@ examples: A single example value for an array of strings attribute: ```yaml -examples: ['first element of first array', 'second element of first array'] +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' + - ['first element of first array', 'second element of first array'] ``` Multiple example values for an array of string attribute: @@ -302,6 +296,12 @@ examples: - ['first element of second array', 'second element of second 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' +``` + #### Ref `ref` MUST have an id of an existing attribute. When it is set, `id`, `type`, `stability`, and `deprecation` MUST NOT be present.