From 0470d9254dd354b9910e4f1bd5070a3c78b3d8a7 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 6 Feb 2026 16:27:16 +0100 Subject: [PATCH 1/7] Add strict YAML parsing guidance to supplementary guidelines Adds a new section recommending strict YAML parsing practices for configuration files, including use of YAML 1.2 Core Schema, disabling dangerous deserialization features, and using safe parser modes. This helps prevent security issues and unintended type coercion. Signed-off-by: Gregor Zeitlinger --- .../configuration/supplementary-guidelines.md | 31 +++++++++++++++++++ 1 file changed, 31 insertions(+) diff --git a/specification/configuration/supplementary-guidelines.md b/specification/configuration/supplementary-guidelines.md index 2f8fc776daa..eaa64d33034 100644 --- a/specification/configuration/supplementary-guidelines.md +++ b/specification/configuration/supplementary-guidelines.md @@ -11,6 +11,7 @@ requirements to the existing specifications. - [Configuration interface prioritization and `create`](#configuration-interface-prioritization-and-create) - [Programmatic customization and `create`](#programmatic-customization-and-create) +- [Strict YAML parsing](#strict-yaml-parsing) @@ -63,3 +64,33 @@ exporters is not possible to express with declarative config should not encourage the OpenTelemetry community to have better programmatic customization. Instead, we should pursue adding authentication as an SDK plugin component and modeling in declarative config. + +## Strict YAML parsing + +Implementations SHOULD use strict YAML parsing when processing configuration +files. Strict parsing helps prevent unintended behaviors and security issues +that can arise from YAML's implicit type conversions and complex features. + +Recommended practices for strict YAML parsing include: + +* Use the [YAML 1.2 Core Schema](https://yaml.org/spec/1.2.2/#103-core-schema) + as specified in the [data model](./data-model.md#yaml-file-format). The Core + Schema provides a minimal type system (strings, integers, floats, booleans, + null) that avoids the ambiguities and security concerns of the JSON Schema or + Failsafe Schema. +* Disable language-specific object deserialization features that allow + arbitrary code execution (e.g., Python's `!!python/object` tags, Ruby's + `!ruby/object` tags). The Core Schema naturally excludes these features. +* Validate that parsed values conform to expected types based on the + configuration schema before using them. +* Consider using "safe" or "strict" parser modes when available in your YAML + library (e.g., `yaml.safe_load()` in Python, safe mode in Ruby's Psych). + +By following strict YAML parsing practices, implementations can avoid common +pitfalls such as: + +* Unintended type coercion (e.g., `NO` being parsed as boolean `false` instead + of the string `"NO"`) +* Security vulnerabilities from arbitrary code execution +* Unexpected behavior from complex YAML features like anchors and aliases in + untrusted input From e654423aeb8f880e2c50f323803193909b82ee37 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 6 Feb 2026 16:30:58 +0100 Subject: [PATCH 2/7] add CHANGELOG.md entry Signed-off-by: Gregor Zeitlinger --- CHANGELOG.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1fffcc6306a..1d6910bafda 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -127,6 +127,13 @@ release. empty object when not set ([#4817](https://github.com/open-telemetry/opentelemetry-specification/pull/4817)) +### Supplementary Guidelines + +- Add strict YAML parsing guidance to configuration supplementary guidelines. + ([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878)) + +### OTEPs + ## v1.53.0 (2026-01-09) ### Metrics From 61ced6bdbf9d5e3a982a5dea8ea4ef9f418bc185 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Tue, 10 Feb 2026 16:22:24 +0100 Subject: [PATCH 3/7] Address review feedback on strict YAML parsing section Reframe guidance toward configuration file authors instead of implementations, remove normative language (SHOULD), and add note clarifying that practices are derived from the YAML 1.2 Core Schema and common security best practices. Signed-off-by: Gregor Zeitlinger --- .../configuration/supplementary-guidelines.md | 40 ++++++++----------- 1 file changed, 17 insertions(+), 23 deletions(-) diff --git a/specification/configuration/supplementary-guidelines.md b/specification/configuration/supplementary-guidelines.md index eaa64d33034..6eee879d9f6 100644 --- a/specification/configuration/supplementary-guidelines.md +++ b/specification/configuration/supplementary-guidelines.md @@ -67,30 +67,24 @@ modeling in declarative config. ## Strict YAML parsing -Implementations SHOULD use strict YAML parsing when processing configuration -files. Strict parsing helps prevent unintended behaviors and security issues -that can arise from YAML's implicit type conversions and complex features. - -Recommended practices for strict YAML parsing include: - -* Use the [YAML 1.2 Core Schema](https://yaml.org/spec/1.2.2/#103-core-schema) - as specified in the [data model](./data-model.md#yaml-file-format). The Core - Schema provides a minimal type system (strings, integers, floats, booleans, - null) that avoids the ambiguities and security concerns of the JSON Schema or - Failsafe Schema. -* Disable language-specific object deserialization features that allow - arbitrary code execution (e.g., Python's `!!python/object` tags, Ruby's - `!ruby/object` tags). The Core Schema naturally excludes these features. -* Validate that parsed values conform to expected types based on the - configuration schema before using them. -* Consider using "safe" or "strict" parser modes when available in your YAML - library (e.g., `yaml.safe_load()` in Python, safe mode in Ruby's Psych). - -By following strict YAML parsing practices, implementations can avoid common -pitfalls such as: +The practices described below are derived from the +[YAML 1.2 Core Schema](https://yaml.org/spec/1.2.2/#103-core-schema) +as specified in the [data model](./data-model.md#yaml-file-format) and common +security best practices for YAML processing. + +Configuration file authors are encouraged to constrain themselves to the +Core Schema's minimal type system (strings, integers, floats, booleans, null) +to maximize portability across languages and avoid common YAML pitfalls such +as: * Unintended type coercion (e.g., `NO` being parsed as boolean `false` instead - of the string `"NO"`) -* Security vulnerabilities from arbitrary code execution + of the string `"NO"` in YAML 1.1) +* Security vulnerabilities from language-specific object deserialization + features that allow arbitrary code execution (e.g., Python's `!!python/object` + tags, Ruby's `!ruby/object` tags) * Unexpected behavior from complex YAML features like anchors and aliases in untrusted input + +When an implementation's YAML library offers a "safe" or "strict" parser mode +(e.g., `yaml.safe_load()` in Python, safe mode in Ruby's Psych), using it is a +good way to enforce these constraints automatically. From a4756c3bc15233cae2f5a74a0af981a02f24a4d7 Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Mon, 16 Mar 2026 15:40:07 +0000 Subject: [PATCH 4/7] Move YAML parsing changelog entry to SDK Configuration section Per review feedback from @pellared. Signed-off-by: Gregor Zeitlinger --- CHANGELOG.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 1d6910bafda..13819f35852 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -126,12 +126,11 @@ release. - Declarative configuration: Update instrumentation config behavior to return empty object when not set ([#4817](https://github.com/open-telemetry/opentelemetry-specification/pull/4817)) - -### Supplementary Guidelines - - Add strict YAML parsing guidance to configuration supplementary guidelines. ([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878)) +### Supplementary Guidelines + ### OTEPs ## v1.53.0 (2026-01-09) From 4989e6770894da1065b1b3cce0eb192c4ed75adc Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Wed, 18 Mar 2026 15:30:13 +0000 Subject: [PATCH 5/7] Move CHANGELOG entry to v1.55.0 (unreleased) Address review comments: move strict YAML parsing guidance entry from v1.54.0 to v1.55.0 under SDK Configuration. Signed-off-by: Gregor Zeitlinger --- CHANGELOG.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 13819f35852..2ac9c675add 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -75,6 +75,8 @@ release. ([#4891](https://github.com/open-telemetry/opentelemetry-specification/pull/4891)) - Mark significant portions of declarative configuration as stable. ([#4568](https://github.com/open-telemetry/opentelemetry-specification/pull/4568)) +- Add strict YAML parsing guidance to configuration supplementary guidelines. + ([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878)) ## v1.54.0 (2026-02-13) @@ -126,9 +128,6 @@ release. - Declarative configuration: Update instrumentation config behavior to return empty object when not set ([#4817](https://github.com/open-telemetry/opentelemetry-specification/pull/4817)) -- Add strict YAML parsing guidance to configuration supplementary guidelines. - ([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878)) - ### Supplementary Guidelines ### OTEPs From 4808b4172e6e7839a61df7e249cb0368b13924cd Mon Sep 17 00:00:00 2001 From: Gregor Zeitlinger Date: Fri, 20 Mar 2026 09:14:08 +0000 Subject: [PATCH 6/7] Remove empty CHANGELOG section headers Signed-off-by: Gregor Zeitlinger --- CHANGELOG.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 9ad6bd6058a..5d271730d68 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -141,9 +141,6 @@ release. - Declarative configuration: Update instrumentation config behavior to return empty object when not set ([#4817](https://github.com/open-telemetry/opentelemetry-specification/pull/4817)) -### Supplementary Guidelines - -### OTEPs ## v1.53.0 (2026-01-09) From 72349aeb9cf08324f06dce3f03a0f8ee59cfc59d Mon Sep 17 00:00:00 2001 From: Jack Berg <34418638+jack-berg@users.noreply.github.com> Date: Wed, 15 Apr 2026 16:00:17 -0500 Subject: [PATCH 7/7] move changelog entry to unreleased --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 5d271730d68..ebf8c828361 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -54,6 +54,9 @@ release. ### SDK Configuration +- Add strict YAML parsing guidance to configuration supplementary guidelines. + ([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878)) + ### Supplementary Guidelines ### OTEPs @@ -88,8 +91,6 @@ release. ([#4891](https://github.com/open-telemetry/opentelemetry-specification/pull/4891)) - Mark significant portions of declarative configuration as stable. ([#4568](https://github.com/open-telemetry/opentelemetry-specification/pull/4568)) -- Add strict YAML parsing guidance to configuration supplementary guidelines. - ([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878)) ## v1.54.0 (2026-02-13)