datamodel-code-generator

This code generator creates pydantic v1 and v2 model, dataclasses.dataclass, typing.TypedDict and msgspec.Struct from an openapi file and others.

Help

See documentation for more details.

Quick Installation

To install datamodel-code-generator:

$ pip install datamodel-code-generator

Simple Usage

You can generate models from a local file.

$ datamodel-codegen --input api.yaml --output model.py

api.yaml

openapi: "3.0.0"info:
version: 1.0.0title: Swagger Petstorelicense:
name: MITservers:
- url: http://petstore.swagger.io/v1paths:
/pets:
get:
summary: List all petsoperationId: listPetstags:
- petsparameters:
- name: limitin: querydescription: How many items to return at one time (max 100)required: falseschema:
type: integerformat: int32responses:
'200':
description: A paged array of petsheaders:
x-next:
description: A link to the next page of responsesschema:
type: stringcontent:
application/json:
schema:
$ref: "#/components/schemas/Pets"default:
description: unexpected errorcontent:
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}/invocationspassthroughBehavior: when_no_templateshttpMethod: POSTtype: aws_proxypost:
summary: Create a petoperationId: createPetstags:
- petsresponses:
'201':
description: Null responsedefault:
description: unexpected errorcontent:
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}/invocationspassthroughBehavior: when_no_templateshttpMethod: POSTtype: aws_proxy/pets/{petId}:
get:
summary: Info for a specific petoperationId: showPetByIdtags:
- petsparameters:
- name: petIdin: pathrequired: truedescription: The id of the pet to retrieveschema:
type: stringresponses:
'200':
description: Expected response to a valid requestcontent:
application/json:
schema:
$ref: "#/components/schemas/Pets"default:
description: unexpected errorcontent:
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}/invocationspassthroughBehavior: when_no_templateshttpMethod: POSTtype: aws_proxycomponents:
schemas:
Pet:
required:
- id
- nameproperties:
id:
type: integerformat: int64name:
type: stringtag:
type: stringPets:
type: arrayitems:
$ref: "#/components/schemas/Pet"Error:
required:
- code
- messageproperties:
code:
type: integerformat: int32message:
type: stringapis:
type: arrayitems:
type: objectproperties:
apiKey:
type: stringdescription: To be used as a dataset parameter valueapiVersionNumber:
type: stringdescription: To be used as a version parameter valueapiUrl:
type: stringformat: uridescription: "The URL describing the dataset's fields"apiDocumentationUrl:
type: stringformat: uridescription: A URL to the API console for each API

model.py

# generated by datamodel-codegen:# filename: api.yaml# timestamp: 2020-06-02T05:28:24+00:00from __future__ importannotationsfromtypingimportList, OptionalfrompydanticimportAnyUrl, BaseModel, FieldclassPet(BaseModel):
id: intname: strtag: Optional[str] =NoneclassPets(BaseModel):
__root__: List[Pet]
classError(BaseModel):
code: intmessage: strclassApi(BaseModel):
apiKey: Optional[str] =Field(
None, description='To be used as a dataset parameter value'
)
apiVersionNumber: Optional[str] =Field(
None, description='To be used as a version parameter value'
)
apiUrl: Optional[AnyUrl] =Field(
None, description="The URL describing the dataset's fields"
)
apiDocumentationUrl: Optional[AnyUrl] =Field(
None, description='A URL to the API console for each API'
)
classApis(BaseModel):
__root__: List[Api]

Supported input types

• OpenAPI 3 (YAML/JSON, OpenAPI Data Type);
• JSON Schema (JSON Schema Core/JSON Schema Validation);
• JSON/YAML/CSV Data (it will be converted to JSON Schema);
• Python dictionary (it will be converted to JSON Schema);
• GraphQL schema (GraphQL Schemas and Types);

Supported output types

• pydantic.BaseModel;
• pydantic_v2.BaseModel;
• dataclasses.dataclass;
• typing.TypedDict;
• msgspec.Struct;
• Custom type from your jinja2 template;

Sponsors

JetBrains

Astral

Datadog, Inc.

Projects that use datamodel-code-generator

These OSS projects use datamodel-code-generator to generate many models. See the following linked projects for real world examples and inspiration.

• airbytehq/airbyte
  • Generate Python, Java/Kotlin, and Typescript protocol models
• apache/iceberg
  • Generate Python codemake generate
• argoproj-labs/hera
  • Makefile
• awslabs/aws-lambda-powertools-python
  • Recommended for advanced-use-cases in the official documentation
• DataDog/integrations-core
  • Config models
• hashintel/hash
  • codegen.sh
• IBM/compliance-trestle
  • Building the models from the OSCAL schemas.
• Netflix/consoleme
  • How do I generate models from the Swagger specification?
• Nike-Inc/brickflow
  • Code generate tools./tools/gen-bundle.sh
• open-metadata/OpenMetadata
  • Makefile
• PostHog/posthog
  • Generate models via npm run
• SeldonIO/MLServer
  • generate-types.sh

Installation

To install datamodel-code-generator:

$ pip install datamodel-code-generator

http extra option

If you want to resolve $ref for remote files then you should specify http extra option.

$ pip install 'datamodel-code-generator[http]'

graphql extra option

If you want to generate data model from a GraphQL schema then you should specify graphql extra option.

$ pip install 'datamodel-code-generator[graphql]'

Docker Image

The docker image is in Docker Hub

$ docker pull koxudaxi/datamodel-code-generator

