Add schema format guide tables

docs/supported-data-types.md

@@ -19,6 +19,175 @@ 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
+
+<!-- BEGIN AUTO-GENERATED 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` | Fallback when text cannot parse as YAML |
+| 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 |
+<!-- END AUTO-GENERATED INPUT FORMAT GUIDE -->
+
 ## 📘 OpenAPI 3 and JSON Schema {#openapi-3-and-json-schema}
 
 Below are the data types and features recognized by datamodel-code-generator for OpenAPI 3 and JSON Schema.

docs/supported_formats.md

@@ -6,6 +6,175 @@ This document describes the JSON Schema, OpenAPI, AsyncAPI, Apache Avro, XML Sch
 
 datamodel-code-generator supports multiple schema formats including JSON Schema, OpenAPI, AsyncAPI, Apache Avro, XML Schema, and Protocol Buffers. By default, the tool operates in **Lenient mode**, accepting all features regardless of version declarations for formats that carry version information. This ensures maximum compatibility with real-world schemas that often mix features from different versions.
 
+## Input Format Guide
+
+<!-- BEGIN AUTO-GENERATED 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` | Fallback when text cannot parse as YAML |
+| 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 |
+<!-- END AUTO-GENERATED INPUT FORMAT GUIDE -->
+
 ## JSON Schema Version Support
 
 ### Supported Versions