usage:¶

datamodel-codegen [options]

Generate Python data models from schema definitions or structured data

For detailed usage, see: https://datamodel-code-generator.koxudaxi.dev

Typing customization:¶

--allof-class-hierarchy {if-no-conflict,always}

How to map allOf references to class hierarchies. 'ifno-conflict': only create subclasses when parent class has no conflicting property definition. 'always': always create subclasses.

--allof-merge-mode {constraints,all,none}

Mode for field merging in allOf schemas. 'constraints': merge only constraints (minItems, maxItems, pattern, etc.) from parent (default). 'all': merge constraints plus annotations (default, examples) from parent. 'none': do not merge any fields from parent properties.

--base-class BASE_CLASS

Base Class (default: pydantic.BaseModel)

--base-class-map BASE_CLASS_MAP

Model-specific base class mapping (JSON or JSON file path). Example: '{"MyModel": "custom.BaseA", "OtherModel": "custom.BaseB"}'. Priority: base-classmap > customBasePath (in schema) > base-class.

--disable-future-imports

Disable __future__ imports

--enum-field-as-literal {all,one,none}

Parse enum field as literal. all: all enum field type are Literal. one: field type is Literal when an enum has only one possible value. none: always use Enum class (never convert to Literal)

--enum-field-as-literal-map ENUM_FIELD_AS_LITERAL_MAP

Per-field override for enum/literal generation (JSON or JSON file path). Format: JSON object mapping field names to 'literal' or 'enum'. Example: '{"status": "literal", "priority": "enum"}'. Overrides --enumfield-as-literal for matched fields.

--field-constraints

Use field constraints and not con* annotations

--ignore-enum-constraints

Ignore enum constraints and use the base type (e.g., str, int) instead of generating Enum classes

--set-default-enum-member

Set enum members as default values for enum field

--strict-types {str,bytes,int,float,bool} [{str,bytes,int,float,bool} ...]

Use strict types

--type-mappings TYPE_MAPPINGS [TYPE_MAPPINGS ...]

Override default type mappings. Format: "type+format=target" (e.g., "string+binary=string" to map binary format to string type) or "format=target" (e.g., "binary=string"). Can be specified multiple times.

--type-overrides TYPE_OVERRIDES

Replace schema model types with custom Python types. Format: JSON object mapping model names to Python import paths. Model-level: '{"CustomType": "my_app.types.MyType"}' replaces all references. Scoped: '{"User.field": "my_app.Type"}' replaces specific field only.

--use-annotated, --no-use-annotated

Use typing.Annotated for Field(). Also, `--fieldconstraints` option will be enabled. Will become default for Pydantic v2 in a future version.

--use-closed-typed-dict, --no-use-closed-typed-dict

Generate TypedDict with PEP 728 closed=True/extra_items for additionalProperties constraints. Use --no-use-closed-typed-dict for type checkers that don't yet support PEP 728 (e.g., mypy).

--use-decimal-for-multiple-of

Use condecimal instead of confloat for float/number fields with multipleOf constraint (Pydantic only). Avoids floating-point precision issues in validation.

--use-enum-values-in-discriminator

Use enum member literals in discriminator fields instead of string literals

--use-generic-container-types

Use generic container types for type hinting (typing.Sequence, typing.Mapping). If `--use-standardcollections` option is set, then import from collections.abc instead of typing

--use-non-positive-negative-number-constrained-types

Use the Non{Positive,Negative}{FloatInt} types instead of the corresponding con* constrained types.

--use-object-type

Use object instead of Any for unspecified JSON Schema object and array values

--use-one-literal-as-default

Use one literal as default value for one literal field

--use-root-model-type-alias

Use type alias format for RootModel (e.g., Foo = RootModel[Bar]) instead of class inheritance (Pydantic v2 only)

--use-serialize-as-any

Use pydantic.SerializeAsAny for fields with types that have subtypes (Pydantic v2 only)

--use-specialized-enum, --no-use-specialized-enum

Use specialized Enum class (StrEnum, IntEnum). Requires --target-python-version 3.11+

--use-standard-collections, --no-use-standard-collections

Use standard collections for type hinting (list, dict). Default: enabled

--use-subclass-enum

Define generic Enum class as subclass with field type when enum has type (int, float, bytes, str)

--use-tuple-for-fixed-items

