JSON Schema Definitions for OpenTelemetry Declarative Configuration

This repository contains the JSON schema that defines the OpenTelemetry configuration. This schema can be utilized to generate model code for implementations and to validate the structure of a configuration file. The repository comes as a result of OTEP #225, where JSON schema was chosen for the following reasons:

• support for client-side validation
• code generation
• broad support across languages

Starter templates

The examples directory contains a variety of sample configuration files to help get started and illustrate useful patterns. The following are noteworthy:

• sdk-migration-config.yaml: Includes env var substitution references to all standard env vars which map cleanly to declarative configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via env var substitution. This is a great starting point for transitioning from env var based configuration to file based configuration.
• sdk-config.yaml: Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via env var substitution.

Code generation

There are several tools available to generate code from a JSON schema. The following shows an example for generating code from the JSON schema in Go:

go-jsonschema \
    -p telemetry \
    --schema-package=https://opentelemetry.io/otelconfig/opentelemetry_configuration.json=github.com/open-telemetry/opentelemetry-collector/schema \
    ./schema/opentelemetry_configuration.json

Stability definition

NOTICE: The stability definitions are applicable after this repository publishes a stable release (1.0.0). Currently, this repository is experimental and makes no stability guarantees.

This repository strictly follows Semantic Versioning 2.0.0. This means that all releases have a version following the format MAJOR.MINOR.PATCH.

Stability definition consists of the following sections:

• Objectives: Overview of the motivation behind stability.
• Guarantees and allowed changes: Specific details on allowed and disallowed changes within stability guarantees.
• Applicability: Limits of stability definitions, including experimental features and extension points.
• File format: The file_format property and implementation behavior when schema versions are not aligned.

Objective

The objective of stability is to protect users from breaking changes. That is, users providing configuration conforming to a particular stable MAJOR version of the schema expect to reliably upgrade MINOR and PATCH versions without risk that their configuration becomes invalid, or that the interpretation changes.

Similarly, language implementations are expected to provide in-memory configuration model representations, which have their own stability guarantees as defined by respective language SIGs, and which users expect to reliably upgrade. The stability guarantees inform maintainers on the types of changes they need to consider when creating these representations, which may be produced "by hand" or with code generation logic. NOTE: There is no guarantee that the output of off-the-shelf code generation tools will be stable when allowed changes are made.

All schema changes are considered through the lens of maintaining this objective.

Guarantees and allowed changes

The following guarantees apply to MINOR version changes. There are no guarantees for MAJOR version changes.

A type is the JSON schema analog to a protobuf message. Types have a type of object, and use various keywords to describe their properties and conditions which constitute valid data.

Stable types provide the following guarantees. All types except those excluded in applicability are considered stable after a 1.0.0 release.

• Type property names will not change.
• The type of properties will not change, except the allowed addition of null.
• Type title will not change.
• Types will be not change to make validation more strict. Changes may occur if they make validation less strict. This applies to the following keywords. Examples are given, but they are not exhaustive.
  • minLength, maxLength: minLength will not increase and maxLength will not decrease.
  • pattern: pattern will not become stricter.
  • format: will not change.
  • multipleOf: will not change.
  • minimum, exclusiveMinimum, maximum, exclusiveMaximum: minimum, exclusiveMinimum will not increase; maximum, exclusiveMaximum will not decrease.
  • patternProperties: will not expand scope to restrict additional properties.
  • additionalProperties: will not go from true to false.
  • propertyNames: will not become stricter.
  • minProperties, maxProperties: minProperties will not increase, maxProperties will not decrease.
  • required: will not add additional entries.
  • contains, minContains, maxContains: will not become stricter.
  • minItems, maxItems: minItems will not increase, maxItems will not decrease.
  • uniqueItems: will not go from false to true.
  • enum: will not remove entries.
  • const: will not change.
• No existing type will be deleted.
• No type property will be deleted.

The following additive changes are allowed:

• Adding of new properties to existing types.
• Adding new types.
• Changes that make property validation less strict. See above for examples.
• Removing a property from required.
• Adding, removing, or modifying description annotation.
• Adding, removing, or modifying deprecated annotation.

Applicability

Stability guarantees do not apply to experimental features and extension points.

Experimental features

Sometimes we need to experiment with new types and properties. For example, to evaluate the configuration experience for experimental features in opentelemetry-specification.

Experimental properties are denoted by a */(development|alpha|beta) suffix (e.g.foo/development). The suffix indicates the property value and all types nested within it are exempt from stability guarantees, and are subject to breaking changes in minor versions. Experimental type key values in $defs should be prefixed with Experimental* (e.g. ExperimentalFoo). Note that because we omit the title annotation, the $defs key value effectively acts as the type title for code generation tools.

Maintainers are not obligated to implement support for experimental properties and types. When they do, they are no obligated to maintain any stability guarantees.

End users should be cautious of adopting experimental properties and types, since in doing so they are subject to breaking changes in MINOR versions.

Extension points

The schema contains types which are designed for extension, as indicated by the presence of "additionalProperties": true. For example, component provider provides mechanisms for referencing custom SDK extension components like exporters, processors, samplers, etc. The stability guarantees surrounding properties not explicitly defined in this repository is out of scope. Users should consult documentation for the components interpreting these additional properties and decide if their stability guarantees are sufficient for adoption.

File format

The top level .file_format property is special in that it conveys the version of the schema a user's configuration conforms to. Implementations also target a particular version of the schema, which may or may not align with the version specified by the user.

Given the guarantees and allowed changes, implementations may encounter the following scenarios:

• The file_format MAJOR version aligns with the implementation MAJOR version, AND:
  • The file_format MINOR version is less than or equal to the implementation MINOR version: This is ideal, with versions maximally aligned. Despite this, an implementation might not support every property and type of its target version.
  • The file_format MINOR version is greater than the implementation MINOR version: The implementation should detect and emit a warning since there may be configuration features the user specifies which the implementation does not understand. However, this is acceptable in many cases, and not terribly different from the ideal path where an implementation also might not support every configuration feature.
• The file_format MAJOR version does not align with the implementation MAJOR version. The implementation should produce an error, since there may be breaking changes in the properties and semantics on how they are interpreted. Implementations may choose to temporarily support multiple major version to accommodate transitioning users.

Contributing

See CONTRIBUTING.md

Approvers (@open-telemetry/configuration-approvers):

• Brett McBride, Deakin University
• Marc Alff, Oracle

Find more about the approver role in community repository.

Maintainers (@open-telemetry/configuration-maintainers):

• Alex Boten, Honeycomb
• Jack Berg, New Relic
• Tristan Sloughter, MyDecisiveAI
• Tyler Yahn, Splunk

Find more about the maintainer role in community repository.