Add model metadata output (#3443)

* Add model metadata output

* Document emitted model metadata

* Add model metadata schema output

* Lazy load model metadata helpers

Author: koxudaxi

docs/cli-reference/base-options.md

@@ -4,6 +4,7 @@
 
 | Option | Description |
 |--------|-------------|
+| [`--emit-model-metadata`](#emit-model-metadata) | Write a separate JSON map from source schema references to t... |
 | [`--encoding`](#encoding) | Specify character encoding for input and output files. |
 | [`--external-ref-mapping`](#external-ref-mapping) | Map external `$ref` files to Python packages. |
 | [`--input`](#input) | Specify the input schema file path. |
@@ -18,6 +19,127 @@
 
 ---
 
+## `--emit-model-metadata` {#emit-model-metadata}
+
+Write a separate JSON map from source schema references to the final generated models, modules, fields, and type hints.
+
+!!! tip "Usage"
+
+    ```bash
+    datamodel-codegen --input schema.json --emit-model-metadata model-map.json --module-split-mode single --disable-timestamp # (1)!
+    ```
+
+    1. :material-arrow-left: `--emit-model-metadata` - the option documented here
+
+??? example "Examples"
+
+    **Input Schema:**
+
+    ```json
+    {
+      "$schema": "https://json-schema.org/draft/2020-12/schema",
+      "title": "Root title",
+      "type": "object",
+      "properties": {
+        "method": {
+          "const": "thread/started"
+        },
+        "payload": {
+          "$ref": "#/$defs/MetadataPayload"
+        }
+      },
+      "required": ["method", "payload"],
+      "$defs": {
+        "MetadataPayload": {
+          "title": "Payload title",
+          "type": "object",
+          "properties": {
+            "id": {
+              "type": "integer"
+            }
+          },
+          "required": ["id"]
+        }
+      }
+    }
+    ```
+
+    **Output:**
+
+    ```python
+    # generated by datamodel-codegen:
+    #   filename:  model_metadata.json
+
+    from __future__ import annotations
+
+    from typing import Literal
+
+    from pydantic import BaseModel
+
+    from . import metadata_payload
+
+
+    class RootTitle(BaseModel):
+        method: Literal['thread/started']
+        payload: metadata_payload.MetadataPayload
+    ```
+
+    **Generated metadata (`model-map.json`):**
+
+    ```json
+    {
+      "version": 1,
+      "models": [
+        {
+          "class_name": "RootTitle",
+          "name": "RootTitle",
+          "module": "root_title",
+          "source_ref": "model_metadata.json#",
+          "source_path": [],
+          "title": "Root title",
+          "fields": [
+            {
+              "name": "method",
+              "alias": "method",
+              "original_name": "method",
+              "type": "Literal['thread/started']",
+              "required": true
+            },
+            {
+              "name": "payload",
+              "alias": "payload",
+              "original_name": "payload",
+              "type": "metadata_payload.MetadataPayload",
+              "required": true
+            }
+          ]
+        },
+        {
+          "class_name": "MetadataPayload",
+          "name": "MetadataPayload",
+          "module": "metadata_payload",
+          "source_ref": "model_metadata.json#/$defs/MetadataPayload",
+          "source_path": [
+            "$defs",
+            "MetadataPayload"
+          ],
+          "title": "Payload title",
+          "fields": [
+            {
+              "name": "id",
+              "alias": "id",
+              "original_name": "id",
+              "type": "int",
+              "required": true
+            }
+          ]
+        }
+      ]
+    }
+    ```
+
+---
+
 ## `--encoding` {#encoding}
 
 Specify character encoding for input and output files.

docs/cli-reference/index.md

@@ -8,7 +8,7 @@ This documentation is auto-generated from test cases.
 
 | Category | Options | Description |
 |----------|---------|-------------|
-| 📁 [Base Options](base-options.md) | 11 | Input/output configuration |
+| 📁 [Base Options](base-options.md) | 12 | Input/output configuration |
 | 🔧 [Typing Customization](typing-customization.md) | 30 | Type annotation and import behavior |
 | 🏷️ [Field Customization](field-customization.md) | 27 | Field naming and docstring behavior |
 | 🏗️ [Model Customization](model-customization.md) | 41 | Model generation behavior |
@@ -74,6 +74,7 @@ This documentation is auto-generated from test cases.
 
 ### E {#e}
 
+- [`--emit-model-metadata`](base-options.md#emit-model-metadata)
 - [`--empty-enum-field-name`](field-customization.md#empty-enum-field-name)
 - [`--enable-command-header`](template-customization.md#enable-command-header)
 - [`--enable-faux-immutability`](model-customization.md#enable-faux-immutability)

docs/cli-reference/manual/output-format-json-schema.md

@@ -1,6 +1,6 @@
 ## `--output-format-json-schema` {#output-format-json-schema}
 
-Output JSON Schema for a structured command output format and exit.
+Output JSON Schema for a JSON output format and exit.
 
 Use this when an LLM agent, tool call definition, or validation layer needs the
 contract before consuming JSON output. The schema is emitted separately from the
@@ -11,6 +11,7 @@ Currently supported schema targets:
 
 - `generate-prompt`: schema for `--generate-prompt --output-format json`
 - `generation`: schema for normal generation with `--output-format json`
+- `model-metadata`: schema for files emitted by `--emit-model-metadata`
 - `structured-output`: tagged union schema for all structured command outputs,
   discriminated by `kind`
 
@@ -19,13 +20,15 @@ Currently supported schema targets:
     ```bash
     datamodel-codegen --output-format-json-schema generate-prompt # (1)!
     datamodel-codegen --output-format-json-schema generation # (2)!
-    datamodel-codegen --output-format-json-schema structured-output # (3)!
-    datamodel-codegen --generate-prompt --output-format json # (4)!
-    datamodel-codegen --input schema.json --output-format json # (5)!
+    datamodel-codegen --output-format-json-schema model-metadata # (3)!
+    datamodel-codegen --output-format-json-schema structured-output # (4)!
+    datamodel-codegen --generate-prompt --output-format json # (5)!
+    datamodel-codegen --input schema.json --emit-model-metadata model-map.json # (6)!
     ```
 
     1. :material-arrow-left: Emit the JSON Schema for structured prompt output
     2. :material-arrow-left: Emit the JSON Schema for generated-file output
-    3. :material-arrow-left: Emit the JSON Schema for all structured command outputs
-    4. :material-arrow-left: Emit prompt payloads that match the prompt schema
-    5. :material-arrow-left: Emit generation payloads that match the generation schema
+    3. :material-arrow-left: Emit the JSON Schema for generated model metadata
+    4. :material-arrow-left: Emit the JSON Schema for all structured command outputs
+    5. :material-arrow-left: Emit prompt payloads that match the prompt schema
+    6. :material-arrow-left: Emit metadata payloads that match the model metadata schema

docs/cli-reference/manual/output-format.md

@@ -24,11 +24,12 @@ is the generated module path.
 
 Use `--output-format json` with `--generate-prompt` to emit structured option
 metadata instead of Markdown. Use `--output-format-json-schema` when an LLM
-agent or tool needs the schema for a structured output payload.
+agent or tool needs the schema for a JSON payload.
 
 Schema targets are intentionally scoped. `generate-prompt` emits the
 `PromptPayload` schema for `--generate-prompt --output-format json`.
 `generation` emits only the `GenerationPayload` schema for generated-file JSON.
+`model-metadata` emits the schema for files written by `--emit-model-metadata`.
 `structured-output` emits the broader `StructuredOutputPayload` schema, a union
 covering `GenerationPayload`, `PromptPayload`, `CommandOutputPayload`, and
 `CheckOutputPayload`. Structured payloads use `kind` as the discriminator.
@@ -41,15 +42,17 @@ covering `GenerationPayload`, `PromptPayload`, `CommandOutputPayload`, and
     datamodel-codegen --generate-prompt --output-format json # (3)!
     datamodel-codegen --output-format-json-schema generation # (4)!
     datamodel-codegen --output-format-json-schema generate-prompt # (5)!
-    datamodel-codegen --output-format-json-schema structured-output # (6)!
+    datamodel-codegen --output-format-json-schema model-metadata # (6)!
+    datamodel-codegen --output-format-json-schema structured-output # (7)!
     ```
 
     1. :material-arrow-left: Emit the default generated Python text
     2. :material-arrow-left: Emit structured JSON containing generated files
     3. :material-arrow-left: Emit structured JSON with current options and argparse metadata
     4. :material-arrow-left: Emit JSON Schema for generated-file JSON output
     5. :material-arrow-left: Emit JSON Schema for structured prompt JSON
-    6. :material-arrow-left: Emit JSON Schema for any structured command JSON output
+    6. :material-arrow-left: Emit JSON Schema for generated model metadata JSON
+    7. :material-arrow-left: Emit JSON Schema for any structured command JSON output
 
 ??? example "Generation JSON output"
 

docs/cli-reference/quick-reference.md

@@ -16,6 +16,7 @@ datamodel-codegen [OPTIONS]
 
 | Option | Description |
 |--------|-------------|
+| [`--emit-model-metadata`](base-options.md#emit-model-metadata) | Write a separate JSON map from source schema references to the final generated m... |
 | [`--encoding`](base-options.md#encoding) | Specify character encoding for input and output files. |
 | [`--external-ref-mapping`](base-options.md#external-ref-mapping) | Map external `$ref` files to Python packages. |
 | [`--input`](base-options.md#input) | Specify the input schema file path. |
@@ -221,7 +222,7 @@ datamodel-codegen [OPTIONS]
 | [`--list-experimental`](utility-options.md#list-experimental) | List registered experimental features |
 | [`--no-color`](utility-options.md#no-color) | Disable colorized output |
 | [`--output-format`](utility-options.md#output-format) | Choose the command output format |
-| [`--output-format-json-schema`](utility-options.md#output-format-json-schema) | Output JSON Schema for structured command output |
+| [`--output-format-json-schema`](utility-options.md#output-format-json-schema) | Output JSON Schema for JSON output payloads |
 | [`--profile`](utility-options.md#profile) | Use a named profile from pyproject.toml |
 | [`--version`](utility-options.md#version) | Show program version and exit |
 
@@ -268,6 +269,7 @@ All options sorted alphabetically:
 - [`--disable-timestamp`](template-customization.md#disable-timestamp) - Disable timestamp in generated file header for reproducible ...
 - [`--disable-warnings`](general-options.md#disable-warnings) - Suppress warning messages during code generation.
 - [`--duplicate-name-suffix`](model-customization.md#duplicate-name-suffix) - Customize suffix for duplicate model names.
+- [`--emit-model-metadata`](base-options.md#emit-model-metadata) - Write a separate JSON map from source schema references to t...
 - [`--empty-enum-field-name`](field-customization.md#empty-enum-field-name) - Name for empty string enum field values.
 - [`--enable-command-header`](template-customization.md#enable-command-header) - Include command-line options in file header for reproducibil...
 - [`--enable-faux-immutability`](model-customization.md#enable-faux-immutability) - Enable faux immutability in Pydantic models (frozen=True).
@@ -329,7 +331,7 @@ All options sorted alphabetically:
 - [`--output-date-class`](typing-customization.md#output-date-class) - Specify date class type for date schema fields.
 - [`--output-datetime-class`](typing-customization.md#output-datetime-class) - Specify datetime class type for date-time schema fields.
 - [`--output-format`](utility-options.md#output-format) - Choose the command output format
-- [`--output-format-json-schema`](utility-options.md#output-format-json-schema) - Output JSON Schema for structured command output
+- [`--output-format-json-schema`](utility-options.md#output-format-json-schema) - Output JSON Schema for JSON output payloads
 - [`--output-model-type`](model-customization.md#output-model-type) - Select the output model type (Pydantic v2, Pydantic v2 datac...
 - [`--parent-scoped-naming`](model-customization.md#parent-scoped-naming) - Namespace models by their parent scope to avoid naming confl...
 - [`--preset`](base-options.md#preset) - Apply an immutable built-in option preset.

docs/cli-reference/utility-options.md

@@ -11,7 +11,7 @@
 | [`--list-experimental`](#list-experimental) | List registered experimental features |
 | [`--no-color`](#no-color) | Disable colorized output |
 | [`--output-format`](#output-format) | Choose the command output format |
-| [`--output-format-json-schema`](#output-format-json-schema) | Output JSON Schema for structured command output |
+| [`--output-format-json-schema`](#output-format-json-schema) | Output JSON Schema for JSON output payloads |
 | [`--profile`](#profile) | Use a named profile from pyproject.toml |
 | [`--version`](#version) | Show program version and exit |
 
@@ -227,11 +227,12 @@ is the generated module path.
 
 Use `--output-format json` with `--generate-prompt` to emit structured option
 metadata instead of Markdown. Use `--output-format-json-schema` when an LLM
-agent or tool needs the schema for a structured output payload.
+agent or tool needs the schema for a JSON payload.
 
 Schema targets are intentionally scoped. `generate-prompt` emits the
 `PromptPayload` schema for `--generate-prompt --output-format json`.
 `generation` emits only the `GenerationPayload` schema for generated-file JSON.
+`model-metadata` emits the schema for files written by `--emit-model-metadata`.
 `structured-output` emits the broader `StructuredOutputPayload` schema, a union
 covering `GenerationPayload`, `PromptPayload`, `CommandOutputPayload`, and
 `CheckOutputPayload`. Structured payloads use `kind` as the discriminator.
@@ -244,15 +245,17 @@ covering `GenerationPayload`, `PromptPayload`, `CommandOutputPayload`, and
     datamodel-codegen --generate-prompt --output-format json # (3)!
     datamodel-codegen --output-format-json-schema generation # (4)!
     datamodel-codegen --output-format-json-schema generate-prompt # (5)!
-    datamodel-codegen --output-format-json-schema structured-output # (6)!
+    datamodel-codegen --output-format-json-schema model-metadata # (6)!
+    datamodel-codegen --output-format-json-schema structured-output # (7)!
     ```
 
     1. :material-arrow-left: Emit the default generated Python text
     2. :material-arrow-left: Emit structured JSON containing generated files
     3. :material-arrow-left: Emit structured JSON with current options and argparse metadata
     4. :material-arrow-left: Emit JSON Schema for generated-file JSON output
     5. :material-arrow-left: Emit JSON Schema for structured prompt JSON
-    6. :material-arrow-left: Emit JSON Schema for any structured command JSON output
+    6. :material-arrow-left: Emit JSON Schema for generated model metadata JSON
+    7. :material-arrow-left: Emit JSON Schema for any structured command JSON output
 
 ??? example "Generation JSON output"
 
@@ -285,7 +288,7 @@ covering `GenerationPayload`, `PromptPayload`, `CommandOutputPayload`, and
 
 ## `--output-format-json-schema` {#output-format-json-schema}
 
-Output JSON Schema for a structured command output format and exit.
+Output JSON Schema for a JSON output format and exit.
 
 Use this when an LLM agent, tool call definition, or validation layer needs the
 contract before consuming JSON output. The schema is emitted separately from the
@@ -296,6 +299,7 @@ Currently supported schema targets:
 
 - `generate-prompt`: schema for `--generate-prompt --output-format json`
 - `generation`: schema for normal generation with `--output-format json`
+- `model-metadata`: schema for files emitted by `--emit-model-metadata`
 - `structured-output`: tagged union schema for all structured command outputs,
   discriminated by `kind`
 
@@ -304,16 +308,18 @@ Currently supported schema targets:
     ```bash
     datamodel-codegen --output-format-json-schema generate-prompt # (1)!
     datamodel-codegen --output-format-json-schema generation # (2)!
-    datamodel-codegen --output-format-json-schema structured-output # (3)!
-    datamodel-codegen --generate-prompt --output-format json # (4)!
-    datamodel-codegen --input schema.json --output-format json # (5)!
+    datamodel-codegen --output-format-json-schema model-metadata # (3)!
+    datamodel-codegen --output-format-json-schema structured-output # (4)!
+    datamodel-codegen --generate-prompt --output-format json # (5)!
+    datamodel-codegen --input schema.json --emit-model-metadata model-map.json # (6)!
     ```
 
     1. :material-arrow-left: Emit the JSON Schema for structured prompt output
     2. :material-arrow-left: Emit the JSON Schema for generated-file output
-    3. :material-arrow-left: Emit the JSON Schema for all structured command outputs
-    4. :material-arrow-left: Emit prompt payloads that match the prompt schema
-    5. :material-arrow-left: Emit generation payloads that match the generation schema
+    3. :material-arrow-left: Emit the JSON Schema for generated model metadata
+    4. :material-arrow-left: Emit the JSON Schema for all structured command outputs
+    5. :material-arrow-left: Emit prompt payloads that match the prompt schema
+    6. :material-arrow-left: Emit metadata payloads that match the model metadata schema
 
 ---