Clarify environment carrier key normalization behavior

[pellared]

Towards #5040

Changes

Clarifies the environment variable propagation carrier key normalization requirements:

• Set writes values using normalized key names.
• Get normalizes both the requested propagator key and carrier keys before matching.
• Keys returns normalized key names.

Motivation

The existing text defined how key names are normalized, but it did not explicitly say where that normalization applies. This PR clarifies that normalization is part of the carrier behavior for writing, reading, and listing keys.

This follows the robustness principle: carriers write the normalized representation, while getters can still accept a non-normalized environment variable key if it normalizes to the requested propagation key. For example, a non-normalized traceparent environment variable can still be used by the propagation getter when matching TRACEPARENT.

This retrospects #4944 (comment) now that implementations are in place.

Implementation references

• Go: envcar: normalize cached environment variable names opentelemetry-go-contrib#8761
• .NET: [API] Support environment variable context propagation opentelemetry-dotnet#7174
• Java: Update Env var getter / setter to reflect spec changes opentelemetry-java#8233
• Python: feat: update EnvironmentGetter and EnvironmentSetter to use normalized environment variable names opentelemetry-python#5119
• Swift: env var propagation carrier as Getter and Setter opentelemetry-swift-core#47

Related Java discussion: open-telemetry/opentelemetry-java#8233 (comment)

[pellared]

CC @open-telemetry/semconv-cicd-approvers @jack-berg @marcalff @Joibel

[Copilot]

Pull request overview

This PR clarifies how environment variable propagation carriers apply key normalization during carrier operations, supporting stabilization work for the environment carrier specification.

Changes:

• Specifies normalization behavior for Set, Get, and Keys.
• Adds an example showing normalized and non-normalized carrier key matching.
• Updates the changelog with the clarification.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
specification/context/env-carriers.md	Clarifies normalization requirements for carrier read, write, and key listing operations.
CHANGELOG.md	Records the environment carrier normalization clarification.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.