Skip to content

Add schema_features property to parsers for version detection #2929

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
koxudaxi merged 20 commits into from
Jan 6, 2026
Merged

Add schema_features property to parsers for version detection #2929

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
20 commits
Select commit Hold shift + click to select a range
811cf13
Add schema_features property to parsers for version detection
koxudaxi Jan 5, 2026
68ffafa
Add version-specific schema processing using schema_features (#2934)
koxudaxi Jan 6, 2026
e31aa17
docs: update llms.txt files
github-actions[bot] Jan 6, 2026
d382f26
docs: update CLI reference documentation and prompt data
github-actions[bot] Jan 6, 2026
eef2db7
Add SchemaFeaturesT generic type parameter to Parser
koxudaxi Jan 6, 2026
21f338f
Fix test snapshot: add exclusive_as_number field
koxudaxi Jan 6, 2026
de56f28
Refactor: genericize _create_default_config using _get_config_class
koxudaxi Jan 6, 2026
2cbbda6
Add parameterized e2e tests for --schema-version and --schema-version…
koxudaxi Jan 6, 2026
b0c5101
docs: update CLI reference documentation and prompt data
github-actions[bot] Jan 6, 2026
c81aaa8
docs: update llms.txt files
github-actions[bot] Jan 6, 2026
943a8f8
Refactor: use _config_class_name class variable instead of method ove…
koxudaxi Jan 6, 2026
17741e1
docs: update CLI reference documentation and prompt data
github-actions[bot] Jan 6, 2026
c83f9c1
docs: update llms.txt files
github-actions[bot] Jan 6, 2026
ed273ba
Add Schema Version Support to docs navigation
koxudaxi Jan 6, 2026
50d8a6c
docs: update llms.txt files
github-actions[bot] Jan 6, 2026
8078f37
Docs: add detailed unsupported features tables
koxudaxi Jan 6, 2026
e93346c
docs: update llms.txt files
github-actions[bot] Jan 6, 2026
da95f2d
Docs: add version info to unsupported features tables
koxudaxi Jan 6, 2026
35bd40f
docs: update llms.txt files
github-actions[bot] Jan 6, 2026
332cccd
Add e2e tests for schema version error handling and strict mode warnings
koxudaxi Jan 6, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
286 changes: 286 additions & 0 deletions docs/cli-reference/base-options.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -10,6 +10,8 @@
| [`--input-model`](#input-model) | Import a Python type or dict schema from a module. |
| [`--input-model-ref-strategy`](#input-model-ref-strategy) | Strategy for referenced types when using --input-model. |
| [`--output`](#output) | Specify the destination path for generated Python code. |
| [`--schema-version`](#schema-version) | Schema version to use for parsing. |
| [`--schema-version-mode`](#schema-version-mode) | Schema version validation mode. |
| [`--url`](#url) | Fetch schema from URL with custom HTTP headers. |

---
Expand Down Expand Up @@ -326,6 +328,290 @@ is written to stdout.

---

## `--schema-version` {#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). Default is 'auto' (detected from $schema or openapi field).

!!! tip "Usage"

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

1. :material-arrow-left: `--schema-version` - the option documented here

??? example "Examples"

=== "OpenAPI"

**Input Schema:**

```yaml
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

=== "JSON Schema"

**Input Schema:**

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

**Output:**

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

from __future__ import annotations

from pydantic import BaseModel


class Model(BaseModel):
s: str
```

---
Comment on lines +331 to +567
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Improve example output and consider simplifying the OpenAPI example.

Issues with the documentation examples:

  1. Error message as output (line 537): The OpenAPI example shows > **Error:** File not found: openapi/api.py as the output, which appears to be a placeholder or incorrect content. This will confuse users.

  2. Verbose OpenAPI example (lines 354-533): The 180-line OpenAPI specification is excessive for demonstrating the --schema-version option. A simpler example would be more effective.

  3. Examples don't demonstrate the option's effect: Neither example clearly shows what happens when you specify --schema-version draft-07 versus auto-detection or a different version. Consider adding examples that highlight version-specific behavior (e.g., using features from different JSON Schema drafts).

📋 Suggested improvements

For the OpenAPI example, either:

  • Replace the error message with actual generated output
  • Use a much simpler OpenAPI spec (e.g., a single endpoint with one schema)

For demonstrating the option's purpose, consider adding an example that shows:

  • A schema using a draft-specific feature (e.g., exclusiveMinimum as boolean in Draft 4 vs. number in Draft 6+)
  • How specifying --schema-version affects the generated output or validation behavior
🤖 Prompt for AI Agents 
In @docs/cli-reference/base-options.md around lines 331 - 567, Summary: The
OpenAPI example is overly verbose and contains a bogus error output, and neither
example demonstrates how --schema-version affects generation. Fix: replace the
large OpenAPI YAML under the "OpenAPI" example with a minimal single-endpoint
spec (keep the section title "OpenAPI") and provide actual generated output
instead of `> **Error:** File not found: openapi/api.py`; shorten or remove the
180-line spec in the diff and ensure the Usage snippet still shows the
datamodel-codegen invocation with --schema-version; add a small JSON Schema
example that uses a draft-specific feature (e.g., exclusiveMinimum as boolean vs
numeric) and include two short generated outputs labeled for draft-04 and
draft-07 to illustrate the effect of the --schema-version option; update the
examples sections ("OpenAPI" and "JSON Schema") to explicitly mention
--schema-version in their captions.


## `--schema-version-mode` {#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.

!!! tip "Usage"

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

1. :material-arrow-left: `--schema-version-mode` - the option documented here

??? example "Examples"

**Input Schema:**

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

**Output:**

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

from __future__ import annotations

from pydantic import BaseModel


class Model(BaseModel):
s: str
```

---
Comment on lines +569 to +613
Copy link
Copy Markdown

@coderabbitai coderabbitai Bot Jan 6, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

⚠️ Potential issue | 🟡 Minor

Add examples demonstrating lenient vs. strict mode behavior.

The current example doesn't illustrate the difference between lenient and strict modes. According to the description (lines 573-575), strict mode should "warn on features outside the declared/detected version," but the example shows identical output for both modes.

Consider adding examples that:

  1. Show a schema using features from a newer version than declared (e.g., prefixItems in a Draft 7 schema)
  2. Demonstrate the warnings generated in strict mode
  3. Show how lenient mode accepts these features without warnings

This will help users understand when and why to use each mode.

🤖 Prompt for AI Agents 
In @docs/cli-reference/base-options.md around lines 569 - 613, Add two example
subsections under the `--schema-version-mode` section demonstrating the
difference between lenient and strict: create a JSON schema that declares
draft-07 but uses a draft-2020+ feature such as "prefixItems"; show the
datamodel-codegen invocation with `--schema-version-mode strict` and note the
expected warning output (mention the warning text or that a warning about
unsupported "prefixItems" or version mismatch appears), then show the invocation
with `--schema-version-mode lenient` and state that generation proceeds without
warnings and produces the same model; reference `--schema-version-mode`,
`strict`, `lenient`, and `prefixItems` so readers can locate the related option
and feature in the docs.


## `--url` {#url}

Fetch schema from URL with custom HTTP headers.
Expand Down
4 changes: 3 additions & 1 deletion docs/cli-reference/index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,7 @@ This documentation is auto-generated from test cases.

| Category | Options | Description |
|----------|---------|-------------|
| 📁 [Base Options](base-options.md) | 7 | Input/output configuration |
| 📁 [Base Options](base-options.md) | 9 | Input/output configuration |
| 🔧 [Typing Customization](typing-customization.md) | 27 | Type annotation and import behavior |
| 🏷️ [Field Customization](field-customization.md) | 24 | Field naming and docstring behavior |
| 🏗️ [Model Customization](model-customization.md) | 39 | Model generation behavior |
Expand Down Expand Up @@ -161,6 +161,8 @@ This documentation is auto-generated from test cases.

### S {#s}

- [`--schema-version`](base-options.md#schema-version)
- [`--schema-version-mode`](base-options.md#schema-version-mode)
- [`--set-default-enum-member`](field-customization.md#set-default-enum-member)
- [`--shared-module-name`](general-options.md#shared-module-name)
- [`--skip-root-model`](model-customization.md#skip-root-model)
Expand Down
4 changes: 4 additions & 0 deletions docs/cli-reference/quick-reference.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,6 +22,8 @@ datamodel-codegen [OPTIONS]
| [`--input-model`](base-options.md#input-model) | Import a Python type or dict schema from a module. |
| [`--input-model-ref-strategy`](base-options.md#input-model-ref-strategy) | Strategy for referenced types when using --input-model. |
| [`--output`](base-options.md#output) | Specify the destination path for generated Python code. |
| [`--schema-version`](base-options.md#schema-version) | Schema version to use for parsing. |
| [`--schema-version-mode`](base-options.md#schema-version-mode) | Schema version validation mode. |
| [`--url`](base-options.md#url) | Fetch schema from URL with custom HTTP headers. |

### 🔧 Typing Customization
Expand Down Expand Up @@ -299,6 +301,8 @@ All options sorted alphabetically:
- [`--remove-special-field-name-prefix`](field-customization.md#remove-special-field-name-prefix) - Remove the special prefix from field names.
- [`--reuse-model`](model-customization.md#reuse-model) - Reuse identical model definitions instead of generating dupl...
- [`--reuse-scope`](model-customization.md#reuse-scope) - Scope for model reuse detection (root or tree).
- [`--schema-version`](base-options.md#schema-version) - Schema version to use for parsing.
- [`--schema-version-mode`](base-options.md#schema-version-mode) - Schema version validation mode.
- [`--set-default-enum-member`](field-customization.md#set-default-enum-member) - Set the first enum member as the default value for enum fiel...
- [`--shared-module-name`](general-options.md#shared-module-name) - Customize the name of the shared module for deduplicated mod...
- [`--skip-root-model`](model-customization.md#skip-root-model) - Skip generation of root model when schema contains nested de...
Expand Down
Loading
Loading