diff --git a/docs/examples/declarative-config/README.rst b/docs/examples/declarative-config/README.rst
new file mode 100644
index 00000000000..1dffb1a3436
--- /dev/null
+++ b/docs/examples/declarative-config/README.rst
@@ -0,0 +1,81 @@
+Declarative Configuration
+=========================
+
+This example configures the OpenTelemetry SDK from a single YAML file using
+:doc:`declarative configuration </sdk/configuration>` instead of environment
+variables or hand-written provider setup.
+
+The source files of this example are available :scm_web:`here
+<docs/examples/declarative-config/>`.
+
+Install the SDK with the ``file-configuration`` extra (it pulls in ``pyyaml``
+and ``jsonschema``), the auto-instrumentation entry point, and the OTLP/HTTP
+exporter:
+
+.. code-block:: sh
+
+    pip install "opentelemetry-sdk[file-configuration]" \
+        opentelemetry-distro \
+        opentelemetry-exporter-otlp-proto-http
+
+Start an OTLP-capable backend locally so there is somewhere to send data. Write
+the following file:
+
+.. code-block:: yaml
+
+    # otel-collector-config.yaml
+    receivers:
+      otlp:
+        protocols:
+          http:
+            endpoint: 0.0.0.0:4318
+
+    exporters:
+      debug:
+        verbosity: detailed
+
+    service:
+        pipelines:
+            traces:
+                receivers: [otlp]
+                exporters: [debug]
+            metrics:
+                receivers: [otlp]
+                exporters: [debug]
+            logs:
+                receivers: [otlp]
+                exporters: [debug]
+
+Then start the Collector:
+
+.. code-block:: sh
+
+    docker run \
+        -p 4318:4318 \
+        -v $(pwd)/otel-collector-config.yaml:/etc/otel-collector-config.yaml \
+        otel/opentelemetry-collector:latest \
+        --config=/etc/otel-collector-config.yaml
+
+Run the example
+---------------
+
+Point the SDK at ``otel-config.yaml`` with ``OTEL_CONFIG_FILE`` and let
+auto-instrumentation apply it. No configuration code lives in ``app.py``:
+
+.. code-block:: sh
+
+    export OTEL_CONFIG_FILE=$(pwd)/otel-config.yaml
+    opentelemetry-instrument python app.py
+
+You should see the exported span in the Collector's debug output.
+
+Environment variable substitution
+----------------------------------
+
+``otel-config.yaml`` uses ``${DEPLOYMENT_ENVIRONMENT:-development}`` to read the
+deployment environment from the environment, defaulting to ``development``. Set
+it before running to override:
+
+.. code-block:: sh
+
+    export DEPLOYMENT_ENVIRONMENT=staging
diff --git a/docs/examples/declarative-config/app.py b/docs/examples/declarative-config/app.py
new file mode 100644
index 00000000000..dce1a5900fb
--- /dev/null
+++ b/docs/examples/declarative-config/app.py
@@ -0,0 +1,18 @@
+# Copyright The OpenTelemetry Authors
+# SPDX-License-Identifier: Apache-2.0
+
+"""A minimal application driven by declarative configuration.
+
+The SDK is configured entirely from ``otel-config.yaml`` via the
+``OTEL_CONFIG_FILE`` environment variable. Run with
+``opentelemetry-instrument`` so the configurator picks up the env var:
+
+    OTEL_CONFIG_FILE=$(pwd)/otel-config.yaml opentelemetry-instrument python app.py
+"""
+
+from opentelemetry import trace
+
+tracer = trace.get_tracer("declarative-config-example")
+
+with tracer.start_as_current_span("hello"):
+    print("Hello from a declaratively configured SDK!")
diff --git a/docs/examples/declarative-config/otel-config.yaml b/docs/examples/declarative-config/otel-config.yaml
new file mode 100644
index 00000000000..1f2bd9fa798
--- /dev/null
+++ b/docs/examples/declarative-config/otel-config.yaml
@@ -0,0 +1,34 @@
+file_format: "1.0"
+
+resource:
+  attributes:
+    - name: service.name
+      value: my-service
+    - name: deployment.environment.name
+      value: ${DEPLOYMENT_ENVIRONMENT:-development}
+
+tracer_provider:
+  processors:
+    - batch:
+        exporter:
+          otlp_http:
+            endpoint: http://localhost:4318/v1/traces
+  sampler:
+    parent_based:
+      root:
+        always_on: {}
+
+meter_provider:
+  readers:
+    - periodic:
+        interval: 60000
+        exporter:
+          otlp_http:
+            endpoint: http://localhost:4318/v1/metrics
+
+logger_provider:
+  processors:
+    - batch:
+        exporter:
+          otlp_http:
+            endpoint: http://localhost:4318/v1/logs
diff --git a/docs/sdk/configuration.rst b/docs/sdk/configuration.rst
new file mode 100644
index 00000000000..5c540ecb6f6
--- /dev/null
+++ b/docs/sdk/configuration.rst
@@ -0,0 +1,124 @@
+Declarative Configuration
+=========================
+
+Declarative configuration lets you configure the OpenTelemetry SDK from a
+single YAML (or JSON) file instead of setting many individual ``OTEL_*``
+environment variables or writing provider-construction code by hand. The file
+format is defined by the `OpenTelemetry configuration specification
+<https://opentelemetry.io/docs/specs/otel/configuration/>`_.
+
+A single file describes your resource, providers, processors, exporters,
+samplers, and propagators. The SDK reads the file, validates it against the
+configuration schema, and applies it globally.
+
+Installing
+----------
+
+File configuration relies on optional dependencies (``pyyaml`` and
+``jsonschema``). Install them with the ``file-configuration`` extra:
+
+.. code-block:: sh
+
+    pip install "opentelemetry-sdk[file-configuration]"
+
+Enabling with an environment variable
+-------------------------------------
+
+Point the SDK at a file with the ``OTEL_CONFIG_FILE`` environment variable.
+When it is set, the file is the sole source of SDK construction. Spec-defined
+``OTEL_*`` variables with schema equivalents are ignored. Environment variables
+can still be read via ``${env:VAR}`` substitution inside the file (see
+`Environment variable substitution`_).
+
+.. code-block:: sh
+
+    export OTEL_CONFIG_FILE=/etc/otel/otel-config.yaml
+    opentelemetry-instrument python app.py
+
+Example configuration
+---------------------
+
+The following file configures traces, metrics, and logs to be exported over
+OTLP/HTTP. The source is available :scm_web:`here
+<docs/examples/declarative-config/>`.
+
+.. code-block:: yaml
+
+    file_format: "1.0"
+
+    resource:
+      attributes:
+        - name: service.name
+          value: my-service
+        - name: deployment.environment.name
+          value: ${DEPLOYMENT_ENVIRONMENT:-development}
+
+    tracer_provider:
+      processors:
+        - batch:
+            exporter:
+              otlp_http:
+                endpoint: https://example.com:4318/v1/traces
+                headers:
+                  - name: api-key
+                    value: ${OTLP_API_KEY}
+      sampler:
+        parent_based:
+          root:
+            always_on: {}
+
+    meter_provider:
+      readers:
+        - periodic:
+            interval: 60000
+            exporter:
+              otlp_http:
+                endpoint: https://example.com:4318/v1/metrics
+                headers:
+                  - name: api-key
+                    value: ${OTLP_API_KEY}
+
+    logger_provider:
+      processors:
+        - batch:
+            exporter:
+              otlp_http:
+                endpoint: https://example.com:4318/v1/logs
+                headers:
+                  - name: api-key
+                    value: ${OTLP_API_KEY}
+
+Environment variable substitution
+----------------------------------
+
+Values in the file may reference environment variables, which keeps secrets
+such as API keys out of the file itself. Substitution happens before the file
+is parsed.
+
+* ``${VAR}``: replaced with the value of ``VAR``. If ``VAR`` is unset, loading
+  fails with an error.
+* ``${VAR:-default}``: replaced with ``VAR`` if set, otherwise ``default``.
+* ``$$``: a literal ``$``.
+
+In the example above, ``${OTLP_API_KEY}`` is required, while
+``${DEPLOYMENT_ENVIRONMENT:-development}`` falls back to ``development`` when
+unset.
+
+Behavior notes
+--------------
+
+* When ``OTEL_CONFIG_FILE`` is set, the file is authoritative for SDK
+  construction; spec-defined ``OTEL_*`` variables with schema equivalents are
+  not consulted. Environment variables can still be read indirectly by
+  components the file enables (for example resource detectors) and via
+  ``${env:VAR}`` substitution.
+* Sections omitted from the file leave the corresponding global provider
+  unset (a no-op provider), per the specification.
+* Setting ``disabled: true`` at the top level turns the SDK into a no-op.
+
+See also
+--------
+
+* `OpenTelemetry configuration specification
+  <https://opentelemetry.io/docs/specs/otel/configuration/>`_
+* :doc:`environment_variables`: the environment-variable configuration path
diff --git a/docs/sdk/index.rst b/docs/sdk/index.rst
index ecc4a390856..48c3568eab6 100644
--- a/docs/sdk/index.rst
+++ b/docs/sdk/index.rst
@@ -20,3 +20,4 @@ processed, and exported.
     metrics
     error_handler
     environment_variables
+    configuration