From 08cee3c1652b6565031140c68dfdeedd4d16ac21 Mon Sep 17 00:00:00 2001 From: Pablo Baeyens Date: Tue, 7 May 2024 21:09:08 +0200 Subject: [PATCH] [configuration] Specify YAML schema that configuration files should follow (#3973) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fixes #3962 ## Changes Specifies the YAML schema to follow. A schema is a set of YAML tags (i.e. types) and a way to assign types. YAML 1.2 recommends the 'Core schema': the types are those of JSON. Scalars are resolved as one would expect, see [here](https://yaml.org/spec/1.2.2/#103-core-schema) for the details. One important difference with the way that YAML 1.1 used to work is that integer scalars starting with a `0` are interpreted as being written in decimal notation; e.g. `0123` parses to the integer 123 instead of the integer 83 (you can still use octal notation in YAML 1.2 by using `0o123`). Some YAML parsers deviate from the core schema in how this works, for example, both of the more commonly used YAML parsing libraries in Golang parse `0123` as 83 ([go-yaml/yaml](https://github.com/go-yaml/yaml?tab=readme-ov-file#compatibility) and [goccy/go-yaml](https://github.com/goccy/go-yaml/blob/4653a1bb5c0047bb37280ac341e2f091cb44352f/ast/ast.go#L326)). **This may make it a bit difficult to strictly follow this requirement in some languages**. For non-trivial changes, follow the [change proposal process](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change). * [x] Related issues #3962, part of #3963 --------- Co-authored-by: Robert Pająk Co-authored-by: jack-berg <34418638+jack-berg@users.noreply.github.com> --- CHANGELOG.md | 2 ++ specification/configuration/file-configuration.md | 2 ++ 2 files changed, 4 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 07bd1485a74..d57f076c7be 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -46,6 +46,8 @@ release. ([#4002](https://github.com/open-telemetry/opentelemetry-specification/pull/4002)) - Add end to end examples for file configuration ([#4018](https://github.com/open-telemetry/opentelemetry-specification/pull/4018)) +- Clarify the schema for YAML configuration files + ([#3973](https://github.com/open-telemetry/opentelemetry-specification/pull/3973)) ### Common diff --git a/specification/configuration/file-configuration.md b/specification/configuration/file-configuration.md index 4a7d11b4829..c88b2da817f 100644 --- a/specification/configuration/file-configuration.md +++ b/specification/configuration/file-configuration.md @@ -65,6 +65,8 @@ Configuration files SHOULD use one the following serialization formats: [YAML](https://yaml.org/spec/1.2.2/) configuration files SHOULD follow YAML spec revision >= 1.2. +YAML configuration files SHOULD be parsed using [v1.2 YAML core schema](https://yaml.org/spec/1.2.2/#103-core-schema). + YAML configuration files MUST use file extensions `.yaml` or `.yml`. ### Environment variable substitution