Split out defaultBehavior and nullBehavior from description in the meta schema

CONTRIBUTING.md

@@ -91,9 +91,11 @@ tracer_provider:
 * `attributes_value_length_limit` is not required. If omitted, no attribute length limits are applied.
 * `attributes_value_length_limit`'s type is `["integer", "null]`. If null (i.e. because the `OTEL_SPAN_ATTRIBUTE_VALUE_LENGTH_LIMIT` env var is unset), no attribute length limits are applied.
 
-If a property is _not_ required, it should include a [meta schema comment](./CONTRIBUTING.md#meta-schema) describing the semantics when it is omitted.
+If a property is _not_ required, it must include `defaultBehavior` in the [meta schema](#meta_schema_typesyaml) describing the semantics when it is omitted.
 
-If a property `type` includes `null`, it must include a [meta schema comment](./CONTRIBUTING.md#meta-schema) describing the semantics when the value is `null`. It's common for properties with primitive types to allow `null`. `object` types allow `null` if no properties are required and the presence of the property key is meaningful.
+If a property is required and `type` includes `null`, it must include `nullBehavior` in the [meta schema](#meta_schema_typesyaml) describing the semantics when it is null.
+
+Optionally, a property which is _not_ required and `type` includes `null` may specify `nullBehavior` to differentiate between cases where it is `null` and omitted.
 
 ### Polymorphic types
 
@@ -274,13 +276,13 @@ There are a variety of build tasks which intersect with the meta schema:
 Content looks like:
 
 ```yaml
-- type: AttributeLimits
+- type: SpanExporter
   properties:
-    - property: attribute_value_length_limit
-      description: |
-        Configure max attribute value size. 
-        Value must be non-negative.
-        If omitted or null, there is no limit.
+    - 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
+    # other properties omitted for brevity
 - type: OtlpHttpEncoding
   enumValues:
     - enumValue: json
@@ -296,7 +298,9 @@ Notes:
   * `[].type` is the name of the JSON schema type. **Maintained automatically by build tooling.**
   * `[].properties` is an array of entries for each property in the JSON schema type. Omitted for enum types.
     * `[].properties[].property` the name of the property. **Maintained automatically by build tooling.**
-    * `[].properties[].description` the property description, including semantics and default behavior.
+    * `[].properties[].description` the property description, including implementation semantics.
+    * `[].properties[].defaultBehavior` the behavior if the property is omitted. Required if the property is not `required`. Must not be present if property is `required`.
+    * `[].properties[].nullBehavior` the behavior if the property is present and null. Required if the property is `required` and may be `null`. Optional to override `defaultBehavior` if the property is not `required`. 
   * `[].enumValues` is an array of entries for each enum value in the JSON schema type. Omitted for non-enum types.
       * `[].enumValues[].enumValue` the name of the enum value. **Maintained automatically by build tooling.**
       * `[].enumValues[].description` the enum value description.
@@ -347,6 +351,8 @@ Ensures that the JSON schema and the meta schema are kept in sync:
 * For each meta schema type:
   * If a property exists in the JSON schema and not the meta schema, add it.
   * If a property exists in the meta schema and not the JSON schema, delete it.
+  * If a property is required in the JSON schema and has defaultBehavior in the meta schema, delete it. If a property is not required in the JSON schema and does not have defaultBehavior in the meta schema, add it.
+  * If a property is required and nullable in the JSON schema and does not have nullBehavior in the meta schema, add it.
 * If a language implementation is known (i.e. defined in constant array `KNOWN_LANGUAGES` in [meta-schema.js](./scripts/meta-schema.js)) but not in meta schema, add it.
 * If a language implementation exists in meta schema but is not known, delete it.
 * For each language implementation:

examples/sdk-config.yaml

@@ -8,24 +8,29 @@
 # The file format version.
 # The yaml format is documented at
 # https://github.com/open-telemetry/opentelemetry-configuration/tree/main/schema
+# Property is required and must be non-null.
 file_format: "1.0-rc.2"
 # Configure if the SDK is disabled or not.
 # If omitted or null, false is used.
 disabled: false
 # Configure the log level of the internal logger used by the SDK.
-# If omitted, info is used.
+# If omitted or null, info is used.
 log_level: info
 # Configure resource for all signals.
 # If omitted, the default resource is used.
 resource:
   # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
+  # If omitted, no resource attributes are added.
   attributes:
     - # The attribute name.
+      # Property is required and must be non-null.
       name: service.name
       # The attribute value.
       # The type of value must match .type.
+      # Property is required and must be non-null.
       value: unknown_service
 # Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
+# If omitted, default values for general attributes are used.
 attribute_limits:
   # Configure max attribute value size. 
   # Value must be non-negative.
@@ -40,18 +45,22 @@ attribute_limits:
 propagator:
   # Configure the propagators in the composite text map propagator. Entries from .composite_list are appended to the list here with duplicates filtered out.
   # Built-in propagator keys include: tracecontext, baggage, b3, b3multi, jaeger, ottrace. Known third party keys include: xray. 
-  # If the resolved list of propagators (from .composite and .composite_list) is empty, a noop propagator is used.
+  # If omitted, and .composite_list is empty, a noop propagator is used.
   composite:
     - # Include the w3c trace context propagator.
+      # If omitted, ignore.
       tracecontext:
     - # Include the w3c baggage propagator.
+      # If omitted, ignore.
       baggage:
 # Configure tracer provider.
 # If omitted, a noop tracer provider is used.
 tracer_provider:
   # Configure span processors.
+  # Property is required and must be non-null.
   processors:
     - # Configure a batch span processor.
+      # If omitted, ignore.
       batch:
         # Configure delay interval (in milliseconds) between two consecutive exports. 
         # Value must be non-negative.
@@ -68,13 +77,16 @@ tracer_provider:
         # If omitted or null, 512 is used.
         max_export_batch_size: 512
         # Configure exporter.
+        # Property is required and must be non-null.
         exporter:
           # Configure exporter to be OTLP with HTTP transport.
+          # If omitted, ignore.
           otlp_http:
             # Configure endpoint, including the signal specific path.
             # If omitted or null, the http://localhost:4318/v1/{signal} (where signal is 'traces', 'logs', or 'metrics') is used.
             endpoint: http://localhost:4318/v1/traces
             # Configure TLS settings for the exporter.
+            # If omitted, system default TLS settings are used.
             tls:
               # Configure certificate used to verify a server's TLS credentials. 
               # Absolute path to certificate file in PEM format.
@@ -98,8 +110,10 @@ tracer_provider:
             timeout: 10000
             # Configure headers. Entries have higher priority than entries from .headers_list.
             # If an entry's .value is null, the entry is ignored.
+            # If omitted, no headers are added.
             headers: []
   # Configure span limits. See also attribute_limits.
+  # If omitted, default span limits are used.
   limits:
     # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. 
     # Value must be non-negative.
@@ -129,38 +143,46 @@ tracer_provider:
   # If omitted, parent based sampler with a root of always_on is used.
   sampler:
     # Configure sampler to be parent_based.
+    # If omitted, ignore.
     parent_based:
       # Configure root sampler.
-      # If omitted or null, always_on is used.
+      # If omitted, always_on is used.
       root:
         # Configure sampler to be always_on.
+        # If omitted, TODO.
         always_on:
       # Configure remote_parent_sampled sampler.
-      # If omitted or null, always_on is used.
+      # If omitted, always_on is used.
       remote_parent_sampled:
         # Configure sampler to be always_on.
+        # If omitted, TODO.
         always_on:
       # Configure remote_parent_not_sampled sampler.
-      # If omitted or null, always_off is used.
+      # If omitted, always_off is used.
       remote_parent_not_sampled:
         # Configure sampler to be always_off.
+        # If omitted, ignore.
         always_off:
       # Configure local_parent_sampled sampler.
-      # If omitted or null, always_on is used.
+      # If omitted, always_on is used.
       local_parent_sampled:
         # Configure sampler to be always_on.
+        # If omitted, TODO.
         always_on:
       # Configure local_parent_not_sampled sampler.
-      # If omitted or null, always_off is used.
+      # If omitted, always_off is used.
       local_parent_not_sampled:
         # Configure sampler to be always_off.
+        # If omitted, ignore.
         always_off:
 # Configure meter provider.
 # If omitted, a noop meter provider is used.
 meter_provider:
   # Configure metric readers.
+  # Property is required and must be non-null.
   readers:
     - # Configure a periodic metric reader.
+      # If omitted, ignore.
       periodic:
         # Configure delay interval (in milliseconds) between start of two consecutive exports. 
         # Value must be non-negative.
@@ -171,13 +193,16 @@ meter_provider:
         # If omitted or null, 30000 is used.
         timeout: 30000
         # Configure exporter.
+        # Property is required and must be non-null.
         exporter:
           # Configure exporter to be OTLP with HTTP transport.
+          # If omitted, ignore.
           otlp_http:
             # Configure endpoint, including the signal specific path.
             # If omitted or null, the http://localhost:4318/v1/{signal} (where signal is 'traces', 'logs', or 'metrics') is used.
             endpoint: http://localhost:4318/v1/metrics
             # Configure TLS settings for the exporter.
+            # If omitted, system default TLS settings are used.
             tls:
               # Configure certificate used to verify a server's TLS credentials. 
               # Absolute path to certificate file in PEM format.
@@ -201,25 +226,28 @@ meter_provider:
             timeout: 10000
             # Configure headers. Entries have higher priority than entries from .headers_list.
             # If an entry's .value is null, the entry is ignored.
+            # If omitted, no headers are added.
             headers: []
             # Configure temporality preference.
             # Values include: cumulative, delta, low_memory. For behavior of values, see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md.
-            # If omitted or null, cumulative is used.
+            # If omitted, cumulative is used.
             temporality_preference: cumulative
             # Configure default histogram aggregation.
             # Values include: explicit_bucket_histogram, base2_exponential_bucket_histogram. For behavior of values, see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk_exporters/otlp.md.
-            # If omitted or null, explicit_bucket_histogram is used.
+            # If omitted, explicit_bucket_histogram is used.
             default_histogram_aggregation: explicit_bucket_histogram
   # Configure the exemplar filter. 
   # Values include: trace_based, always_on, always_off. For behavior of values see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#metrics-sdk-configuration.
-  # If omitted or null, trace_based is used.
+  # If omitted, trace_based is used.
   exemplar_filter: trace_based
 # Configure logger provider.
 # If omitted, a noop logger provider is used.
 logger_provider:
   # Configure log record processors.
+  # Property is required and must be non-null.
   processors:
     - # Configure a batch log record processor.
+      # If omitted, ignore.
       batch:
         # Configure delay interval (in milliseconds) between two consecutive exports. 
         # Value must be non-negative.
@@ -236,13 +264,16 @@ logger_provider:
         # If omitted or null, 512 is used.
         max_export_batch_size: 512
         # Configure exporter.
+        # Property is required and must be non-null.
         exporter:
           # Configure exporter to be OTLP with HTTP transport.
+          # If omitted, ignore.
           otlp_http:
             # Configure endpoint, including the signal specific path.
             # If omitted or null, the http://localhost:4318/v1/{signal} (where signal is 'traces', 'logs', or 'metrics') is used.
             endpoint: http://localhost:4318/v1/logs
             # Configure TLS settings for the exporter.
+            # If omitted, system default TLS settings are used.
             tls:
               # Configure certificate used to verify a server's TLS credentials. 
               # Absolute path to certificate file in PEM format.
@@ -266,8 +297,10 @@ logger_provider:
             timeout: 10000
             # Configure headers. Entries have higher priority than entries from .headers_list.
             # If an entry's .value is null, the entry is ignored.
+            # If omitted, no headers are added.
             headers: []
   # Configure log record limits. See also attribute_limits.
+  # If omitted, default log record limits are used.
   limits:
     # Configure max attribute value size. Overrides .attribute_limits.attribute_value_length_limit. 
     # Value must be non-negative.