diff --git a/README.md b/README.md index fb2ee71..6c598c1 100644 --- a/README.md +++ b/README.md @@ -204,6 +204,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. + ## Schemas and subschemas In JSON Schema, a [schema](https://json-schema.org/learn/glossary#schema) is a document, and a [subschema](https://json-schema.org/learn/glossary#subschema) is contained in surrounding parent schema. Subschemas can be nested in various ways: diff --git a/schema/common.json b/schema/common.json index 1c02cd0..2b588bb 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": { @@ -82,7 +80,6 @@ ] }, "OtlpGrpcExporter": { - "title": "OtlpGrpcExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { diff --git a/schema/instrumentation.json b/schema/instrumentation.json index 53a2822..4ad3715 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 3b7bbd1..626be35 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 5a0f163..a68f497 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": { @@ -57,8 +56,7 @@ }, "required": [ "exporter" - ], - "title": "PeriodicMetricReader" + ] }, "PullMetricReader": { "type": "object", @@ -76,8 +74,7 @@ }, "required": [ "exporter" - ], - "title": "PullMetricReader" + ] }, "PushMetricExporter": { "type": "object", @@ -141,7 +138,6 @@ "additionalProperties": false }, "PrometheusMetricExporter": { - "title": "PrometheusMetricExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -180,7 +176,6 @@ } }, "ExporterTemporalityPreference": { - "title": "ExporterTemporalityPreference", "type": ["string", "null"], "enum": [ "cumulative", @@ -189,7 +184,6 @@ ] }, "ExporterDefaultHistogramAggregation": { - "title": "ExporterDefaultHistogramAggregation", "type": ["string", "null"], "enum": [ "explicit_bucket_histogram", @@ -197,7 +191,6 @@ ] }, "OtlpHttpMetricExporter": { - "title": "OtlpHttpMetricExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -241,7 +234,6 @@ } }, "OtlpGrpcMetricExporter": { - "title": "OtlpGrpcMetricExporter", "type": ["object", "null"], "additionalProperties": false, "properties": { @@ -312,7 +304,6 @@ } }, "ViewSelector": { - "title": "Selector", "type": "object", "additionalProperties": false, "properties": { @@ -348,7 +339,6 @@ ] }, "ViewStream": { - "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 1b3cf43..141b1c5 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": { @@ -64,7 +62,6 @@ ] }, "Detectors": { - "title": "Detectors", "type": "object", "additionalProperties": false, "properties": { diff --git a/schema/tracer_provider.json b/schema/tracer_provider.json index 2a0e704..da92f08 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"], @@ -136,7 +134,6 @@ "SimpleSpanProcessor": { "type": "object", "additionalProperties": false, - "title": "SimpleSpanProcessor", "properties": { "exporter": { "$ref": "#/$defs/SpanExporter" @@ -224,7 +221,6 @@ } }, "ZipkinSpanExporter": { - "title": "ZipkinSpanExporter", "type": ["object", "null"], "additionalProperties": false, "properties": {