Advanced Uses

You can generate models from a URL.

$ datamodel-codegen --url https://<INPUT FILE URL> --output model.py

This method needs the http extra option

All Command Options

The datamodel-codegen command:

usage: datamodel-codegen [options]
Generate Python data models from schema definitions or structured data
Options:
--additional-imports ADDITIONAL_IMPORTS
Custom imports for output (delimited list input). For example
"datetime.date,datetime.datetime"
--custom-formatters CUSTOM_FORMATTERS
List of modules with custom formatter (delimited list input).
--http-headers HTTP_HEADER [HTTP_HEADER ...]
Set headers in HTTP requests to the remote host. (example:
"Authorization: Basic dXNlcjpwYXNz")
--http-ignore-tls Disable verification of the remote host''s TLS certificate
--http-query-parameters HTTP_QUERY_PARAMETERS [HTTP_QUERY_PARAMETERS ...]
Set query parameters in HTTP requests to the remote host. (example:
"ref=branch")
--input INPUT Input file/directory (default: stdin)
--input-file-type {auto,openapi,jsonschema,json,yaml,dict,csv,graphql}
Input file type (default: auto)
--output OUTPUT Output file (default: stdout)
--output-model-type {pydantic.BaseModel,pydantic_v2.BaseModel,dataclasses.dataclass,typing.TypedDict,msgspec.Struct}
Output model type (default: pydantic.BaseModel)
--url URL Input file URL. `--input` is ignored when `--url` is used
Typing customization:
--base-class BASE_CLASS
Base Class (default: pydantic.BaseModel)
--enum-field-as-literal {all,one}
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
--field-constraints Use field constraints and not con* annotations
--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
--use-annotated Use typing.Annotated forField(). Also, `--field-constraints` option
will be enabled.
--use-generic-container-types
Use generic container types fortype hinting (typing.Sequence,
typing.Mapping). If `--use-standard-collections` 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-one-literal-as-default
Use one literal as default value for one literal field
--use-standard-collections
Use standard collections fortype hinting (list, dict)
--use-subclass-enum Define Enum class as subclass with field type when enum has type
(int, float, bytes, str)
--use-union-operator Use | operator for Union type (PEP 604).
--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
--force-optional Force optional for required fields
--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
--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`)
--strip-default-none Strip default None on fields
--union-mode {smart,left_to_right}
Union mode for only pydantic v2 field
--use-default Use default value even if a field is required
--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
Model customization:
--allow-extra-fields Allow to pass extra fields, if this flag is not passed, extra fields
are forbidden.
--allow-population-by-field-name
Allow population by field name
--class-name CLASS_NAME
Set class name of root model
--collapse-root-models
Models generated with a root-type field will be merged into the
models using that root-type model
--disable-appending-item-suffix
Disable appending `Item` suffix to model name in an array
--disable-timestamp Disable timestamp on file headers
--enable-faux-immutability
Enable faux immutability
--enable-version-header
Enable package version on file headers
--keep-model-order Keep generated models'' order
--keyword-only Defined models as keyword only (for example
dataclass(kw_only=True)).
--output-datetime-class {datetime,AwareDatetime,NaiveDatetime}
Choose Datetime class between AwareDatetime, NaiveDatetime or
datetime. Each output model has its default mapping, and only
pydantic and dataclass support this override" --reuse-model Reuse models on the field when a module has the model with the same content --target-python-version {3.6,3.7,3.8,3.9,3.10,3.11,3.12} target python version (default: 3.8) --treat-dot-as-module treat dotted module names as modules --use-exact-imports import exact types instead of modules, for example: "from .foo
import Bar" instead of "from . import foo" with "foo.Bar" --use-pendulum use pendulum instead of datetime --use-schema-description Use schema description to populate class docstring --use-title-as-name use titles as class names of modelsTemplate customization: --aliases ALIASES Alias mapping file --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 A file with kwargs for custom formatters. --custom-template-dir CUSTOM_TEMPLATE_DIR Custom template directory --encoding ENCODING The encoding of input and output (default: utf-8) --extra-template-data EXTRA_TEMPLATE_DATA Extra template data --use-double-quotes Model generated with double quotes. Single quotes or your black config skip_string_normalization value will be used without this option. --wrap-string-literal Wrap string literal by using black `experimental-string-processing` option (require black 20.8b0 or later)OpenAPI-only options: --openapi-scopes {schemas,paths,tags,parameters} [{schemas,paths,tags,parameters} ...] Scopes of OpenAPI model generation (default: schemas) --strict-nullable Treat default field as a non-nullable field (Only OpenAPI) --use-operation-id-as-name use operation id of OpenAPI as class names of models --validation Deprecated: Enable validation (Only OpenAPI). this option is deprecated. it will be removed in future releasesGeneral options: --debug show debug message (require "debug". `$ pip install ''datamodel-code- generator[debug]''`) --disable-warnings disable warnings --no-color disable colorized output --version show version -h, --help show this help message and exit

Related projects

fastapi-code-generator

This code generator creates FastAPI app from an openapi file.

https://github.com/koxudaxi/fastapi-code-generator

pydantic-pycharm-plugin

A JetBrains PyCharm plugin for pydantic.

https://github.com/koxudaxi/pydantic-pycharm-plugin

PyPi

https://pypi.org/project/datamodel-code-generator

Contributing

See docs/development-contributing.md for how to get started!

License

datamodel-code-generator is released under the MIT License. http://www.opensource.org/licenses/mit-license