Split out defaultBehavior and nullBehavior from description in the meta schema#357
Closed
jack-berg wants to merge 6 commits intoopen-telemetry:mainfrom
Closed
Split out defaultBehavior and nullBehavior from description in the meta schema#357jack-berg wants to merge 6 commits intoopen-telemetry:mainfrom
jack-berg wants to merge 6 commits intoopen-telemetry:mainfrom
Conversation
jack-berg
commented
Oct 31, 2025
| - property: otlp_http | ||
| description: Configure exporter to be OTLP with HTTP transport. | ||
| defaultBehavior: OTLP HTTP exporter is not used | ||
| nullBehavior: OTLP HTTP exporter is used with defaults |
Member
Author
There was a problem hiding this comment.
This example illustrates a case where both defaultBehavior and nullBehavior are needed.
The common case is to define only defaultBehavior, which describes semantics when the field is EITHER omitted or null.
jack-berg
commented
Oct 31, 2025
| # If omitted, always_on is used. | ||
| root: | ||
| # Configure sampler to be always_on. | ||
| # If omitted, ignore. |
Member
Author
There was a problem hiding this comment.
These comments are useful and precise, but starting to seem overly verbose. Perhaps in a followup PR, we strip the example comments down to something more terse, and save the details for schema-docs.md.
…y-configuration into meta-schema-default-behavior
…y-configuration into meta-schema-default-behavior
…y-configuration into meta-schema-default-behavior
This was referenced Nov 11, 2025
Member
Author
|
Superseded by #426. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Currently, all the semantics of properties are bundled up in the
[].properties[].descriptionfield ofmeta_schema_types.yaml. This includes a terse description, various details about allowable values and semantics, and default behavior.We schema modeling guidance which states that the description MUST include details about the semantics when the property is omitted / null.
These details are an important part of the stability contract and for ensuring consistency across language implementations.
However, enforcement of this guidance is very difficult / error prone, and as we'll see in this PR, there are many instances where we have failed to provide those details.
This PR adds two new fields to the meta schema:
defaultBehaviordescribes the behavior when a property is omitted (and in some cases when it is null). Build tooling enforces that this field is present if a property is not required, and that the field is not present if a property is required.nullBehaviordescribes the behavior when a property is null (ifdefaultBehavioris not defined). This allows us to define separate semantics for when a field is omitted entirely vs. present but with the value set to null. Build tooling enforces that this field is present if a property is required and is nullable. It can optionally be added to any non-required field.If approved, I will go back in a followup PR and replace all the
TODOvalues with proper descriptions.Ironing out these semantics now will help ensure we have a more robust first stable release.