Skip to content

📚 Supported Input Formats

This code generator supports the following input formats:

Use --input-file-type auto (the default) for common files, or set an explicit type when a file extension is ambiguous. For example, YAML can contain either an OpenAPI/JSON Schema document or raw sample data, so use jsonschema, openapi, or yaml depending on the intended input.

Input Format Guide

Input Format Guide (from code)

The tables below are generated from the input type enum, parser routing code, schema version enums, raw-data conversion rules, and parser type conversion maps.

Parser Routes and Version Flags

Input format Selector Parser route --schema-version Auto detection
JSON Schema jsonschema JsonSchemaParser draft-04, draft-06, draft-07, 2019-09, 2020-12, auto $schema, type, properties, or composition keywords
OpenAPI openapi OpenAPIParser 3.0, 3.1, 3.2, auto openapi field
AsyncAPI asyncapi AsyncAPIParser 2.0, 3.0, auto asyncapi field
GraphQL schema graphql GraphQLParser Not supported Explicit only
XML Schema xmlschema XMLSchemaParser 1.0, 1.1, auto XML Schema namespace on the root element
Protocol Buffers protobuf ProtobufParser proto2, proto3, 2023, auto Protocol Buffers syntax/message-like text
Apache Avro avro AvroParser Not supported Avro schema object, union, or primitive schema form
MCP tool schemas mcp-tools JsonSchemaParser after MCP conversion Converted to JSON Schema; draft-04, draft-06, draft-07, 2019-09, 2020-12, auto Explicit only
JSON data json JsonSchemaParser after genson conversion Converted to JSON Schema; draft-04, draft-06, draft-07, 2019-09, 2020-12, auto Mapping that is not a schema/OpenAPI/AsyncAPI/Avro document
YAML data yaml JsonSchemaParser after genson conversion Converted to JSON Schema; draft-04, draft-06, draft-07, 2019-09, 2020-12, auto Explicit for YAML sample data
CSV data csv JsonSchemaParser after genson conversion Converted to JSON Schema; draft-04, draft-06, draft-07, 2019-09, 2020-12, auto Detected from CSV-like text with consistent comma counts across non-empty lines or explicit csv
Python dictionary data dict JsonSchemaParser after genson conversion Converted to JSON Schema; draft-04, draft-06, draft-07, 2019-09, 2020-12, auto Explicit for mapping input
Python input model --input-model JsonSchemaParser after Python schema conversion JSON Schema after conversion; dict input can select another explicit schema type Explicit only

Accepted Source Shapes

Input format Accepted source shape
JSON Schema JSON Schema document as JSON/YAML, mapping, URL, or file
OpenAPI OpenAPI document as JSON/YAML, mapping, URL, or file
AsyncAPI AsyncAPI document as JSON/YAML, mapping, URL, or file
GraphQL schema GraphQL SDL text, URL, or file
XML Schema XSD XML text, URL, or file
Protocol Buffers .proto text, file, directory, URL, or path list
Apache Avro Avro schema JSON/YAML, mapping, list, URL, or file
MCP tool schemas MCP tool list/profile as JSON/YAML, mapping, list, URL, or file
JSON data JSON sample data text or file
YAML data YAML sample data text or file
CSV data CSV text or file with a header row and at least one data row
Python dictionary data In-memory mapping or Python literal data
Python input model module:Object or path/to/file.py:Object via --input-model

Format Type Coverage

Input family Code-derived coverage Guide
JSON Schema 7 schema types, 54 common formats Uses JSON Schema type/format mappings and feature metadata below
OpenAPI JSON Schema mappings plus 2 OpenAPI-only formats Adds OpenAPI-specific schema features and formats
GraphQL 6 GraphQL type kinds Uses GraphQL SDL parser order and parser method map
XML Schema 50 built-in XSD datatypes Converts XSD built-ins to JSON Schema fragments
Protocol Buffers 15 scalar field types, 17 well-known type mappings Converts descriptors to JSON Schema definitions
Apache Avro 8 primitives, 13 logical type mappings Converts Avro schemas to JSON Schema while preserving Avro metadata
JSON/YAML/CSV/Dict data 4 raw data selectors Samples are converted to JSON Schema with genson before parsing
Python input model 4 supported object kinds Python objects are converted to schema data before normal generation

GraphQL Type Kinds

GraphQL kind Parser method Generated shape
scalar parse_scalar Generates scalar aliases
enum parse_enum Generates enums or literals depending on enum options
interface parse_interface Generates model classes from interface fields
object parse_object Generates model classes except root Query/Mutation objects
input_object parse_input_object Generates model classes for input objects
union parse_union Generates union type aliases

Apache Avro Primitive Types

Avro primitive JSON Schema mapping Constraints
null null -
boolean boolean -
int integer + int32 -
long integer + int64 -
float number + float -
double number + double -
bytes string + binary -
string string -

