datamodel-code-generator

The datamodel-code-generator CLI is organized into several functional categories. Use these categories to find specific options for your generation workflow:

• Base Options: Input and output configuration.
• Typing Customization: Controls type annotation and import behavior.
• Field Customization: Controls field naming and docstring behavior.
• Model Customization: Controls how models are generated.
• Template Customization: Controls output formatting and custom rendering.
• OpenAPI-only Options: Features specific to OpenAPI schemas.
• GraphQL-only Options: Features specific to GraphQL schemas.
• General Options: Utilities and meta options.
• Utility Options: Help, version, and debug options.

If you are working on a specific workflow area, you can use the following focused topic guides to find relevant options:

• Model Customization: Covers Model Naming, Model Reuse, Model Shape, and Root Models.
• Template Customization: Covers Custom Templates, Generated Output, Imports, and Output Formatting.
• Typing Customization: Covers Imports, Collection Types, Type Alias, Type Mapping, and Type Syntax.
• OpenAPI: Covers OpenAPI Naming, OpenAPI Paths, OpenAPI Scopes, and Read Only/Write Only fields.

The performance benchmarks for datamodel-code-generator are categorized by input type (JSON Schema or OpenAPI) and case size (Small or Large). These scenarios help evaluate different aspects of the generation process:

• Small / JSON Schema: Focuses on CLI startup, parsing, and formatter overhead for JSON Schema to Pydantic v2 model generation.
• Small / OpenAPI: Focuses on CLI startup, parsing, and formatter overhead for OpenAPI component resolution and Pydantic v2 model generation.
• Large / JSON Schema: Emphasizes parser and model graph throughput for JSON Schema to Pydantic v2 model generation.
• Large / OpenAPI: Emphasizes parser and model graph throughput for OpenAPI component resolution and Pydantic v2 model generation.

The datamodel-code-generator project uses several external conformance and end-to-end (e2e) test suites to ensure compatibility with upstream specifications. These suites exercise the generator against pinned corpora to verify that generated models (e.g., Pydantic v2) correctly represent the input formats.

Note: These suites are compatibility and coverage signals; they do not claim complete specification compliance.

Scope

The parser extracts schemas from several AsyncAPI locations to generate models, including:

• components.schemas (Reusable models)
• components.messages[*].payload and headers (Message models)
• channels[*].publish.message, subscribe.message, and messages[*] (Channel models)
• channels[*].parameters[*].schema (Parameter models)
• operations[*].messages and operations[*].reply.messages (Operation models)
• Binding schemas for fields like Kafka key, HTTP headers, WebSockets query, and Kafka groupId/clientId.

Limitations

• Does not validate complete AsyncAPI documents.
• Does not apply protocol binding runtime semantics.
• Does not generate producer/consumer code or clients/servers.
• Does not enforce runtime message validation.
• Does not merge multiple traits that define the same headers property.

You can generate Pydantic models from a .proto file using the datamodel-codegen CLI. Use the --input-file-type protobuf flag to specify the input format.

To generate models from a single file:

datamodel-codegen \
    --input order.proto \
    --input-file-type protobuf \
    --output-model-type pydantic_v2.BaseModel \
    --output model.py

Use the datamodel-codegen CLI to convert a JSON Schema file into Pydantic models. To generate Pydantic v2 models with annotated types, use the following command structure:

datamodel-codegen \
    --input person.json \
    --input-file-type jsonschema \
    --output-model-type pydantic_v2.BaseModel \
    --use-annotated \
    --output model.py

You can steer the generation of base classes directly within your JSON Schema using the customBasePath extension. This avoids needing to pass CLI options for every specific model.

### Single Base Class
```json
{
  "title": "User",
  "type": "object",
  "customBasePath": "myapp.models.UserBase",
  "properties": {
    "name": {"type": "string"}
  }
}

Multiple Base Classes (Mixins)

{
  "title": "User",
  "type": "object",
  "customBasePath": ["mixins.AuditMixin", "mixins.TimestampMixin"],
  "properties": {
    "name": {"type": "string"}
  }
}

Note: When using multiple base classes, the specified classes are used directly without adding BaseModel. Ensure your mixins inherit from pydantic.BaseModel if you need Pydantic model behavior.

You can pass keyword arguments to your custom formatter's constructor using the --custom-formatters-kwargs CLI flag. This flag accepts a JSON string representing the arguments.

datamodel-codegen --input schema.json --output model.py \
    --custom-formatters "mypackage.your_module" \
    --custom-formatters-kwargs '{"line_length": 100}'

You can generate models from Model Context Protocol (MCP) tool schema profiles using the experimental --input-file-type mcp-tools flag. This converts MCP tool inputSchema and outputSchema entries into JSON Schema definitions.

Supported Input Shapes

• tools/list JSON-RPC responses containing result.tools.
• MCP server definitions with a top-level tools array.
• Single or arrays of tool definitions.
• JSON Schema documents where $defs or definitions contain tool definitions.

Naming Convention

Generated definitions are named using the pattern {tool_name}{Input|Output}. Example: A tool named Search will generate SearchInput and SearchOutput models.