[cmd/mdatagen] Add extended type aliases for configuration schema (#15514)

jkoronaAtCisco · web-flow · commit 0dff74643e8f · 2026-07-22T18:03:32.000Z
#### Description Adds first-class extended type aliases to cmd/mdatagen, so `metadata.yaml` authors can write a Go-idiomatic type name directly as the type field of a config property, instead of combining `type` + `format` or `type` + `x-customType` by hand.  #### Link to tracking issue Fixes #15513  #### Testing - Sample components extended with examples - Changes covered with unit tests  #### Documentation Extended README of mdatagen with info about usage of extended types and how to add new.  #### Authorship - [x] I, a human, wrote this pull request description myself.
diff --git a/.chloggen/mdatagen_extended_types.yaml b/.chloggen/mdatagen_extended_types.yaml
@@ -0,0 +1,30 @@
+# Use this changelog template to create an entry for release notes.
+
+# One of 'breaking', 'deprecation', 'new_component', 'enhancement', 'bug_fix'
+change_type: enhancement
+
+# The name of the component, or a single word describing the area of concern, (e.g. receiver/otlp)
+component: cmd/mdatagen
+
+# A brief description of the change.  Surround your text with quotes ("") if it needs to start with a backtick (`).
+note: Add first-class extended type aliases (int64, duration, opaque_string, id, opaque_map, etc.) to config schemas in metadata.yaml
+
+# One or more tracking issues or pull requests related to the change
+issues: [15513]
+
+# (Optional) One or more lines of additional information to render under the primary note.
+# These lines will be padded with 2 spaces and then inserted directly into the document.
+# Use pipe (|) for multiline entries.
+subtext: |
+  Authors can now write `type: int64`, `type: duration`, `type: opaque_string`, `type: id`, or
+  `type: opaque_map` directly as a property type in the `config:` section of `metadata.yaml`.
+  Each alias expands to the correct JSON Schema representation and Go type automatically.
+  Existing uses of standard JSON Schema types, `format:`, and `x-customType:` remain supported
+  without migration.
+
+# Optional: The change log or logs in which this entry should be included.
+# e.g. '[user]' or '[user, api]'
+# Include 'user' if the change is relevant to end users.
+# Include 'api' if there is a change to a library API.
+# Default: '[user]'
+change_logs: [user, api]
diff --git a/cmd/mdatagen/README.md b/cmd/mdatagen/README.md
@@ -97,6 +97,50 @@ The `config` section is based on [JSON Schema standard](https://json-schema.org/
 - **References**: Internal (`$ref: definition_name`), external (`$ref: package.path.type`), or relative (`$ref: ./internal/config.type`)
 - **Reusable definitions**: Define common schemas in `$defs` and reference them with `$ref`
 - **Schema composition**: Use `allOf` for complex configurations
+- **Extended type aliases**: first-class aliases that expand to the correct JSON Schema shape and Go type automatically (see table below)
+
+#### Extended type aliases
+
+Instead of combining `type`+`format` or `type`+`x-customType` by hand, you can use an alias directly as the `type` value:
+
+| Alias | Go type | JSON Schema representation        |
+|---|---|-----------------------------------|
+| `rune` | `rune` | `integer`                         |
+| `byte` | `byte` | `integer`                         |
+| `uint` | `uint` | `integer`                         |
+| `int8` | `int8` | `integer`                         |
+| `uint8` | `uint8` | `integer`                         |
+| `int16` | `int16` | `integer`                         |
+| `uint16` | `uint16` | `integer`                         |
+| `int32` | `int32` | `integer`                         |
+| `uint32` | `uint32` | `integer`                         |
+| `int64` | `int64` | `integer`                         |
+| `uint64` | `uint64` | `integer`                         |
+| `float32` | `float32` | `number`                          |
+| `float64` | `float64` | `number`                          |
+| `duration` | `time.Duration` | `string` with Go duration pattern |
+| `time` | `time.Time` | `string` with `format: date-time` |
+| `opaque_string` | `configopaque.String` | `string`                          |
+| `opaque_map` | `configopaque.MapList` | `object` of name/value pairs      |
+| `id` | `component.ID` | `string`                          |
+
+Example:
+
+```yaml
+config:
+  type: object
+  properties:
+    max_results:
+      type: int64
+      default: 100
+    timeout:
+      type: duration
+      default: 30s
+    api_token:
+      type: opaque_string
+```
+
+Aliases are additive: existing uses of standard JSON Schema types, `format`, and `x-customType` remain supported without migration.
 
 ### Metrics Builder Configuration
 
diff --git a/cmd/mdatagen/go.mod b/cmd/mdatagen/go.mod
@@ -9,6 +9,7 @@ require (
 	github.com/stretchr/testify v1.11.1
 	go.opentelemetry.io/collector/component v1.63.0
 	go.opentelemetry.io/collector/component/componenttest v0.157.0
+	go.opentelemetry.io/collector/config/configopaque v1.63.0
 	go.opentelemetry.io/collector/config/configoptional v1.63.0
 	go.opentelemetry.io/collector/confmap v1.63.0
 	go.opentelemetry.io/collector/confmap/provider/fileprovider v1.63.0
diff --git a/cmd/mdatagen/internal/loader_test.go b/cmd/mdatagen/internal/loader_test.go
@@ -97,10 +97,26 @@ func TestLoadMetadata(t *testing.T) {
 							},
 							"timeout": {
 								Description: "Timeout for scraping metrics.",
-								Type:        "string",
-								Format:      "duration",
+								Type:        "duration",
 								Default:     "10s",
 							},
+							"max_results": {
+								Description: "Maximum number of results to return per scrape.",
+								Type:        "int64",
+								Default:     100,
+							},
+							"api_token": {
+								Description: "API token used to authenticate with the endpoint.",
+								Type:        "opaque_string",
+							},
+							"component_id": {
+								Description: "Component ID used to identify this receiver instance.",
+								Type:        "component_id",
+							},
+							"headers": {
+								Description: "Extra HTTP headers to attach to each request.",
+								Type:        "opaque_map",
+							},
 						},
 						Required: []string{"endpoint"},
 					},
diff --git a/cmd/mdatagen/internal/samplereceiver/README.md b/cmd/mdatagen/internal/samplereceiver/README.md
@@ -34,7 +34,11 @@ This is where warnings are described.
 ## Configuration
 | Setting | Type | Default | Required | Description |
 | ------- | ---- | ------- | -------- | ----------- |
+| `api_token` | string |  | no | API token used to authenticate with the endpoint. |
+| `component_id` | string |  | no | Component ID used to identify this receiver instance. |
 | `endpoint` | string | localhost:12345 | **yes** | The endpoint to scrape metrics from. |
+| `headers` | map[string]string |  | no | Extra HTTP headers to attach to each request. |
+| `max_results` | int | 100 | no | Maximum number of results to return per scrape. |
 | `metrics` | object (see [metrics](#metrics)) |  | no | MetricsConfig provides config for sample metrics. |
 | `resource_attributes` | object (see [resource_attributes](#resource_attributes)) |  | no | ResourceAttributesConfig provides config for sample resource attributes. |
 | `sample_pkg` | object (see [sample_pkg](#sample_pkg)) |  | no |  |
diff --git a/cmd/mdatagen/internal/samplereceiver/config.schema.json b/cmd/mdatagen/internal/samplereceiver/config.schema.json
@@ -1,11 +1,31 @@
 {
   "type": "object",
   "properties": {
+    "api_token": {
+      "type": "string",
+      "description": "API token used to authenticate with the endpoint."
+    },
+    "component_id": {
+      "type": "string",
+      "description": "Component ID used to identify this receiver instance."
+    },
     "endpoint": {
       "type": "string",
       "description": "The endpoint to scrape metrics from.",
       "default": "localhost:12345"
     },
+    "headers": {
+      "type": "object",
+      "description": "Extra HTTP headers to attach to each request.",
+      "additionalProperties": {
+        "type": "string"
+      }
+    },
+    "max_results": {
+      "type": "integer",
+      "description": "Maximum number of results to return per scrape.",
+      "default": 100
+    },
     "sample_pkg": {
       "type": "object",
       "properties": {
diff --git a/cmd/mdatagen/internal/samplereceiver/generated_config.go b/cmd/mdatagen/internal/samplereceiver/generated_config.go
diff --git a/cmd/mdatagen/internal/samplereceiver/metadata.yaml b/cmd/mdatagen/internal/samplereceiver/metadata.yaml
@@ -50,9 +50,21 @@ config:
       default: "localhost:12345"
     timeout:
       description: Timeout for scraping metrics.
-      type: string
-      format: duration
+      type: duration
       default: 10s
+    max_results:
+      description: Maximum number of results to return per scrape.
+      type: int64
+      default: 100
+    api_token:
+      description: API token used to authenticate with the endpoint.
+      type: opaque_string
+    component_id:
+      description: Component ID used to identify this receiver instance.
+      type: component_id
+    headers:
+      description: Extra HTTP headers to attach to each request.
+      type: opaque_map
     sample_pkg:
       $ref: ../samplepkg.sample_config
   required: [endpoint]
diff --git a/cmd/mdatagen/internal/samplescraper/metadata.yaml b/cmd/mdatagen/internal/samplescraper/metadata.yaml
@@ -40,9 +40,8 @@ config:
       go_struct:
         anonymous: true
     component:
-      type: string
+      type: component_id
       description: Identifies the scraper, used for telemetry and logging.
-      x-customType: go.opentelemetry.io/collector/component.ID
       go_struct:
         field_name: ComponentID
     job_name:
@@ -62,8 +61,7 @@ config:
         type: object
         properties:
           interval:
-            type: string
-            format: duration
+            type: duration
             x-optional: true
             default: 10s
           labels:
diff --git a/config/configmiddleware/metadata.yaml b/config/configmiddleware/metadata.yaml
@@ -13,5 +13,4 @@ exported_configs:
     properties:
       id:
         description: Specifies the name of the extension to use.
-        type: string
-        x-customType: go.opentelemetry.io/collector/component.ID
+        type: component_id
diff --git a/internal/schemagen/extended_types.go b/internal/schemagen/extended_types.go
@@ -0,0 +1,104 @@
+// Copyright The OpenTelemetry Authors
+// SPDX-License-Identifier: Apache-2.0
+
+package schemagen // import "go.opentelemetry.io/collector/internal/schemagen"
+
+import "fmt"
+
+// goDurationPattern matches Go duration strings (e.g., "30s", "1h30m", "500ms")
+const goDurationPattern = `^([0-9]+(\.[0-9]+)?(ns|us|µs|ms|s|m|h))+$`
+
+// extendedTypes is the centralized registry of first-class type aliases that can be used as the "type" field
+// in a metadata.yaml config schema. Each entry maps an alias name to the standard JSON Schema fields it expands to,
+// together with any Go-specific annotations (GoType) needed for code generation.
+//
+// To add a new alias, add a single entry here. No other switch or case needs editing.
+var extendedTypes = map[string]ConfigMetadata{
+	// Integer aliases
+	"rune":   {Type: "integer", GoType: "rune"},
+	"byte":   {Type: "integer", GoType: "byte"},
+	"uint":   {Type: "integer", GoType: "uint"},
+	"int8":   {Type: "integer", GoType: "int8"},
+	"uint8":  {Type: "integer", GoType: "uint8"},
+	"int16":  {Type: "integer", GoType: "int16"},
+	"uint16": {Type: "integer", GoType: "uint16"},
+	"int32":  {Type: "integer", GoType: "int32"},
+	"uint32": {Type: "integer", GoType: "uint32"},
+	"int64":  {Type: "integer", GoType: "int64"},
+	"uint64": {Type: "integer", GoType: "uint64"},
+
+	// Number aliases
+	"float32": {Type: "number", GoType: "float32"},
+	"float64": {Type: "number", GoType: "float64"},
+
+	// String-backed aliases using full import-path GoType convention
+	"opaque_string": {Type: "string", GoType: "go.opentelemetry.io/collector/config/configopaque.String"},
+	"component_id":  {Type: "string", GoType: "go.opentelemetry.io/collector/component.ID"},
+
+	// duration and time
+	"duration": {Type: "string", GoType: "time.Duration", Pattern: goDurationPattern},
+	"time":     {Type: "string", GoType: "time.Time", Format: "date-time"},
+
+	// opaque_map: Go uses configopaque.MapList; JSON gets a map[string]string
+	"opaque_map": {
+		Type:   "object",
+		GoType: "go.opentelemetry.io/collector/config/configopaque.MapList",
+		AdditionalProperties: &ConfigMetadata{
+			Type: "string",
+		},
+	},
+}
+
+var basicTypes = map[string]bool{
+	"":        true, // empty is allowed (treated as "any" by the generator)
+	"string":  true,
+	"integer": true,
+	"number":  true,
+	"boolean": true,
+	"object":  true,
+	"array":   true,
+	"null":    true,
+}
+
+func isBasicType(typ string) bool {
+	return basicTypes[typ]
+}
+
+// expandExtendedType rewrites md.Type from an extended alias to the equivalent standard JSON Schema fields.
+// It is a no-op when md.Type is already a standard JSON Schema type. An explicit x-customType on the node
+// is never overwritten.
+//
+// Returns an actionable error for unknown aliases.
+func expandExtendedType(md *ConfigMetadata) error {
+	if isBasicType(md.Type) {
+		return nil
+	}
+	ext, ok := extendedTypes[md.Type]
+	if !ok {
+		return fmt.Errorf("unknown config type %q: not a JSON Schema type and not a known extended type alias (e.g. int64, duration, opaque_string, id, opaque_map)", md.Type)
+	}
+
+	md.Type = ext.Type
+
+	if md.GoType == "" {
+		md.GoType = ext.GoType
+	}
+
+	if md.Format == "" {
+		md.Format = ext.Format
+	}
+
+	if md.Pattern == "" {
+		md.Pattern = ext.Pattern
+	}
+
+	if md.Items == nil {
+		md.Items = ext.Items
+	}
+
+	if md.AdditionalProperties == nil {
+		md.AdditionalProperties = ext.AdditionalProperties
+	}
+
+	return nil
+}
diff --git a/internal/schemagen/extended_types_test.go b/internal/schemagen/extended_types_test.go
diff --git a/internal/schemagen/resolver.go b/internal/schemagen/resolver.go
diff --git a/internal/schemagen/resolver_test.go b/internal/schemagen/resolver_test.go
diff --git a/scraper/scraperhelper/internal/controller/metadata.yaml b/scraper/scraperhelper/internal/controller/metadata.yaml
