JSON Schema Definitions for OpenTelemetry File 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

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

Before reaching 1.0, each minor version change is equivalent to major version change. That is, there are no guarantees about compatibility and all changes are permitted. As of 1.0, we provide the following stability guarantees:

For major version: No guarantees.
For minor versions: TBD

Allowable changes:

For major versions: All changes are permitted.
For minor versions: TBD

Schema modeling rules

The following rules are enforced when modeling the configuration schema:

What properties are part of schema?

Only properties which are described in opentelemetry-specification or semantic-conventions are modeled in the schema. However, it's acceptable to allow additional properties specific to a particular language or implementation, and not covered by the schema. Model these by setting "additionalProperties": true (see JSON schema additionalProperties). Types should set "additionalProperties": false by default unless requested by an opentelemetry component maintainer which supports additional options.

Property naming

To remove redundant information from the configuration file, prefixes for data produced by each of the providers will be removed from configuration options. For example, under the meter_provider configuration, metric readers are identified by the word readers rather than by metric_readers. Similarly, the prefix span_ will be dropped for tracer provider configuration, and logrecord for logger provider.

Property name case

Properties defined in the schema should be lower snake case.

Properties which pattern matching

When a property requires pattern matching, use wildcard * (match any number of any character, including none) and ? (match any single character) instead of regex. If a single property with wildcards is likely to be insufficient to model the configuration requirements, accept included and excluded properties, each with an array of strings with wildcard entries. The wildcard entries should be joined with a logical OR. If included is not specified, assume that all entries are included. Apply excluded after applying included. Examples:

Given excluded: ["a*"]: Match all except values starting with a.
Given included: ["a*", "b*"], excluded: ["ab*"]: Match any value starting with a or b, excluding values starting with ab.
Given included: ["a", "b"], excluded: ["a"]: Match values equal to b.

marcalff / opentelemetry-configuration