From 345e8632f6c72c52baddf0e04df27654879acf46 Mon Sep 17 00:00:00 2001 From: Jack Berg Date: Tue, 14 Jan 2025 15:31:13 -0600 Subject: [PATCH] Add guidance around use of title and description keywords --- README.md | 9 ++++++++ schema/common.json | 3 --- schema/instrumentation.json | 1 - schema/logger_provider.json | 1 - schema/meter_provider.json | 14 ++---------- schema/opentelemetry_configuration.json | 30 ++++++++++++++++++++----- schema/propagator.json | 1 - schema/resource.json | 3 --- schema/tracer_provider.json | 4 ---- 9 files changed, 35 insertions(+), 31 deletions(-) diff --git a/README.md b/README.md index 003d1e8..11ef17b 100644 --- a/README.md +++ b/README.md @@ -185,6 +185,15 @@ Another example: `oneOf` is used to specify that the `value` property matches the [standard attribute](https://github.com/open-telemetry/opentelemetry-specification/tree/main/specification/common#standard-attribute) definition, and is either a primitive or array of primitives. This type of use is acceptable but should be used judiciously. +### Annotations - title and description + +The JSON schema [`title` and `description` annotations](https://json-schema.org/understanding-json-schema/reference/annotations) are keywords which are not involved in validation. Instead, they act as a mechanism to help schemas be self-documenting, and may be used by code generation tools. + +Despite these potential benefits, these keywords should be omitted: + +* The titles of `object` and `enum` types produced by code generation tools should be defined using key values in [$defs](https://json-schema.org/understanding-json-schema/structuring#defs). Setting the `title` keyword introduces multiple sources of truth and possible conflict. +* As described in [description generation](./CONTRIBUTING.md#description-generation), we use a different mechanism to describe the semantics of types and properties. Setting the `description` keyword introduces multiple sources of truth and possible conflict. + ## Contributing See [CONTRIBUTING.md](CONTRIBUTING.md) diff --git a/schema/common.json b/schema/common.json index 6ee683f..a30bdfc 100644 --- a/schema/common.json +++ b/schema/common.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/common.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Common", "$defs": { "IncludeExclude": { "type": "object", @@ -37,7 +36,6 @@ ] }, "OtlpHttpExporter": { - "title": "OtlpHttpExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -79,7 +77,6 @@ } }, "OtlpGrpcExporter": { - "title": "OtlpGrpcExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { diff --git a/schema/instrumentation.json b/schema/instrumentation.json index cf93ef6..6846e15 100644 --- a/schema/instrumentation.json +++ b/schema/instrumentation.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/instrumentation.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Instrumentation", "type": "object", "additionalProperties": false, "properties": { diff --git a/schema/logger_provider.json b/schema/logger_provider.json index 52f6bf0..2672cbb 100644 --- a/schema/logger_provider.json +++ b/schema/logger_provider.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/logger_provider.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "LoggerProvider", "type": "object", "additionalProperties": false, "properties": { diff --git a/schema/meter_provider.json b/schema/meter_provider.json index 5dd33ad..7fa48f2 100644 --- a/schema/meter_provider.json +++ b/schema/meter_provider.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/meter_provider.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "MeterProvider", "type": "object", "additionalProperties": false, "properties": { @@ -54,8 +53,7 @@ }, "required": [ "exporter" - ], - "title": "PeriodicMetricReader" + ] }, "PullMetricReader": { "type": "object", @@ -73,8 +71,7 @@ }, "required": [ "exporter" - ], - "title": "PullMetricReader" + ] }, "PushMetricExporter": { "type": "object", @@ -132,7 +129,6 @@ } }, "PrometheusMetricExporter": { - "title": "PrometheusMetricExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -171,7 +167,6 @@ } }, "ExporterTemporalityPreference": { - "title": "ExporterTemporalityPreference", "type": ["string", "null"], "enum": [ "cumulative", @@ -180,7 +175,6 @@ ] }, "ExporterDefaultHistogramAggregation": { - "title": "ExporterDefaultHistogramAggregation", "type": ["string", "null"], "enum": [ "explicit_bucket_histogram", @@ -188,7 +182,6 @@ ] }, "OtlpHttpMetricExporter": { - "title": "OtlpHttpMetricExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -236,7 +229,6 @@ } }, "OtlpGrpcMetricExporter": { - "title": "OtlpGrpcMetricExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -284,7 +276,6 @@ "additionalProperties": false, "properties": { "selector": { - "title": "Selector", "type": "object", "additionalProperties": false, "properties": { @@ -317,7 +308,6 @@ } }, "stream": { - "title": "Stream", "type": "object", "additionalProperties": false, "properties": { diff --git a/schema/opentelemetry_configuration.json b/schema/opentelemetry_configuration.json index 2bd1a2b..d8d4bab 100644 --- a/schema/opentelemetry_configuration.json +++ b/schema/opentelemetry_configuration.json @@ -15,22 +15,22 @@ "$ref": "#/$defs/AttributeLimits" }, "logger_provider": { - "$ref": "logger_provider.json" + "$ref": "#/$defs/LoggerProvider" }, "meter_provider": { - "$ref": "meter_provider.json" + "$ref": "#/$defs/MeterProvider" }, "propagator": { - "$ref": "propagator.json" + "$ref": "#/$defs/Propagator" }, "tracer_provider": { - "$ref": "tracer_provider.json" + "$ref": "#/$defs/TracerProvider" }, "resource": { - "$ref": "resource.json" + "$ref": "#/$defs/Resource" }, "instrumentation": { - "$ref": "instrumentation.json" + "$ref": "#/$defs/Instrumentation" } }, "required": [ @@ -48,6 +48,24 @@ "type": ["integer", "null"] } } + }, + "LoggerProvider": { + "$ref": "logger_provider.json" + }, + "MeterProvider": { + "$ref": "meter_provider.json" + }, + "TracerProvider": { + "$ref": "tracer_provider.json" + }, + "Propagator": { + "$ref": "propagator.json" + }, + "Resource": { + "$ref": "resource.json" + }, + "Instrumentation": { + "$ref": "instrumentation.json" } } } diff --git a/schema/propagator.json b/schema/propagator.json index a2bf235..633572b 100644 --- a/schema/propagator.json +++ b/schema/propagator.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/propagator.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Propagator", "type": "object", "properties": { "composite": { diff --git a/schema/resource.json b/schema/resource.json index b419546..1cdf4d9 100644 --- a/schema/resource.json +++ b/schema/resource.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/resource.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "Resource", "type": "object", "additionalProperties": false, "properties": { @@ -23,7 +22,6 @@ }, "$defs": { "AttributeNameValue": { - "title": "AttributeNameValue", "type": "object", "additionalProperties": false, "properties": { @@ -61,7 +59,6 @@ ] }, "Detectors": { - "title": "Detectors", "type": "object", "additionalProperties": false, "properties": { diff --git a/schema/tracer_provider.json b/schema/tracer_provider.json index 1471278..22a1a2a 100644 --- a/schema/tracer_provider.json +++ b/schema/tracer_provider.json @@ -1,7 +1,6 @@ { "$id": "https://opentelemetry.io/otelconfig/tracer_provider.json", "$schema": "https://json-schema.org/draft/2020-12/schema", - "title": "TracerProvider", "type": "object", "additionalProperties": false, "properties": { @@ -25,7 +24,6 @@ "BatchSpanProcessor": { "type": "object", "additionalProperties": false, - "title": "BatchSpanProcessor", "properties": { "schedule_delay": { "type": ["integer", "null"], @@ -121,7 +119,6 @@ "SimpleSpanProcessor": { "type": "object", "additionalProperties": false, - "title": "SimpleSpanProcessor", "properties": { "exporter": { "$ref": "#/$defs/SpanExporter" @@ -206,7 +203,6 @@ } }, "ZipkinSpanExporter": { - "title": "ZipkinSpanExporter", "type": ["object", "null"], "additionalProperties": false, "properties": {