Generate tuple types for arrays with items array syntax when minItems equals maxItems equals items length

--use-type-alias

Use TypeAlias instead of root models (experimental)

--use-union-operator, --no-use-union-operator

Use | operator for Union type (PEP 604). Default: enabled

--use-unique-items-as-set

define field type as `set` when the field attribute has `uniqueItems`

Field customization:¶

--capitalise-enum-members, --capitalize-enum-members

Capitalize field names on enum

--empty-enum-field-name EMPTY_ENUM_FIELD_NAME

Set field name when enum value is empty (default: `_`)

--field-extra-keys FIELD_EXTRA_KEYS [FIELD_EXTRA_KEYS ...]

Add extra keys to field parameters

--field-extra-keys-without-x-prefix FIELD_EXTRA_KEYS_WITHOUT_X_PREFIX [FIELD_EXTRA_KEYS_WITHOUT_X_PREFIX ...]

Add extra keys with `x-` prefix to field parameters. The extra keys are stripped of the `x-` prefix.

--field-include-all-keys

Add all keys to field parameters

--field-type-collision-strategy {rename-field,rename-type}

Strategy for handling field name and type name collisions (Pydantic v2 only). 'rename-field': rename field with suffix and add alias (default). 'renametype': rename type class with suffix to preserve field name.

--force-optional

Force optional for required fields

--model-extra-keys MODEL_EXTRA_KEYS [MODEL_EXTRA_KEYS ...]

Add extra keys from schema extensions (x-* fields) to model_config json_schema_extra

--model-extra-keys-without-x-prefix MODEL_EXTRA_KEYS_WITHOUT_X_PREFIX [MODEL_EXTRA_KEYS_WITHOUT_X_PREFIX ...]

Add extra keys with `x-` prefix to model_config json_schema_extra. The extra keys are stripped of the `x-` prefix.

--no-alias

Do not add a field alias. E.g., if --snake-case-field is used along with a base class, which has an alias_generator

--original-field-name-delimiter ORIGINAL_FIELD_NAME_DELIMITER

Set delimiter to convert to snake case. This option only can be used with --snake-case-field (default: `_` )

--remove-special-field-name-prefix

Remove field name prefix if it has a special meaning e.g. underscores

--serialization-aliases SERIALIZATION_ALIASES

Serialization alias mapping as inline JSON or a JSON file path for Pydantic v2. Format: {'<schema_field>': '<serialization_alias>'}. Supports hierarchical formats: Flat: {'name': 'fullName'} applies to all occurrences. Scoped: {'User.name': 'fullName'} applies to specific class.

--snake-case-field, --no-snake-case-field

Change camel-case field name to snake-case

--special-field-name-prefix SPECIAL_FIELD_NAME_PREFIX

Set field name prefix when first character can't be used as Python field name (default: `field`)

--strict-nullable

Treat default field as a non-nullable field

--strip-default-none

Strip default None on fields

--union-mode {smart,left_to_right}

Union mode for only pydantic v2 field

--use-attribute-docstrings

Set use_attribute_docstrings=True in Pydantic v2 ConfigDict

--use-default

Use default value even if a field is required

--use-default-factory-for-optional-nested-models

Use default_factory for optional nested model fields instead of None default. E.g., `field: Model | None = Field(default_factory=Model)` instead of `field: Model | None = None`

--use-default-kwarg

Use `default=` instead of a positional argument for Fields that have default values.

--use-field-description

Use schema description to populate field docstring

--use-field-description-example

Use schema example to populate field docstring

--use-frozen-field, --no-use-frozen-field

Use Field(frozen=True) for readOnly fields (Pydantic v2).

--use-inline-field-description

Use schema description to populate field docstring as inline docstring

--use-missing-sentinel

Use pydantic.experimental.missing_sentinel.MISSING for optional fields without defaults (Pydantic v2.12+).

--use-serialization-alias

Use serialization_alias instead of alias for field aliasing (Pydantic v2 only). This allows setting values using the Pythonic field name while serializing to the original name.

--use-single-line-docstring

Use single-line docstrings when the content fits on one line

Model customization:¶

--alias-generator {to_camel,to_pascal,to_snake}

Pydantic v2 BaseModel alias generator to use in ConfigDict. Matching generated aliases are omitted from individual Field() calls.

--all-exports-collision-strategy {error,minimal-prefix,full-prefix}

