Automate enum descriptions

schema/common.yaml

@@ -81,7 +81,7 @@ $defs:
           - "null"
         description: |
           Configure compression.
-          Values include: gzip, none. Implementations may support other compression algorithms.
+          Known values include: gzip, none. Implementations may support other compression algorithms.
         defaultBehavior: none is used
       timeout:
         type:
@@ -96,7 +96,7 @@ $defs:
         $ref: "#/$defs/OtlpHttpEncoding"
         description: |
           Configure the encoding used for messages. 
-          Values include: protobuf, json. Implementations may not support json.
+          Implementations may not support json.
         defaultBehavior: protobuf is used
   OtlpHttpEncoding:
     type:
@@ -148,7 +148,7 @@ $defs:
           - "null"
         description: |
           Configure compression.
-          Values include: gzip, none. Implementations may support other compression algorithms.
+          Known values include: gzip, none. Implementations may support other compression algorithms.
         defaultBehavior: none is used
       timeout:
         type:

schema/logger_provider.yaml

@@ -190,7 +190,6 @@ $defs:
         description: |
           Configure severity filtering.
           Log records with an non-zero (i.e. unspecified) severity number which is less than minimum_severity are not processed.
-          Values include: TRACE, TRACE2, TRACE3, TRACE4, DEBUG, DEBUG2, DEBUG3, DEBUG4, INFO, INFO2, INFO3, INFO4, WARN, WARN2, WARN3, WARN4, ERROR, ERROR2, ERROR3, ERROR4, FATAL, FATAL2, FATAL3, FATAL4.
         defaultBehavior: severity filtering is not applied
       trace_based:
         type:

schema/meter_provider.yaml

@@ -20,7 +20,6 @@ properties:
     $ref: "#/$defs/ExemplarFilter"
     description: |
       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.
     defaultBehavior: trace_based is used
   meter_configurator/development:
     $ref: "#/$defs/ExperimentalMeterConfigurator"
@@ -273,14 +272,7 @@ $defs:
         defaultBehavior: no resource attributes are added
       translation_strategy:
         $ref: "#/$defs/ExperimentalPrometheusTranslationStrategy"
-        description: |
-          Configure how Prometheus metrics are exposed. Values include:
-
-           * UnderscoreEscapingWithSuffixes, the default. This fully escapes metric names for classic Prometheus metric name compatibility, and includes appending type and unit suffixes.
-           * UnderscoreEscapingWithoutSuffixes, metric names will continue to escape special characters to _, but suffixes won't be attached.
-           * NoUTF8EscapingWithSuffixes will disable changing special characters to _. Special suffixes like units and _total for counters will be attached.
-           * NoTranslation. This strategy bypasses all metric and label name translation, passing them through unaltered.
-
+        description: Configure how Prometheus metrics are exposed.
         defaultBehavior: UnderscoreEscapingWithSuffixes is used
   ExperimentalPrometheusTranslationStrategy:
     type:
@@ -372,7 +364,7 @@ $defs:
           - "null"
         description: |
           Configure compression.
-          Values include: gzip, none. Implementations may support other compression algorithms.
+          Known values include: gzip, none. Implementations may support other compression algorithms.
         defaultBehavior: none is used
       timeout:
         type:
@@ -387,19 +379,17 @@ $defs:
         $ref: common.yaml#/$defs/OtlpHttpEncoding
         description: |
           Configure the encoding used for messages. 
-          Values include: protobuf, json. Implementations may not support json.
+          Implementations may not support json.
         defaultBehavior: protobuf is used
       temporality_preference:
         $ref: "#/$defs/ExporterTemporalityPreference"
         description: |
           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.
         defaultBehavior: cumulative is used
       default_histogram_aggregation:
         $ref: "#/$defs/ExporterDefaultHistogramAggregation"
         description: |
           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.
         defaultBehavior: explicit_bucket_histogram is used
   OtlpGrpcMetricExporter:
     type:
@@ -441,7 +431,7 @@ $defs:
           - "null"
         description: |
           Configure compression.
-          Values include: gzip, none. Implementations may support other compression algorithms.
+          Known values include: gzip, none. Implementations may support other compression algorithms.
         defaultBehavior: none is used
       timeout:
         type:
@@ -456,13 +446,11 @@ $defs:
         $ref: "#/$defs/ExporterTemporalityPreference"
         description: |
           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.
         defaultBehavior: cumulative is used
       default_histogram_aggregation:
         $ref: "#/$defs/ExporterDefaultHistogramAggregation"
         description: |
           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.
         defaultBehavior: explicit_bucket_histogram is used
   ExperimentalOtlpFileMetricExporter:
     type:
@@ -482,13 +470,11 @@ $defs:
         $ref: "#/$defs/ExporterTemporalityPreference"
         description: |
           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.
         defaultBehavior: cumulative is used
       default_histogram_aggregation:
         $ref: "#/$defs/ExporterDefaultHistogramAggregation"
         description: |
           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.
         defaultBehavior: explicit_bucket_histogram is used
   ConsoleMetricExporter:
     type:
