📁 Base Options¶

📋 Options¶

Option	Description
`--emit-model-metadata`	Write a separate JSON map from source schema references to t...
`--encoding`	Specify character encoding for input and output files.
`--external-ref-mapping`	Map external `$ref` files to Python packages.
`--http-backend`	Select the HTTP client backend for remote schemas.
`--input`	Specify the input schema file path.
`--input-file-type`	Specify the input file type for code generation.
`--input-model`	Import a Python type or dict schema from a module or Python ...
`--input-model-ref-strategy`	Strategy for referenced types when using --input-model.
`--output`	Specify the destination path for generated Python code.
`--preset`	Apply an immutable built-in option preset.
`--schema-version`	Schema version to use for parsing.
`--schema-version-mode`	Schema version validation mode.
`--url`	Fetch a schema from a URL with custom HTTP headers.

🍳 Recipes¶

Generate a local schema file¶

Pin the input type and destination when the source extension is ambiguous or generated output needs a stable path.

Options: --input, --input-file-type, --output

Fetch a protected remote schema¶

Use URL input together with HTTP request controls for schemas served behind headers or slower endpoints.

Options: --url, --http-headers, --http-timeout

`--emit-model-metadata`¶

Write a separate JSON map from source schema references to the final generated models, modules, fields, and type hints.

Usage

datamodel-codegen --input schema.json --emit-model-metadata model-map.json --module-split-mode single --disable-timestamp # (1)!

--emit-model-metadata - the option documented here

Examples

Input Schema:

{
  "$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:

# 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):

{
  "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`¶

Specify character encoding for input and output files.

The --encoding flag sets the character encoding used when reading the schema file and writing the generated Python code. This is useful for schemas containing non-ASCII characters (e.g., Japanese, Chinese). Default is UTF-8, which is the standard encoding for JSON and most modern text files.

Usage

datamodel-codegen --input schema.json --encoding utf-8 # (1)!

--encoding - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "日本語Model",
  "description": "モデルの説明文",
  "type": "object",
  "properties": {
    "名前": {
      "type": "string",
      "description": "ユーザー名"
    },
    "年齢": {
      "type": "integer"
    }
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  encoding_test.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel, Field


class 日本語Model(BaseModel):
    名前: str | None = Field(None, description='ユーザー名')
    年齢: int | None = None

`--external-ref-mapping`¶

Map external $ref files to Python packages.

Use --external-ref-mapping FILE_PATH=PYTHON_PACKAGE to import referenced models from an existing package, instead of generating duplicate classes from external schema files.

Usage

datamodel-codegen --input schema.json --input-file-type openapi --external-ref-mapping common.yaml=mypackage.shared.models # (1)!

--external-ref-mapping - the option documented here

Examples

Input Schema:

openapi: "3.0.3"
info:
  title: API
  version: "1.0.0"
paths: {}
components:
  schemas:
    UserResponse:
      type: object
      properties:
        user:
          $ref: "common.yaml#/components/schemas/User"
        request_id:
          type: string
      required:
        - user
        - request_id
    ErrorResponse:
      type: object
      properties:
        error:
          $ref: "common.yaml#/components/schemas/Error"
        timestamp:
          type: string
          format: date-time
      required:
        - error
        - timestamp

Output:

# generated by datamodel-codegen:
#   filename:  api.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from mypackage.shared.models import Error, User
from pydantic import AwareDatetime, BaseModel


class UserResponse(BaseModel):
    user: User
    request_id: str


class ErrorResponse(BaseModel):
    error: Error
    timestamp: AwareDatetime

`--http-backend`¶

Select the HTTP client backend for remote schemas.

--http-backend auto selects stable HTTPX when its client module is installed and selects experimental HTTPX2 only when that module is absent. Explicit httpx or httpx2 selections require that exact backend. Explicit selections and paired dependency errors do not fall back.

Usage

datamodel-codegen --input schema.json --http-backend auto # (1)!

--http-backend - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  http://localhost/schema.json

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None

`--input`¶

Specify the input schema file path.

The --input flag specifies the path to the schema file (JSON Schema, OpenAPI, GraphQL, etc.). Multiple input files can be specified to merge schemas. Required unless using --url to fetch schema from a URL.

Usage

datamodel-codegen --input schema.json --input pet_simple.json --output output.py # (1)!

--input - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  pet_simple.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None

`--input-file-type`¶

Specify the input file type for code generation.

The --input-file-type flag explicitly sets the input format.

Important distinction:

Use jsonschema, openapi, asyncapi, graphql, mcp-tools, xmlschema, protobuf, or avro for schema definition files
Use json, yaml, or csv for raw sample data to automatically infer a schema

For example, if you have a JSON Schema written in YAML format, use --input-file-type jsonschema, not --input-file-type yaml. The yaml type treats the file as raw data and infers a schema from it.

Usage

datamodel-codegen --input schema.json --input-file-type json # (1)!

--input-file-type - the option documented here

Examples

JSONYAML

Input Schema:

{
  "Pet": {
    "name": "dog",
    "age": 2
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  pet.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel, Field


class Pet(BaseModel):
    name: str
    age: int


class Model(BaseModel):
    Pet_1: Pet = Field(..., alias='Pet')

Input Schema:

Pet:
  name: cat
  age: 3

Output:

# generated by datamodel-codegen:
#   filename:  pet.yaml
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel, Field


class Pet(BaseModel):
    name: str
    age: int


class Model(BaseModel):
    Pet_1: Pet = Field(..., alias='Pet')

`--input-model`¶

Import a Python type or dict schema from a module or Python file.

Use the format module:Object or path/to/file.py:Object to specify the type.

Usage

datamodel-codegen --input schema.json --input-model mymodule:MyModel # (1)!

--input-model - the option documented here

Examples

Command:

datamodel-codegen \
  --input-model tests.data.python.input_model.typeddict_models:User \
  --output model.py

Input Model (tests/data/python/input_model/typeddict_models.py):

"""TypedDict models for --input-model tests."""

from typing_extensions import TypedDict


class User(TypedDict):
    """User TypedDict with basic fields."""

    name: str
    age: int

Output:

from __future__ import annotations

from pydantic import BaseModel, Field


class User(BaseModel):
    name: str = Field(..., title='Name')
    age: int = Field(..., title='Age')

`--input-model-ref-strategy`¶

Strategy for referenced types when using --input-model.

The --input-model-ref-strategy option determines whether to regenerate or import referenced types. Use regenerate-all (default) to regenerate all types, reuse-foreign to import types from different families (like enums when generating dataclasses) while regenerating same-family types, or reuse-all to import all referenced types directly.

Usage

datamodel-codegen --input schema.json --input-model-ref-strategy reuse-foreign # (1)!

--input-model-ref-strategy - the option documented here

Examples

Output:

`--output`¶

Specify the destination path for generated Python code.

The --output flag specifies where to write the generated Python code. It can be either a file path (single-file output) or a directory path (multi-file output for modular schemas). If omitted, the generated code is written to stdout.

Usage

datamodel-codegen --input schema.json --input pet_simple.json --output output.py # (1)!

--output - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  pet_simple.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None

`--preset`¶

Apply an immutable built-in option preset.

The standard-py312-20260619 preset enables the recommended modern Python output style for new projects. The preset name pins generated Python syntax and backports.

Related: --target-python-version

See also: pyproject.toml Configuration

Usage

datamodel-codegen --input schema.json --preset standard-py312-20260619 # (1)!

--preset - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Person",
  "type": "object",
  "properties": {
    "firstName": {
      "type": "string",
      "description": "The person's first name."
    },
    "lastName": {
      "type": ["string", "null"],
      "description": "The person's last name."
    },
    "age": {
      "description": "Age in years which must be equal to or greater than zero.",
      "type": "integer",
      "minimum": 0
    },
    "friends": {
      "type": "array"
    },
    "comment": {
      "type": "null"
    }
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  person.json

from __future__ import annotations

from typing import Annotated, Any

from pydantic import BaseModel, ConfigDict, Field


class Person(BaseModel):
    model_config = ConfigDict(
        populate_by_name=True,
    )
    first_name: Annotated[
        str | None, Field(alias='firstName', description="The person's first name.")
    ] = None
    last_name: Annotated[
        str | None, Field(alias='lastName', description="The person's last name.")
    ] = None
    age: Annotated[
        int | None,
        Field(
            description='Age in years which must be equal to or greater than zero.',
            ge=0,
        ),
    ] = None
    friends: list[Any] | None = None
    comment: Annotated[None, Field(None)] = None

`--schema-version`¶

Schema version to use for parsing.

The --schema-version option specifies the schema version to use instead of auto-detection. Valid values depend on input type: JsonSchema (draft-04, draft-06, draft-07, 2019-09, 2020-12) or OpenAPI (3.0, 3.1, 3.2). Default is 'auto' (detected from $schema or openapi field).

Usage

datamodel-codegen --input schema.json --schema-version draft-07 # (1)!

--schema-version - the option documented here

Examples

OpenAPIJSON Schema

Input Schema:

openapi: "3.0.0"
info:
  version: 1.0.0
  title: Swagger Petstore
  license:
    name: MIT
servers:
  - url: http://petstore.swagger.io/v1
paths:
  /pets:
    get:
      summary: List all pets
      operationId: listPets
      tags:
        - pets
      parameters:
        - name: limit
          in: query
          description: How many items to return at one time (max 100)
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: A paged array of pets
          headers:
            x-next:
              description: A link to the next page of responses
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
    post:
      summary: Create a pet
      operationId: createPets
      tags:
        - pets
      responses:
        '201':
          description: Null response
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
                x-amazon-apigateway-integration:
                  uri:
                    Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
                  passthroughBehavior: when_no_templates
                  httpMethod: POST
                  type: aws_proxy
  /pets/{petId}:
    get:
      summary: Info for a specific pet
      operationId: showPetById
      tags:
        - pets
      parameters:
        - name: petId
          in: path
          required: true
          description: The id of the pet to retrieve
          schema:
            type: string
      responses:
        '200':
          description: Expected response to a valid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Pets"
        default:
          description: unexpected error
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    x-amazon-apigateway-integration:
      uri:
        Fn::Sub: arn:aws:apigateway:${AWS::Region}:lambda:path/2015-03-31/functions/${PythonVersionFunction.Arn}/invocations
      passthroughBehavior: when_no_templates
      httpMethod: POST
      type: aws_proxy
components:
  schemas:
    Pet:
      required:
        - id
        - name
      properties:
        id:
          type: integer
          format: int64
          default: 1
        name:
          type: string
        tag:
          type: string
    Pets:
      type: array
      items:
        $ref: "#/components/schemas/Pet"
    Users:
      type: array
      items:
        required:
          - id
          - name
        properties:
          id:
            type: integer
            format: int64
          name:
            type: string
          tag:
            type: string
    Id:
      type: string
    Rules:
      type: array
      items:
        type: string
    Error:
      description: error result
      required:
        - code
        - message
      properties:
        code:
          type: integer
          format: int32
        message:
          type: string
    apis:
      type: array
      items:
        type: object
        properties:
          apiKey:
            type: string
            description: To be used as a dataset parameter value
          apiVersionNumber:
            type: string
            description: To be used as a version parameter value
          apiUrl:
            type: string
            format: uri
            description: "The URL describing the dataset's fields"
          apiDocumentationUrl:
            type: string
            format: uri
            description: A URL to the API console for each API
    Event:
      type: object
      description: Event object
      properties:
        name:
          type: string
    Result:
        type: object
        properties:
          event:
            $ref: '#/components/schemas/Event'

Output:

Error: File not found: openapi/api.py

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {"s": {"type": ["string"]}},
  "required": ["s"]
}

Output:

# generated by datamodel-codegen:
#   filename:  simple_string.json

from __future__ import annotations

from pydantic import BaseModel


class Model(BaseModel):
    s: str

`--schema-version-mode`¶

Schema version validation mode.

The --schema-version-mode option controls how schema version validation is performed. 'lenient' (default): accept all features regardless of version. 'strict': warn on features outside the declared/detected version.

Usage

datamodel-codegen --input schema.json --schema-version-mode lenient # (1)!

--schema-version-mode - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema",
  "type": "object",
  "properties": {"s": {"type": ["string"]}},
  "required": ["s"]
}

Output:

# generated by datamodel-codegen:
#   filename:  simple_string.json

from __future__ import annotations

from pydantic import BaseModel


class Model(BaseModel):
    s: str

`--url`¶

Fetch a schema from a URL with custom HTTP headers.

The --url flag specifies a remote URL to fetch the schema from instead of a local file. The --http-headers flag adds request headers in HeaderName:HeaderValue format.

Usage

datamodel-codegen --input schema.json --url https://api.example.com/schema.json --http-headers "Authorization:Bearer token" # (1)!

--url - the option documented here

Examples

Input Schema:

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "Pet",
  "type": "object",
  "properties": {
    "id": {
      "type": "integer"
    },
    "name": {
      "type": "string"
    },
    "tag": {
      "type": "string"
    }
  }
}

Output:

# generated by datamodel-codegen:
#   filename:  https://api.example.com/schema.json
#   timestamp: 2019-07-26T00:00:00+00:00

from __future__ import annotations

from pydantic import BaseModel


class Pet(BaseModel):
    id: int | None = None
    name: str | None = None
    tag: str | None = None

📁 Base Options¶

📋 Options¶

🍳 Recipes¶

Generate a local schema file¶

Fetch a protected remote schema¶

--emit-model-metadata¶

--encoding¶

--external-ref-mapping¶

--http-backend¶

--input¶

--input-file-type¶

--input-model¶

--input-model-ref-strategy¶

--output¶

--preset¶

--schema-version¶

--schema-version-mode¶

--url¶

`--emit-model-metadata`¶

`--encoding`¶

`--external-ref-mapping`¶

`--http-backend`¶

`--input`¶

`--input-file-type`¶

`--input-model`¶

`--input-model-ref-strategy`¶

`--output`¶

`--preset`¶

`--schema-version`¶

`--schema-version-mode`¶

`--url`¶