Apache Avro Logical Types

Avro logical type Allowed Avro type JSON Schema mapping
decimal bytes, fixed string + decimal
big-decimal bytes string + decimal
uuid string, fixed string + uuid
date int string + date
time-millis int string + time
time-micros long string + time
timestamp-millis long string + date-time
timestamp-micros long string + date-time
timestamp-nanos long string + date-time
local-timestamp-millis long string + date-time-local
local-timestamp-micros long string + date-time-local
local-timestamp-nanos long string + date-time-local
duration fixed string + duration

Protocol Buffers Scalar Types

Protobuf scalar JSON Schema mapping Constraints
double number + double -
float number + float -
int64 integer + int64 -
uint64 integer + int64 minimum=0, maximum=18446744073709551615
int32 integer + int32 -
uint32 integer + int32 minimum=0, maximum=4294967295
sint32 integer + int32 -
sint64 integer + int64 -
fixed32 integer + int32 minimum=0, maximum=4294967295
fixed64 integer + int64 minimum=0, maximum=18446744073709551615
sfixed32 integer + int32 -
sfixed64 integer + int64 -
bool boolean -
string string -
bytes string + binary -

Protocol Buffers Well-Known Types

Well-known type JSON Schema mapping
google.protobuf.Timestamp string + date-time
google.protobuf.Duration string + duration
google.protobuf.Struct object map
google.protobuf.ListValue array
google.protobuf.Value null | boolean | number | string | object map | array
google.protobuf.Any object map
google.protobuf.Empty object
google.protobuf.FieldMask string
google.protobuf.DoubleValue number + double | null
google.protobuf.FloatValue number + float | null
google.protobuf.Int64Value integer + int64 | null
google.protobuf.UInt64Value integer + int64 | null
google.protobuf.Int32Value integer + int32 | null
google.protobuf.UInt32Value integer + int32 | null
google.protobuf.BoolValue boolean | null
google.protobuf.StringValue string | null
google.protobuf.BytesValue string + binary | null

XML Schema Built-In Type Groups

JSON Schema mapping XSD built-ins Count
Any anySimpleType, anyAtomicType, anyType 3
string + uri anyURI 1
string + byte base64Binary 1
boolean boolean 1
integer byte, int, integer, long, negativeInteger, nonNegativeInteger, nonPositiveInteger, positiveInteger, +5 more 13
string + date date 1
string + date-time dateTime, dateTimeStamp 2
number + decimal decimal 1
number double, float 2
string duration, ENTITY, gDay, gMonth, gMonthDay, gYear, gYearMonth, hexBinary, +12 more 20
string + duration dayTimeDuration 1
array ENTITIES, IDREFS, NMTOKENS 3
string + time time 1

Python Input Types

Python input object Conversion behavior
dict Returned directly as the schema; --input-file-type is required
Pydantic v2 BaseModel Converted with Pydantic model_json_schema()
dataclass Converted with Pydantic TypeAdapter; includes stdlib and Pydantic dataclasses
TypedDict Converted with Pydantic TypeAdapter
Multiple --input-model Supported only for Pydantic v2 BaseModel classes

📘 OpenAPI 3 and JSON Schema

Below are the data types and features recognized by datamodel-code-generator for OpenAPI 3 and JSON Schema.

Schema Feature Support (from code)

The JSON Schema and OpenAPI feature matrix below is generated from the same code metadata used by the schema version support page.

JSON Schema Features

Feature Introduced Status Description
Null in type array Draft 4 or earlier ✅ Supported Allows type: ['string', 'null'] syntax for nullable types
$defs 2019-09 ✅ Supported Uses $defs instead of definitions for schema definitions
prefixItems 2020-12 ✅ Supported Tuple validation using prefixItems keyword
Boolean schemas Draft 6 ✅ Supported Allows true and false as valid schemas
$id Draft 6 ✅ Supported Schema identifier field (id in Draft 4, $id in Draft 6+)
definitions/$defs Draft 4 ✅ Supported Key for reusable schema definitions
exclusiveMinimum/Maximum as number Draft 6 ✅ Supported Numeric exclusiveMinimum/exclusiveMaximum (boolean in Draft 4)
readOnly/writeOnly Draft 7 ✅ Supported Field visibility hints for read-only and write-only properties
const Draft 6 ✅ Supported Single constant value constraint
propertyNames Draft 6 ✅ Supported Dict key type constraints via pattern, enum, or $ref
contains Draft 6 ⚠️ Partial Count constraints are modeled when contains matches every item; general schema-valued contains is not supported
deprecated 2019-09 ⚠️ Partial Marks schema elements as deprecated
if/then/else Draft 7 ❌ Not Supported Conditional schema validation
contentMediaType/contentEncoding Draft 7 ⚠️ Partial Content type and encoding hints for strings
contentSchema 2019-09 ⚠️ Partial Schema for decoded string content
$anchor 2019-09 ✅ Supported Location-independent schema references
$vocabulary 2019-09 ❌ Not Supported Vocabulary declarations for meta-schemas
unevaluatedProperties 2019-09 ⚠️ Partial Additional properties not evaluated by subschemas
unevaluatedItems 2019-09 ⚠️ Partial Additional items not evaluated by subschemas
dependentRequired 2019-09 ❌ Not Supported Conditional property requirements
dependentSchemas 2019-09 ❌ Not Supported Conditional schema application based on property presence
$recursiveRef/$recursiveAnchor 2019-09 ✅ Supported Recursive reference resolution via anchors
$dynamicRef/$dynamicAnchor 2020-12 ✅ Supported Dynamic reference resolution across schemas
$ref with sibling keywords 2019-09 ⚠️ Partial Keywords beside $ref apply with the referenced schema (ignored in Draft 4-7 and OAS 3.0)