Strategy for name collisions when using --all-exportsscope=recursive. 'error': raise an error (default). 'minimal-prefix': add module prefix only to colliding names. 'full-prefix': add full module path prefix to colliding names.

--all-exports-scope {children,recursive}

Generate __all__ in __init__.py with re-exports. 'children': export from direct child modules only. 'recursive': export from all descendant modules.

--allow-extra-fields

Deprecated: --allow-extra-fields is deprecated. Use --extra-fields=allow instead.

--allow-leading-underscore-class-name

Allow an explicitly specified root class name to start with an underscore

--allow-population-by-field-name, --no-allow-population-by-field-name

Allow population by field name

--class-name CLASS_NAME

Set class name of root model

--class-name-affix-scope {all,models,enums}

Scope for applying --class-name-prefix/--class-namesuffix. 'all': Apply to all classes including enums (default). 'models': Apply only to model classes. 'enums': Apply only to enum classes.

--class-name-prefix CLASS_NAME_PREFIX

Prefix to add to generated class names (e.g., 'Api' produces 'ApiUser'). Does not apply to root model when --class-name is specified.

--class-name-suffix CLASS_NAME_SUFFIX

Suffix to add to generated class names (e.g., 'Schema' produces 'UserSchema'). Does not apply to root model when --class-name is specified.

--collapse-reuse-models

When used with --reuse-model, collapse duplicate models by replacing references instead of creating empty inheritance subclasses. This eliminates 'class Foo(Bar): pass' patterns

--collapse-root-models, --no-collapse-root-models

Models generated with a root-type field will be merged into the models using that root-type model

--collapse-root-models-name-strategy {child,parent}

Strategy for naming when collapsing root models that reference other models. 'child': Keep inner model's name (default). 'parent': Use wrapper's name for inner model. Requires --collapse-root-models to be set.

--dataclass-arguments DATACLASS_ARGUMENTS

Custom dataclass arguments as a JSON dictionary, e.g. '{"frozen": true, "kw_only": true}'. Overrides --frozen-dataclasses and similar flags.

--disable-appending-item-suffix

Disable appending `Item` suffix to model name in an array

--disable-timestamp

Disable timestamp on file headers

--duplicate-name-suffix DUPLICATE_NAME_SUFFIX

JSON mapping of type to suffix for resolving duplicate name conflicts. Example: '{"model": "Schema"}' changes Address1 to AddressSchema. Keys: 'model' (for classes), 'enum' (for enums), 'default' (fallback). When not specified, uses numeric suffix (Address1, Address2).

--enable-command-header

Enable command-line options on file headers for reproducibility

--enable-faux-immutability

Enable faux immutability

--enable-generated-header-marker

Enable @generated marker on file headers

--enable-version-header

Enable package version on file headers

--extra-fields {allow,ignore,forbid}

Set the generated models to allow, forbid, or ignore extra fields.

--frozen-dataclasses

Generate frozen dataclasses (dataclass(frozen=True)). Only applies to dataclass output.

--infer-union-variant-names

Infer inline oneOf/anyOf branch model names from literal discriminator-style fields

--keep-model-order

Keep generated models' order

--keyword-only

Defined models as keyword only (for example dataclass(kw_only=True)).

--model-name-map MODEL_NAME_MAP

Rename generated model classes by schema ref or current generated class name using a JSON object or JSON file.

--module-split-mode {single}

Split generated models into separate files. 'single': generate one file per model class.

--naming-strategy {numbered,parent-prefixed,full-path,primary-first}

Strategy for generating unique model names when duplicates occur. 'numbered' (default): Append numeric suffix (Address, Address1, Address2). Simple but names don't indicate context. 'parent-prefixed': Prefix with parent model name using underscore (Company_Address, Company_Employee_Address for nested). Names show hierarchy. 'full-path': Similar to parent-prefixed but joins with CamelCase (CompanyAddress, CompanyEmployeeAddress). More readable for deep nesting. 'primary-first': Keep clean names for primary definitions (in /definitions/ or /components/schemas/), only add suffix to inline/nested duplicates.

--output-date-class {date,PastDate,FutureDate}

Choose Date class between PastDate, FutureDate or date. (Pydantic v2 only) Each output model has its default mapping.

--output-datetime-class {datetime,AwareDatetime,NaiveDatetime,PastDatetime,FutureDatetime}

