[herin049]

Description

Aligns environment variable substitution in opentelemetry-configuration with the declarative configuration spec.

Input	Before	After (per spec)
${env:VALUE} (VALUE=42, unquoted)	left as literal text	42, resolved as an int
${VALUE:?error}, ${1API_KEY}, ${sys:foo}	left as literal text	ConfigurationError, no partial config
${UNDEFINED_KEY:-$${UNDEFINED_KEY}}	$${UNDEFINED_KEY}	${UNDEFINED_KEY:-${UNDEFINED_KEY}}
${EMPTY:-fallback} with EMPTY=""	""	fallback

Changes:

• $$ escapes are now found first, scanning left to right, and references are matched only in the text between them, as in the spec's pseudocode.
• Added support for the env: prefix. An unquoted standalone ${env:VAR} gets the same YAML type resolution as ${VAR}.
• A reference that doesn't match ENV-SUBSTITUTION now raises ConfigurationError. This includes unknown prefixes, since env: is the only one this SDK supports.
• A default value now applies when the variable is set but empty, not only when it's unset.

Type of change

Please delete options that are not relevant.

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• This change requires a documentation update

Checklist:

See contributing.md for styleguide, changelog guidelines, and more.

• I am a human and not a bot
• I have run tox -e precommit
• I have run tox -e typecheck
• I have run the relevant tests and linting tox environments
• This requires the following PR in contrib:

[opentelemetry-pr-dashboard]

Pull request dashboard status

Waiting on reviewers · refreshed 2026-10-21 20:00 UTC

Review the latest changes.

Status above doesn't look right?

• Just replied or pushed? Anything around or after the refresh time above may not be picked up yet — give it a few minutes.
• Anything look wrong? Report it with what you expected; it helps us improve the dashboard.

[Copilot]

🟢 Approval recommended

The focused implementation and regression coverage support the described behavior, with no unresolved blocking issues.

No open issues 🎉

What changed in this PR

Aligns declarative configuration environment-variable substitution with the specification.

Changes:

• Adds env: support, escape-first parsing, invalid-reference errors, and defaults for empty variables.
• Preserves YAML type resolution for standalone prefixed references.
• Expands unit and Docker scenario coverage.

File	Description
tests/​opentelemetry-docker-tests/​tests/​declconfig/​scenarios/​general_env_substitution/​scenario.yaml	Expands expected substitution results.
tests/​opentelemetry-docker-tests/​tests/​declconfig/​scenarios/​general_env_substitution/​otel-config.yaml	Adds substitution edge cases.
tests/​opentelemetry-docker-tests/​tests/​declconfig/​scenarios/​error_invalid_env_substitution/​scenario.yaml	Checks initialization failure and zero spans.
tests/​opentelemetry-docker-tests/​tests/​declconfig/​scenarios/​error_invalid_env_substitution/​run.py	Attempts tracing after invalid configuration.
tests/​opentelemetry-docker-tests/​tests/​declconfig/​scenarios/​error_invalid_env_substitution/​otel-config.yaml	Supplies an invalid reference.
opentelemetry-configuration/​tests/​file/​test_loader.py	Tests loader typing and error propagation.
opentelemetry-configuration/​tests/​file/​test_env_substitution.py	Adds specification regression tests.
opentelemetry-configuration/​src/​opentelemetry/​configuration/​file/​_loader.py	Recognizes standalone prefixed references.
opentelemetry-configuration/​src/​opentelemetry/​configuration/​file/​_env_substitution.py	Implements updated substitution rules.
.changelog/​5805.fixed	Records the parsing fix.

_{Review effort: Balanced}