Skip to content

Add strict YAML parsing guidance to supplementary guidelines#4878

Merged
jack-berg merged 9 commits intoopen-telemetry:mainfrom
zeitlinger:strict-yaml
Apr 15, 2026
Merged

Add strict YAML parsing guidance to supplementary guidelines#4878
jack-berg merged 9 commits intoopen-telemetry:mainfrom
zeitlinger:strict-yaml

Conversation

@zeitlinger
Copy link
Copy Markdown
Member

@zeitlinger zeitlinger commented Feb 6, 2026 •
edited
Loading

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.

Fixes #

Changes

Please provide a brief description of the changes here.

For non-trivial changes, follow the change proposal process.

  • Related issues #
  • Related OTEP(s) #
  • Links to the prototypes (when adding or changing features)
  • CHANGELOG.md file updated for non-trivial changes
    • For trivial changes, include [chore] in the PR title to skip the changelog check
  • Spec compliance matrix updated if necessary

@zeitlinger zeitlinger requested review from a team as code owners February 6, 2026 15:30
jack-berg
jack-berg reviewed Feb 10, 2026
View reviewed changes
Comment thread specification/configuration/supplementary-guidelines.md Outdated
Comment thread specification/configuration/supplementary-guidelines.md Outdated
Comment thread specification/configuration/supplementary-guidelines.md Outdated
@jack-berg
Copy link
Copy Markdown
Member

jack-berg commented Feb 12, 2026

This seems like a good addition. Adhering to strict YAML increases the likelihood of a consistent experience across languages.

However, its unlikely that all language implementations can configure their YAML parsers to enforce strict parsing. And so supplementary guidance to users seems like the most appropriate way to encourage this.

@zeitlinger
Copy link
Copy Markdown
Member Author

zeitlinger commented Feb 13, 2026

/easycla

@jack-berg jack-berg self-assigned this Feb 18, 2026
@carlosalberto
Copy link
Copy Markdown
Contributor

carlosalberto commented Mar 4, 2026

@jack-berg @zeitlinger Do we need more reviews from the config SIG? Or we good to go?

@zeitlinger
Copy link
Copy Markdown
Member Author

zeitlinger commented Mar 4, 2026

I think we're good — two spec approver approvals should be sufficient. Thanks for the review!

@pellared pellared added the area:configuration Related to configuring the SDK label Mar 4, 2026
pellared
pellared approved these changes Mar 4, 2026
View reviewed changes
Comment thread CHANGELOG.md Outdated
@zeitlinger
Add strict YAML parsing guidance to supplementary guidelines
0470d92 
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 <gregor.zeitlinger@grafana.com>
@zeitlinger
add CHANGELOG.md entry
e654423 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@zeitlinger
Address review feedback on strict YAML parsing section
61ced6b 
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 <gregor.zeitlinger@grafana.com>
@zeitlinger
Move YAML parsing changelog entry to SDK Configuration section
a4756c3 
Per review feedback from @pellared.
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
pellared
pellared reviewed Mar 16, 2026
View reviewed changes
Comment thread CHANGELOG.md Outdated
@zeitlinger
Move CHANGELOG entry to v1.55.0 (unreleased)
4989e67 
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 <gregor.zeitlinger@grafana.com>
@zeitlinger
Merge branch 'main' into strict-yaml
07200cb
@zeitlinger
Remove empty CHANGELOG section headers
4808b41 
Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
@jack-berg
Copy link
Copy Markdown
Member

jack-berg commented Mar 30, 2026

@pellared I believe your feedback has been addressed. Can you remove your change request? Thanks

@carlosalberto
Copy link
Copy Markdown
Contributor

carlosalberto commented Apr 13, 2026

Ping @pellared ;)

@jmacd jmacd dismissed pellared’s stale review April 14, 2026 23:00

This was fixed, but now IIUC we need to move the changelog entry again?

@jack-berg
Copy link
Copy Markdown
Member

jack-berg commented Apr 15, 2026

This was fixed, but now IIUC we need to move the changelog entry again?

Fixed