OpenAPI-Specific Features

Client: whether the generated Python client (--generate-client) supports the feature; an operation that uses an unsupported one is skipped with a warning. A dash means the client follows the models.

Feature Introduced Status Client Description
nullable OAS 3.0 ✅ Supported — Uses nullable: true for nullable types (deprecated in 3.1)
discriminator OAS 3.0 ✅ Supported — Polymorphism support via discriminator keyword
webhooks OAS 3.1 ✅ Supported ⚠️ Partial Top-level webhooks object for incoming events; the client generates no methods for webhook operations, only helpers that verify and decode deliveries
itemSchema OAS 3.2 ✅ Supported — Media Type Object item schema for sequential media
$self OAS 3.2 ✅ Supported — Root document URI for relative and absolute reference resolution
querystring OAS 3.2 ✅ Supported ⚠️ Partial Query string parameter object without a parameter name; the client ignores the encoding declarations of the members of a nameless form querystring
xml OAS 3.0 ⚠️ Partial — XML serialization metadata (name, namespace, prefix)
externalDocs OAS 3.0 ⚠️ Partial — Reference to external documentation
links OAS 3.0 ❌ Not Supported — Links between operations
callbacks OAS 3.0 ❌ Not Supported — Callback definitions for webhooks
securitySchemes OAS 3.0 ❌ Not Supported — API security mechanism definitions
http security schemes OAS 3.0 ❌ Not Supported ⚠️ Partial HTTP authentication schemes; the client sends basic and bearer only
mutualTLS OAS 3.1 ❌ Not Supported ❌ Not Supported Mutual TLS security scheme
style: cookie OAS 3.2 ✅ Supported ✅ Supported Cookie parameter style; earlier versions do not declare it
style: deepObject OAS 3.0 ✅ Supported ⚠️ Partial Query parameters written as name[key]=value; the client writes objects of scalars, and arrays, scalars, nested objects and arrays of objects, which OpenAPI leaves undefined, of query parameters and URL-encoded form members as name[]=value, name=value, name[key][key]=value and name[0][key]=value only with --client-deep-object-brackets
Structured style values OAS 3.0 ✅ Supported ⚠️ Partial Parameter and form member values that are no single scalar kind, such as nested objects, unions and allOf, written with a style; the client writes only a parameter outside a header, or a URL-encoded form member, that takes one item or an array of them, and with --client-deep-object-brackets deepObject values, as style: deepObject describes
Binary strings in text media OAS 3.0 ✅ Supported ❌ Not Supported format: binary strings inside a JSON, URL-encoded or text body, a parameter or a header
multipart media types OAS 3.0 ✅ Supported ⚠️ Partial Multipart bodies; the client maps the parts of multipart/form-data with an object schema, or a union of objects that agree on the parts of each property, only, such as not multipart/related
Encoding contentType OAS 3.0 ✅ Supported ⚠️ Partial Media types of form-data parts; the client writes a part holding no files as JSON, or its scalars as text in a media type other than a form or multipart media type

AsyncAPI Client Features

The AsyncAPI features the generated Python client plans itself; a channel that uses an unsupported one is left out of the client with a warning, and its models are generated as usual. Message headers leave no channel out.

