From f65592fc1a51dda5858732bdd0c848dd613ecd9f Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Fri, 5 Dec 2025 09:39:48 -0600 Subject: [PATCH 1/3] Clarify declarative config default requirements --- specification/configuration/sdk.md | 32 +++++++++++++++++++++--------- 1 file changed, 23 insertions(+), 9 deletions(-) diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 3d844f6c81e..6e02061faad 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -260,15 +260,29 @@ Interpret configuration model and return SDK components. The multiple responses MAY be returned using a tuple, or some other data structure encapsulating the components. -If a property has a default value defined (i.e. is _not_ required) and is -missing or present but null, Create MUST ensure the SDK component is configured -with the default value. If a property is required and is missing or present but -null, Create SHOULD return an error. For example, if configuring -the [span batching processor](../trace/sdk.md#batching-processor) and -the `scheduleDelayMillis` property is missing or present but null, the component -is configured with the default value of `5000`. However, if the `exporter` -property is missing or present but null, Create fails fast since there is no -default value for `exporter`. +Create requirements around default and null behavior are described below. Note that +[`defaultBehavior` and `nullBehavior`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/CONTRIBUTING.md#json-schema-source-and-output) +are defined in the configuration data model. + +* If a property is present and the value is non-null, Create MUST use the value. +* If a property is not present, Create MUST use `defaultBehavior`. +* If a property is present and the value is null, Create MUST use the + `nullBehavior`, or `defaultBehavior` if `nullBehavior` is not set. +* If a property is required, and not present, Create MUST return an error. +* If a property is not nullable, and present and the value is null, Create MUST + return an error. + +A few examples to illustrate: + +* If configuring [`BatchSpanProcessor`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#batchspanprocessor-) + and `schedule_delay` is not present or present but null, the component is + configured according to the `defaultBehavior` of `5000`. +* If configuring `BatchSpanProcessor` and `exporter` is not present or present + but null, Create returns an error since `exporter` is required and not + nullable. +* If configuring [`SpanExporter`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#spanexporter) + and `console` is present and null, the component is configured with a + `console` exporter with default configuration since `console` is nullable. When encountering a reference to a [SDK extension component](#sdk-extension-components) which is not built in to From 20065cfecccbd2a0d9066d7a4a0c0c529ad4cbbb Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Tue, 9 Dec 2025 08:53:35 -0600 Subject: [PATCH 2/3] improve phrasing --- specification/configuration/sdk.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 6e02061faad..ced50979f8a 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -269,8 +269,8 @@ are defined in the configuration data model. * If a property is present and the value is null, Create MUST use the `nullBehavior`, or `defaultBehavior` if `nullBehavior` is not set. * If a property is required, and not present, Create MUST return an error. -* If a property is not nullable, and present and the value is null, Create MUST - return an error. +* If a property is not nullable, and the value is null, Create MUST return an + error. A few examples to illustrate: From 83f305a688e71e6a91e7c360b04b99446805ecf3 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Wed, 10 Dec 2025 11:52:16 -0600 Subject: [PATCH 3/3] clarify parse is responsible for enforcing standard json schema keywords, create is responsible for semantics defined in description --- specification/configuration/sdk.md | 20 ++++++++++++-------- 1 file changed, 12 insertions(+), 8 deletions(-) diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index ced50979f8a..5ac7b1ae31f 100644 --- a/specification/configuration/sdk.md +++ b/specification/configuration/sdk.md @@ -239,7 +239,9 @@ Parse SHOULD return an error if: * The `file` doesn't exist or is invalid * The parsed `file` content does not conform to - the [configuration model](data-model.md) schema. + the [configuration model](data-model.md) schema. Note that this includes + enforcing all constraints encoded into the schema (e.g. required properties + are present, that properties adhere to specified types, etc.). #### Create @@ -264,26 +266,28 @@ Create requirements around default and null behavior are described below. Note t [`defaultBehavior` and `nullBehavior`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/CONTRIBUTING.md#json-schema-source-and-output) are defined in the configuration data model. -* If a property is present and the value is non-null, Create MUST use the value. -* If a property is not present, Create MUST use `defaultBehavior`. * If a property is present and the value is null, Create MUST use the `nullBehavior`, or `defaultBehavior` if `nullBehavior` is not set. * If a property is required, and not present, Create MUST return an error. -* If a property is not nullable, and the value is null, Create MUST return an - error. A few examples to illustrate: * If configuring [`BatchSpanProcessor`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#batchspanprocessor-) and `schedule_delay` is not present or present but null, the component is configured according to the `defaultBehavior` of `5000`. -* If configuring `BatchSpanProcessor` and `exporter` is not present or present - but null, Create returns an error since `exporter` is required and not - nullable. * If configuring [`SpanExporter`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#spanexporter) and `console` is present and null, the component is configured with a `console` exporter with default configuration since `console` is nullable. +The [configuration model](data-model.md) uses the JSON schema +[`description`](https://json-schema.org/understanding-json-schema/reference/annotations) +annotation to capture property semantics which cannot be encoded using standard +JSON schema keywords. Create SHOULD return an error if it encounters a value +which is invalid according to the property `description`. For example, if +configuring [`HttpTls`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#httptls-) +and `ca_file` is not an absolute file path as defined in the property +description, return an error. + When encountering a reference to a [SDK extension component](#sdk-extension-components) which is not built in to the SDK, Create MUST resolve the component using [Create Plugin](#create-plugin)