@jack-berg jack-berg enabled auto-merge April 15, 2026 21:01
@jack-berg jack-berg added this pull request to the merge queue Apr 15, 2026
Merged via the queue into open-telemetry:main with commit a8b288e Apr 15, 2026
9 checks passed
@carlosalberto carlosalberto mentioned this pull request Apr 15, 2026
Merged
pull Bot pushed a commit to MC-MAGA/opentelemetry-specification that referenced this pull request Apr 20, 2026
@carlosalberto @jack-berg
Release 1.56 (open-telemetry#5029)
50149c2 
### Context

- Align environment variable context propagation name restrictions with
POSIX.1-2024
  and define normalization behavior.

([open-telemetry#4944](open-telemetry#4944))
- Decouple the responsibilities of the environment variable propagation
carrier.

([open-telemetry#4961](open-telemetry#4961))
- Remove misleading implementation approach the environment variable
propagation.

([open-telemetry#5003](open-telemetry#5003))
- Change Environment Variables as Context Propagation Carriers document
status to Beta.

([open-telemetry#5020](open-telemetry#5020))

### Traces

- Stabilize Tracer `enabled` operation

([open-telemetry#4941](open-telemetry#4941))
- Stabilize `AlwaysRecord` sampler.

([open-telemetry#4934](open-telemetry#4934))

### Metrics

- Add development `maxExportBatchSize` parameter to Periodic exporting
MetricReader.

([open-telemetry#4895](open-telemetry#4895))

### Logs

- Add event to span event bridge.

([open-telemetry#5006](open-telemetry#5006))

### Resource

- Clarify that a Resource describes the observed entity, not the
component
  that technically emits telemetry.

([open-telemetry#4905](open-telemetry#4905))

### Compatibility

- Deprecate OpenTracing compatibility requirements in the specification.

([open-telemetry#4938](open-telemetry#4938))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram
transformation.

([open-telemetry#4874](open-telemetry#4874))
  - Stabilize Prometheus Timestamp and Start timestamp transformation.

([open-telemetry#4953](open-telemetry#4953))
- Clarify Prometheus Native Histogram to OTLP Exponential Histogram
conversion,
add conversion rules for Native Histograms with Custom Buckets (NHCB) to
OTLP
    Histogram.

([open-telemetry#4898](open-telemetry#4898))
  - Stabilize Prometheus Dropped Types transformation.

([open-telemetry#4952](open-telemetry#4952))
- Stabilize OpenTelemetry Attributes to Prometheus labels
transformation.

([open-telemetry#4963](open-telemetry#4963))
- Stabilize Prometheus Exemplar to OpenTelemetry Exemplar
transformation.

([open-telemetry#4962](open-telemetry#4962))
  - Stabilize Prometheus Metadata transformation.

([open-telemetry#4954](open-telemetry#4954))
- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata.

([open-telemetry#4966](open-telemetry#4966))
- Stabilize OpenTelemetry Exemplar to Prometheus Exemplar
transformation.

([open-telemetry#4964](open-telemetry#4964))
- Stabilize sections of Prometheus Metrics Exporter.
  - Stabilize host configuration.

([open-telemetry#5025](open-telemetry#5025))

### SDK Configuration

- Declarative configuration: add in-development guidance for exposing
the
  effective `Resource` returned by `Create`.

([open-telemetry#4949](open-telemetry#4949))
- Require spec changes to consider declarative config schema

([open-telemetry#4916](open-telemetry#4916))
- Add strict YAML parsing guidance to configuration supplementary
guidelines.

([open-telemetry#4878](open-telemetry#4878))

### OTEPs

- Process Context: Sharing Resource Attributes with External Readers.

([open-telemetry#4719](open-telemetry#4719))
- Support multiple Resources within an SDK.

([open-telemetry#4665](open-telemetry#4665))

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
hilmarf pushed a commit to apeirora/opentelemetry-specification that referenced this pull request Apr 22, 2026
@zeitlinger @jack-berg @hilmarf
Add strict YAML parsing guidance to supplementary guidelines (open-te…
80f49f4 
…lemetry#4878)

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.

Fixes #

## Changes

Please provide a brief description of the changes here.

For non-trivial changes, follow the [change proposal
process](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CONTRIBUTING.md#proposing-a-change).

* [ ] Related issues #
* [ ] Related [OTEP(s)](https://github.com/open-telemetry/oteps) #
* [ ] Links to the prototypes (when adding or changing features)
* [x]
[`CHANGELOG.md`](https://github.com/open-telemetry/opentelemetry-specification/blob/main/CHANGELOG.md)
file updated for non-trivial changes
* For trivial changes, include `[chore]` in the PR title to skip the
changelog check
* [ ] [Spec compliance
matrix](https://github.com/open-telemetry/opentelemetry-specification/blob/main/spec-compliance-matrix/template.yaml)
updated if necessary

---------

Signed-off-by: Gregor Zeitlinger <gregor.zeitlinger@grafana.com>
Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
hilmarf pushed a commit to apeirora/opentelemetry-specification that referenced this pull request Apr 22, 2026
@carlosalberto @jack-berg @hilmarf
Release 1.56 (open-telemetry#5029)
68fba8a 
### Context

- Align environment variable context propagation name restrictions with
POSIX.1-2024
  and define normalization behavior.

([open-telemetry#4944](open-telemetry#4944))
- Decouple the responsibilities of the environment variable propagation
carrier.

([open-telemetry#4961](open-telemetry#4961))
- Remove misleading implementation approach the environment variable
propagation.

([open-telemetry#5003](open-telemetry#5003))
- Change Environment Variables as Context Propagation Carriers document
status to Beta.

([open-telemetry#5020](open-telemetry#5020))

### Traces

- Stabilize Tracer `enabled` operation

([open-telemetry#4941](open-telemetry#4941))
- Stabilize `AlwaysRecord` sampler.

([open-telemetry#4934](open-telemetry#4934))

### Metrics

- Add development `maxExportBatchSize` parameter to Periodic exporting
MetricReader.

([open-telemetry#4895](open-telemetry#4895))

### Logs

- Add event to span event bridge.

([open-telemetry#5006](open-telemetry#5006))

### Resource

- Clarify that a Resource describes the observed entity, not the
component
  that technically emits telemetry.

([open-telemetry#4905](open-telemetry#4905))

### Compatibility

- Deprecate OpenTracing compatibility requirements in the specification.

([open-telemetry#4938](open-telemetry#4938))
- Stabilize sections of Prometheus and OpenMetrics Compatibility.
- Stabilize Prometheus Classic Histogram to OTLP Explicit Histogram
transformation.

([open-telemetry#4874](open-telemetry#4874))
  - Stabilize Prometheus Timestamp and Start timestamp transformation.

([open-telemetry#4953](open-telemetry#4953))
- Clarify Prometheus Native Histogram to OTLP Exponential Histogram
conversion,
add conversion rules for Native Histograms with Custom Buckets (NHCB) to
OTLP
    Histogram.

([open-telemetry#4898](open-telemetry#4898))
  - Stabilize Prometheus Dropped Types transformation.

([open-telemetry#4952](open-telemetry#4952))
- Stabilize OpenTelemetry Attributes to Prometheus labels
transformation.

([open-telemetry#4963](open-telemetry#4963))
- Stabilize Prometheus Exemplar to OpenTelemetry Exemplar
transformation.

([open-telemetry#4962](open-telemetry#4962))
  - Stabilize Prometheus Metadata transformation.

([open-telemetry#4954](open-telemetry#4954))
- Stabilize OpenTelemetry Metric Metadata to Prometheus metric metadata.

([open-telemetry#4966](open-telemetry#4966))
- Stabilize OpenTelemetry Exemplar to Prometheus Exemplar
transformation.

([open-telemetry#4964](open-telemetry#4964))
- Stabilize sections of Prometheus Metrics Exporter.
  - Stabilize host configuration.

([open-telemetry#5025](open-telemetry#5025))

### SDK Configuration

- Declarative configuration: add in-development guidance for exposing
the
  effective `Resource` returned by `Create`.

([open-telemetry#4949](open-telemetry#4949))
- Require spec changes to consider declarative config schema

([open-telemetry#4916](open-telemetry#4916))
- Add strict YAML parsing guidance to configuration supplementary
guidelines.

([open-telemetry#4878](open-telemetry#4878))

### OTEPs

- Process Context: Sharing Resource Attributes with External Readers.

([open-telemetry#4719](open-telemetry#4719))
- Support multiple Resources within an SDK.

([open-telemetry#4665](open-telemetry#4665))

---------

Co-authored-by: Jack Berg <34418638+jack-berg@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@carlosalberto carlosalberto carlosalberto approved these changes

@jmacd jmacd jmacd approved these changes

@reyang reyang reyang approved these changes

@jack-berg jack-berg jack-berg approved these changes

@pellared pellared pellared left review comments

+1 more reviewer

@seemk seemk seemk approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

@jack-berg jack-berg

Labels

area:configuration Related to configuring the SDK

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

7 participants

@zeitlinger @jack-berg @carlosalberto @jmacd @pellared @seemk @reyang