Choose Datetime class between AwareDatetime, NaiveDatetime, PastDatetime, FutureDatetime or datetime. Each output model has its default mapping (for example pydantic: datetime, dataclass: str, ...)

--parent-scoped-naming

Deprecated: --parent-scoped-naming is deprecated. Use --naming-strategy parent-prefixed instead.

--reuse-model

Reuse models on the field when a module has the model with the same content

--reuse-scope {module,tree}

Scope for model reuse deduplication: module (per-file, default) or tree (cross-file with shared module). Only effective when --reuse-model is set.

--shared-module-name SHARED_MODULE_NAME

Name of the shared module for --reuse-scope=tree (default: "shared"). Use this option if your schema has a file named "shared".

--skip-root-model

Skip generating the model for the root schema element

--target-pydantic-version {2,2.11,2.12}

Target Pydantic version for generated code. '2': Pydantic 2.0+ compatible (default, uses populate_by_name). '2.11': Pydantic 2.11+ (uses validate_by_name). '2.12': Pydantic 2.12+ (supports MISSING sentinel).

--target-python-version {3.10,3.11,3.12,3.13,3.14}

target python version

--treat-dot-as-module, --no-treat-dot-as-module

Treat dotted schema names as module paths, creating nested directory structures (e.g., 'foo.bar.Model' becomes 'foo/bar.py'). Use --no-treat-dot-as-module to keep dots in names as underscores for single-file output.

--use-exact-imports

import exact types instead of modules, for example: "from .foo import Bar" instead of "from . import foo" with "foo.Bar"

--use-generic-base-class

Generate a shared base class with model configuration (e.g., extra='forbid') instead of repeating the configuration in each model. Keeps code DRY.

--use-pendulum

use pendulum instead of datetime

--use-root-model-sequence-interface

Make non-null sequence-like Pydantic v2 RootModel classes implement collections.abc.Sequence by adding Sequence[T] inheritance and root-delegating __iter__, __getitem__, and __len__ methods

--use-schema-description

Use schema description to populate class docstring

--use-standard-primitive-types, --no-use-standard-primitive-types

Use Python standard library types for string formats (UUID, IPv4Address, etc.) instead of str. Affects dataclass, msgspec, TypedDict output. Pydantic already uses these types by default.

--use-title-as-name

use titles as class names of models

Template customization:¶

--aliases ALIASES

Alias mapping as inline JSON or a JSON file path for renaming fields. Format: {'<schema_field>': '<python_name>'} - the schema field name becomes the Pydantic alias. Supports hierarchical formats: Flat: {'id': 'id_'} applies to all occurrences. Scoped: {'User.name': 'user_name'} applies to specific class. Priority: scoped > flat. Multiple aliases (Pydantic v2 only): {'field': ['alt1', 'alt2']} uses AliasChoices for validation. Example: {'User.name': 'user_name', 'id': 'id_'} generates `id_: ... = Field(alias='id')`.

--custom-file-header CUSTOM_FILE_HEADER

Custom file header

--custom-file-header-path CUSTOM_FILE_HEADER_PATH

Custom file header file path

--custom-formatters-kwargs CUSTOM_FORMATTERS_KWARGS

Custom formatter kwargs as inline JSON or a JSON file path.

--custom-template-dir CUSTOM_TEMPLATE_DIR

Custom template directory

--default-values DEFAULT_VALUES

Default value overrides as inline JSON or a JSON file path. Supports hierarchical formats: Flat: {'field': value} applies to all occurrences. Scoped: {'ClassName.field': value} applies to specific class. Priority: scoped > flat. Note: Scoped keys use the generated class name for JSON Schema/OpenAPI. Required fields remain required unless --use-default is also specified. Example: {'User.status': 'active', 'page': 1, 'limit': 10}

--encoding ENCODING

The encoding of input and output (default: utf-8)

--extra-template-data EXTRA_TEMPLATE_DATA

Extra template data for output models as inline JSON or a JSON file path. For OpenAPI and Jsonschema the keys are the spec path of the object, or the name of the object if you want to apply the template data to multiple objects with the same name. If you are using another input file type (e.g. GraphQL), the key is the name of the object. The value is a dictionary of the template data to add.

--generate-schema-validators

Generate Pydantic v2 model validators for JSON Schema rules that cannot be represented as type hints (experimental).

