Define modeling guidance for mismatches with standard env vars, add .resource.attribute_list (#106)

Co-authored-by: Alex Boten <223565+codeboten@users.noreply.github.com>

Author: jack-berg

README.md

@@ -12,7 +12,7 @@ This repository contains the JSON schema that defines the OpenTelemetry configur
 
 The [examples](./examples) repository contains a variety of sample configuration files to help get started and illustrate useful patterns. The following are noteworthy:
 
-- [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard environment variables](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) which map cleanly to file configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. This is a great starting point for transitioning from env var based configuration to file based configuration.
+- [sdk-migration-config.yaml](./examples/sdk-migration-config.yaml): Includes env var substitution references to all [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) which map cleanly to file configuration (see notes in the example for the set of env vars which are not referenced). Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][]. This is a great starting point for transitioning from env var based configuration to file based configuration.
 - [sdk-config.yaml](./examples/sdk-config.yaml): Represents the typical default configuration. This is a good starting point if you are not using env var based configuration or wish to transition fully to file based configuration. Note, SDKs parsing configuration files ignore all env vars besides those referenced via [env var substitution][].
 
 [env var substitution]: https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/file-configuration.md#environment-variable-substitution
@@ -63,3 +63,9 @@ When a property requires pattern matching, use wildcard `*` (match any number of
 * Given `excluded: ["a*"]`: Match all except values starting with `a`.
 * Given `included: ["a*", "b*"]`, `excluded: ["ab*"]`: Match any value starting with `a` or `b`, excluding values starting with `ab`.
 * Given `included: ["a", "b"]`, `excluded: ["a"]`: Match values equal to `b`.
+
+### Data modeling and environment variable substitution
+
+Properties should be modeled using the most appropriate data structures and types to represent the information. This may result in a schema which doesn't support env var substitution for the [standard env vars](https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md) where a type mismatch occurs. For example, the `OTEL_RESOURCE_ATTRIBUTES` env var is modeled as a string, consisting of a comma separated list of key-value pairs, which is not the natural way to model a mapping of key-value pairs in JSON schema. 
+
+In instances where there is a type mismatch between the JSON schema and equivalent standard env var, an alternative version of the property may be provided to resolve the mismatch. For example, resource attributes are configured at `.resource.attributes`, but `.resource.attributes_list` is available with a format matching that of `OTEL_RESOURCE_ATTRIBUTES`. Alternative properties are reserved for cases where there is a demonstrated need for platforms to be able to participate in configuration and there is no reasonable alternative.

examples/kitchen-sink.yaml

@@ -406,14 +406,18 @@ tracer_provider:
 
 # Configure resource for all signals.
 resource:
-  # Configure resource attributes.
+  # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
   #
   # Environment variable: OTEL_RESOURCE_ATTRIBUTES
   attributes:
     # Configure `service.name` resource attribute
     #
     # Environment variable: OTEL_SERVICE_NAME
     service.name: !!str "unknown_service"
+  # Configure resource attributes. Entries have lower priority than entries from .resource.attributes.
+  #
+  # The value is a list of comma separated key-value pairs,  matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
+  attributes_list: "service.namespace=my-namespace,service.version=1.0.0"
   # Configure resource detectors.
   detectors:
     # Configure attributes provided by resource detectors.

examples/sdk-migration-config.yaml

@@ -14,7 +14,6 @@
 # for more information. The following spec defined env vars are NOT referenced and are thus
 # ignored:
 #
-# - OTEL_RESOURCE_ATTRIBUTES
 # - OTEL_LOG_LEVEL
 # - OTEL_PROPAGATORS
 # - OTEL_TRACES_SAMPLER
@@ -45,10 +44,14 @@ disabled: ${OTEL_SDK_DISABLED:-false}
 
 # Configure resource for all signals.
 resource:
-  # Configure resource attributes.
+  # Configure resource attributes. Entries have higher priority than entries from .resource.attributes_list.
   attributes:
     # Configure `service.name` resource attribute
     service.name: ${OTEL_SERVICE_NAME:-unknown_service}
+  # Configure resource attributes. Entries have lower priority than entries from .resource.attributes.
+  #
+  # The value is a list of comma separated key-value pairs, matching the format of OTEL_RESOURCE_ATTRIBUTES. See https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/configuration/sdk-environment-variables.md#general-sdk-configuration for details.
+  attributes_list: ${OTEL_RESOURCE_ATTRIBUTES}
 
 # Configure general attribute limits. See also tracer_provider.limits, logger_provider.limits.
 attribute_limits:

schema/resource.json

@@ -13,6 +13,9 @@
         },
         "schema_url": {
             "type": ["string", "null"]
+        },
+        "attributes_list": {
+            "type": ["string", "null"]
         }
     },
     "$defs": {