Versioning

This document describes the versioning policy for this repository.

NOTICE: The versioning policy is 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.

Versioning policy consists of the following sections:

• Objectives: Overview of the motivation behind versioning.
• Guarantees and allowed changes: Specific details on allowed and disallowed changes within the versioning policy.
• Applicability: Limits of the versioning policy, 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 the versioning policy 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 versioning policy as defined by respective language SIGs, and which users expect to reliably upgrade. The versioning policy informs 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][annotation] will not change.
• Types will 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: 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. minContains will not increase; maxContains will not decrease.
  • minItems, maxItems: minItems will not increase, maxItems will not decrease.
  • uniqueItems: will not go from false to true.
  • enum: will not remove stable values.
  • const: will not change.
  • isSdkExtensionPlugin: will not change.
• No existing type will be deleted.
• No type property will be deleted.

The following additive changes are allowed:

• Adding new properties to existing types.
• Adding new types.
• Changes that make property validation less strict. See above for examples.
• Removing a property from required.
• Modifying description [annotation][], as long as the updated semantics do not break users. [1]
• Modifying defaultBehavior, as long as the updated semantics do not break users. [1]
• Modifying nullBehavior, as long as the updated semantics do not break users. [1]
• Modifying enumDescriptions, as long as the updated semantics do not break users. [1]
• Adding, removing, or modifying deprecated [annotation][].

[1]: desciption, defaultBehavior, nullBehavior, and enumDescriptions each play in describing property semantics, important for both users and language implementation maintainers. These fields are written in plain english, and therefore it's not possible to have a rigid policy around what changes are allowed. Instead, we follow the principle: don't break users. What constitutes a breaking change will be decided on a case-by-case basis and is left to the judgment of project maintainers.

Applicability

The versioning policy guarantees do not apply to experimental features and extension points.

Experimental features

Sometimes we need to experiment with new types, properties, and enum values, e.g. when evaluating the configuration experience for experimental features in opentelemetry-specification.

Experimental properties and enum values 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 versioning policy 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 not obligated to maintain any versioning policy 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 that are designed for extension, as indicated by the presence of "additionalProperties": true. For example, plugin component provider provides mechanisms for referencing custom SDK extension components like exporters, processors, samplers, etc. The versioning policy guarantees surrounding properties not explicitly defined in this repository are out of scope. Users should consult documentation for the components interpreting these additional properties and decide if their versioning policy is 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 that 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.