--schema-validator-base-class-name SCHEMA_VALIDATOR_BASE_CLASS_NAME

Set the generated shared Pydantic v2 schema runtime validator base class name.

--schema-validator-type {pydantic-v2}

Select the schema-derived runtime validator backend. 'pydantic-v2' generates Pydantic v2 model validators (experimental).

--use-double-quotes

Model generated with double quotes. Single quotes or your black config skip_string_normalization value will be used without this option.

--use-type-checking-imports, --no-use-type-checking-imports

Allow Ruff to move typing-only imports into TYPE_CHECKING blocks. By default this stays enabled, except for multi-module Ruff formatting of modular Pydantic output where referenced models stay imported at runtime. Use --no-use-type-checking-imports to force runtime imports.

--validators VALIDATORS

Validators configuration as inline JSON or a JSON file path. Defines field validators for Pydantic v2 models. Keys are model names, values contain validator definitions with field, function, and mode.

--wrap-string-literal

Wrap string literal by using black `experimentalstring-processing` option (require black 20.8b0 or later)

OpenAPI-only options:¶

--include-path-parameters

Include path parameters in generated parameter models in addition to query parameters (Only OpenAPI)

--openapi-include-info-version

Emit OpenAPI info.version as OPENAPI_INFO_VERSION in generated models

--openapi-include-paths PATTERN [PATTERN ...]

Include only OpenAPI paths matching fnmatch patterns. Use wildcards: '*' matches any chars, '?' matches single char. Example: '/users/*' '/products'. Requires '--openapi-scopes' to include 'paths'.

--openapi-scopes {schemas,paths,tags,parameters,webhooks,requestbodies} [{schemas,paths,tags,parameters,webhooks,requestbodies} ...]

Scopes of OpenAPI model generation (default: schemas)

--read-only-write-only-model-type {request-response,all}

Model generation for readOnly/writeOnly fields: 'request-response' = Request/Response models only (no base model), 'all' = Base + Request + Response models.

--use-operation-id-as-name

use operation id of OpenAPI as class names of models

--use-status-code-in-response-name

Include HTTP status code in response model names (e.g., ResourceGetResponse200, ResourceGetResponseDefault)

--validation

Deprecated: The `--validation` option is deprecated and will be removed in a future release. Use --fieldconstraints instead.

GraphQL-only options:¶

--graphql-no-typename

Exclude __typename field from generated GraphQL models. Useful when using generated models for GraphQL mutations.

General options:¶

--check

Verify generated files are up-to-date without modifying them. Exits with code 1 if differences found, 0 if up-to-date. Useful for CI to ensure generated code is committed.

--debug

show debug message (require "debug". `$ pip install 'datamodel-code-generator[debug]'`)

--disable-warnings

disable warnings

--generate-cli-command

Generate CLI command from pyproject.toml configuration and exit

--generate-prompt [QUESTION]

Generate a prompt for consulting LLMs about CLI options. Optionally provide your question as an argument. Pipe to CLI tools (e.g., `| claude -p`, `| codex exec`) or copy to clipboard (e.g., `| pbcopy`, `| xclip`) for web LLM chats.

--generate-pyproject-config

Generate pyproject.toml configuration from the provided CLI arguments and exit

--ignore-pyproject

Ignore pyproject.toml configuration

--list-deprecations [{table,json,markdown}]

List registered deprecations and scheduled breaking changes, then exit.

--list-experimental [{table,json,markdown}]

List registered experimental features, then exit.

--no-color

disable colorized output

--output-format {text,json}

Format for command output (default: text). Use json for structured output when supported.

--output-format-json-schema {config,generate-prompt,generation,model-metadata,structured-output}

Output JSON Schema for the selected JSON output or JSON configuration format and exit.

--profile PROFILE

Use a named profile from pyproject.toml [tool.datamodel-codegen.profiles.<name>]

--version

show version

--watch

Watch input file(s) for changes and regenerate output automatically

--watch-delay WATCH_DELAY

Debounce delay in seconds for watch mode (default: 0.5)

-h, --help

show this help message and exit

Documentation: https://datamodel-code-generator.koxudaxi.dev Agent skill: https://datamodel-code-generator.koxudaxi.dev/coding-agent-skill/ GitHub: https://github.com/koxudaxi/datamodel-code-generator