Skip to content

Commit e111347

Browse files
authored
Clarify declarative config default requirements (#4780)
When the declarative config `create` spec was written, declarative config was dependent on the spec as its source of truth for default values for the various properties. We now directly record expected [`defaultBehavior` and `nullBehavior`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/CONTRIBUTING.md#json-schema-source-and-output) semantics in `opentelemetry-configuration`. Updating the spec to tie things back together. /cc @open-telemetry/configuration-approvers
1 parent 838e1c0 commit e111347

1 file changed

Lines changed: 28 additions & 10 deletions

File tree

  • specification/configuration

specification/configuration/sdk.md

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -239,7 +239,9 @@ Parse SHOULD return an error if:
239239

240240
* The `file` doesn't exist or is invalid
241241
* The parsed `file` content does not conform to
242-
the [configuration model](data-model.md) schema.
242+
the [configuration model](data-model.md) schema. Note that this includes
243+
enforcing all constraints encoded into the schema (e.g. required properties
244+
are present, that properties adhere to specified types, etc.).
243245

244246
#### Create
245247

@@ -260,15 +262,31 @@ Interpret configuration model and return SDK components.
260262
The multiple responses MAY be returned using a tuple, or some other data
261263
structure encapsulating the components.
262264

263-
If a property has a default value defined (i.e. is _not_ required) and is
264-
missing or present but null, Create MUST ensure the SDK component is configured
265-
with the default value. If a property is required and is missing or present but
266-
null, Create SHOULD return an error. For example, if configuring
267-
the [span batching processor](../trace/sdk.md#batching-processor) and
268-
the `scheduleDelayMillis` property is missing or present but null, the component
269-
is configured with the default value of `5000`. However, if the `exporter`
270-
property is missing or present but null, Create fails fast since there is no
271-
default value for `exporter`.
265+
Create requirements around default and null behavior are described below. Note that
266+
[`defaultBehavior` and `nullBehavior`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/CONTRIBUTING.md#json-schema-source-and-output)
267+
are defined in the configuration data model.
268+
269+
* If a property is present and the value is null, Create MUST use the
270+
`nullBehavior`, or `defaultBehavior` if `nullBehavior` is not set.
271+
* If a property is required, and not present, Create MUST return an error.
272+
273+
A few examples to illustrate:
274+
275+
* If configuring [`BatchSpanProcessor`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#batchspanprocessor-)
276+
and `schedule_delay` is not present or present but null, the component is
277+
configured according to the `defaultBehavior` of `5000`.
278+
* If configuring [`SpanExporter`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#spanexporter)
279+
and `console` is present and null, the component is configured with a
280+
`console` exporter with default configuration since `console` is nullable.
281+
282+
The [configuration model](data-model.md) uses the JSON schema
283+
[`description`](https://json-schema.org/understanding-json-schema/reference/annotations)
284+
annotation to capture property semantics which cannot be encoded using standard
285+
JSON schema keywords. Create SHOULD return an error if it encounters a value
286+
which is invalid according to the property `description`. For example, if
287+
configuring [`HttpTls`](https://github.com/open-telemetry/opentelemetry-configuration/blob/main/schema-docs.md#httptls-)
288+
and `ca_file` is not an absolute file path as defined in the property
289+
description, return an error.
272290

273291
When encountering a reference to
274292
a [SDK extension component](#sdk-extension-components) which is not built in to

0 commit comments

Comments
 (0)