@@ -500,13 +486,11 @@ $defs:
         $ref: "#/$defs/ExporterTemporalityPreference"
         description: |
           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.
         defaultBehavior: cumulative is used
       default_histogram_aggregation:
         $ref: "#/$defs/ExporterDefaultHistogramAggregation"
         description: |
           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.
         defaultBehavior: explicit_bucket_histogram is used
   View:
     type: object
@@ -538,7 +522,6 @@ $defs:
         $ref: "#/$defs/InstrumentType"
         description: |
           Configure instrument type selection criteria.
-          Values include: counter, gauge, histogram, observable_counter, observable_gauge, observable_up_down_counter, up_down_counter.
         defaultBehavior: all instrument types match
       unit:
         type:
@@ -610,7 +593,6 @@ $defs:
         $ref: "#/$defs/Aggregation"
         description: |
           Configure aggregation of the resulting stream(s). 
-          Values include: default, drop, explicit_bucket_histogram, base2_exponential_bucket_histogram, last_value, sum. For behavior of values see https://github.com/open-telemetry/opentelemetry-specification/blob/main/specification/metrics/sdk.md#aggregation.
         defaultBehavior: default is used
       aggregation_cardinality_limit:
         type:

schema/resource.yaml

@@ -63,7 +63,6 @@ $defs:
         $ref: "#/$defs/AttributeType"
         description: |
           The attribute type.
-          Values include: string, bool, int, double, string_array, bool_array, int_array, double_array.
         defaultBehavior: string is used
     required:
       - name

scripts/compile-schema.js

@@ -27,14 +27,14 @@ sourceTypes.sort((a, b) => a.type.localeCompare(b.type));
 const defs = {};
 sourceTypes.filter(sourceSchemaType => sourceSchemaType.type !== rootTypeName)
     .forEach(sourceSchemaType => {
-        defs[sourceSchemaType.type] = prepareSchemaForOutput(sourceSchemaType);
+        defs[sourceSchemaType.type] = prepareSchemaForOutput(sourceSchemaType, sourceTypes);
     });
 
 const rootType = sourceTypes.find(sourceSchemaType => sourceSchemaType.type === rootTypeName);
 if (!rootType) {
     throw new Error(`Root type ${rootTypeName} not found in source schema.`);
 }
-const rootTypeSchema = prepareSchemaForOutput(rootType);
+const rootTypeSchema = prepareSchemaForOutput(rootType, sourceTypes);
 
 const output = {
     "$id": "https://opentelemetry.io/otelconfig/opentelemetry_configuration.json",
@@ -48,14 +48,14 @@ fs.writeFileSync(schemaPath, JSON.stringify(output, null, 2));
 
 // Helper functions
 
-function prepareSchemaForOutput(sourceSchemaType) {
+function prepareSchemaForOutput(sourceSchemaType, sourceTypes) {
     const schema = JSON.parse(JSON.stringify(sourceSchemaType.schema));
 
     delete schema['$defs'];
 
     stripMetadata(schema);
     replaceCrossFileRefs(schema);
-    enrichDescriptions(sourceSchemaType, schema);
+    enrichDescriptions(sourceSchemaType, schema, sourceTypes);
 
     return schema;
 }
@@ -94,17 +94,28 @@ function replaceCrossFileRefs(schema) {
     });
 }
 
-function enrichDescriptions(sourceSchemaType, schema) {
+function enrichDescriptions(sourceSchemaType, schema, sourceTypes) {
     const properties = schema.properties;
     if (!properties) {
         return;
     }
     Object.entries(properties).forEach(([propertyKey, propertySchema]) => {
         const sourceProperty = sourceSchemaType.properties.find(property => property.property === propertyKey);
         let description = propertySchema['description'];
-        if (!description.endsWith('\n')) {
-            description += '\n';
+
+        // Add enum value descriptions if property is an enum type
+        const enumSourceType = sourceProperty.types.map(type => sourceTypes.find(sourceType => sourceType.type === type)).find(sourceType => sourceType && sourceType.isEnumType());
+        if (enumSourceType) {
+            description = maybeAddLineBreak(description);
+            description += 'Values include:\n';
+            enumSourceType.sortedEnumValues().forEach(enumValue => {
+                const enumDescription = enumSourceType.schema['enumDescriptions'][enumValue];
+                description += `* ${enumValue}: ${enumDescription}\n`;
+            });
         }
+
+        // Add default and null behavior
+        description = maybeAddLineBreak(description)
         description += sourceProperty.formatDefaultAndNullBehavior();
         if (!description.endsWith('\n')) {
             description += '\n';
@@ -113,6 +124,13 @@ function enrichDescriptions(sourceSchemaType, schema) {
     });
 }
 
+function maybeAddLineBreak(str) {
+    if (!str.endsWith('\n')) {
+        return str + '\n';
+    }
+    return str;
+}
+
 // Validation functions
 
 function allPropertiesShouldHaveDescriptions(sourceSchemaType, messages) {