Skip to content

Add strict YAML parsing guidance to supplementary guidelines #4878

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
zeitlinger wants to merge 3 commits into
base: main
Choose a base branch
from
Open

Add strict YAML parsing guidance to supplementary guidelines #4878

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
431c4c4
Add strict YAML parsing guidance to supplementary guidelines
zeitlinger Feb 6, 2026
41ca196
add CHANGELOG.md entry
zeitlinger Feb 6, 2026
f4e41ff
Address review feedback on strict YAML parsing section
zeitlinger Feb 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -56,6 +56,9 @@ release.

### Supplementary Guidelines

- Add strict YAML parsing guidance to configuration supplementary guidelines.
([#4878](https://github.com/open-telemetry/opentelemetry-specification/pull/4878))
Comment on lines +59 to +60
Copy link
Member

@pellared pellared Mar 4, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

(nit) How about moving to "SDK Configuration" section?


### OTEPs

## v1.53.0 (2026-01-09)
Expand Down
25 changes: 25 additions & 0 deletions specification/configuration/supplementary-guidelines.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)

<!-- tocstop -->

Expand Down Expand Up @@ -63,3 +64,27 @@ 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

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"` 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.
Loading