Feature Introduced Client Description
server protocols AsyncAPI 2.0 ⚠️ Partial The protocol of a server; the client opens the channels of ws and wss servers as WebSockets, and the server-sent event channels of http, https and sse servers
server-sent event channels AsyncAPI 2.0 ⚠️ Partial A channel that carries text/event-stream messages, its own or a trait's, or that no ws or wss server serves and an sse server serves or whose http binding fixes Accept or Content-Type to text/event-stream; the client opens it with a GET, whose query and header parameters are those of the http bindings of the channel and its operations, and receives the JSON data of each of its messages until the stream ends, without reconnecting; it does not receive other content types on it or open it with another method
server variables AsyncAPI 2.0 ⚠️ Partial The variables of a server's URL; the client substitutes each by its default, which OpenAPI requires and AsyncAPI does not
channels without an address AsyncAPI 3.0 ❌ Not Supported A channel whose address is null or absent, which the client cannot open
WebSocket channel bindings AsyncAPI 2.0 ⚠️ Partial bindings.ws of a channel; the client opens GET handshakes, with the properties of objects query and headers as parameters, and the values a Sec-WebSocket-Protocol header fixes as the subprotocols it offers
message content types AsyncAPI 2.0 ⚠️ Partial The payloads of messages; the client codes JSON, text/plain strings and application/octet-stream payloads of JSON Schema or AsyncAPI schemas, and no contentEncoding string outside JSON
messages without a payload AsyncAPI 2.0 ❌ Not Supported A message that declares no payload, which the client cannot code
message headers AsyncAPI 2.0 ⚠️ Partial The headers of a message; the client codes its payload but neither sends nor reads headers, which a WebSocket frame does not carry, and opens the channel without a warning
several messages per direction AsyncAPI 2.0 ⚠️ Partial More than one message that an application sends, or receives, on one channel; the client tells JSON messages apart by a tag their models declare, else by their class when it sends them, and Pydantic models code them as a union; it does not receive text and JSON messages on one channel
channels sharing an address AsyncAPI 2.0 ⚠️ Partial Channels at one address on the same servers, which the client opens as one connection that carries the messages of them all; their handshakes must take the same parameters, offer the same subprotocols and need the same security
operation replies AsyncAPI 3.0 ⚠️ Partial The reply of an operation; the client sends or receives its messages on the operation's connection, without correlating them with a request, and does not open a reply on a channel at another address or sent to an address a runtime expression gives
security requirements AsyncAPI 2.0 ⚠️ Partial The security of a server or an operation, its own or a trait's; the client sends httpApiKey, http, oauth2 and openIdConnect credentials on a handshake, and needs every server of a channel to require the same

✅ Implemented data types and features

Implemented Data Types and Formats

The schema type, format, and default Pydantic v2 type columns below are generated from the parser's schema format registry and the default Pydantic v2 type mapping; keyword and note columns document supplemental schema details.

Schema Data Types

Schema Type Default Pydantic v2 Type Supported Keywords
integer int maximum, exclusiveMaximum, minimum, exclusiveMinimum, multipleOf
number float maximum, exclusiveMaximum, minimum, exclusiveMinimum, multipleOf
string str pattern, minLength, maxLength
boolean bool -
object Dict[str, Any] properties, required, additionalProperties, patternProperties
null None -
array List[Any] items, prefixItems, minItems, maxItems, uniqueItems

Common Formats (JSON Schema + OpenAPI)

Schema Type Format Default Pydantic v2 Type Notes
integer default (no format) int -
integer int32 int -
integer int64 int -
integer date-time AwareDatetime -
integer unix-time int -
integer unixtime int -
number default (no format) float -
number float float -
number double float -
number decimal Decimal -
number date-time AwareDatetime -
number time time -
number time-delta timedelta -
number unixtime int -
string default (no format) str -
string byte Base64Str Base64 encoded string
string date date -
string date-time AwareDatetime -
string timestamp with time zone AwareDatetime -
string date-time-local NaiveDatetime -
string duration timedelta -
string time time -
string time-local time -
string path Path -
string email EmailStr Requires email-validator
string idn-email EmailStr Requires email-validator
string idn-hostname str -
string iri str -
string iri-reference str -
string uuid UUID -
string uuid1 UUID1 -
string uuid2 UUID -
string uuid3 UUID3 -
string uuid4 UUID4 -
string uuid5 UUID5 -
string uri AnyUrl -
string uri-reference str -
string uri-template str -
string json-pointer str -
string relative-json-pointer str -
string regex str -
string hostname str -
string ipv4 IPv4Address -
string ipv4-network IPv4Network -
string ipv6 IPv6Address -
string ipv6-network IPv6Network -
string decimal Decimal -
string integer int -
string unixtime int -
string ulid ULID Requires python-ulid
boolean default (no format) bool -
object default (no format) Dict[str, Any] -
null default (no format) None -
array default (no format) List[Any] -

OpenAPI-Only Formats

Schema Type Format Default Pydantic v2 Type Notes
string binary bytes File content
string password SecretStr -

🔗 Other schema

  • enum (as enum.Enum or typing.Literal)
  • allOf (as Multiple inheritance)
  • anyOf (as typing.Union)
  • oneOf (as typing.Union)
  • $ref (http extra is required when resolving $ref for remote files.)
  • $id (for JSONSchema)