diff --git a/specification/configuration/sdk.md b/specification/configuration/sdk.md index 3d844f6c81e..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 @@ -260,15 +262,31 @@ 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 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. + +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 [`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