Add version-specific schema processing using schema_features #2934

koxudaxi · 2026-01-05T17:43:57Z

Summary by CodeRabbit

New Features
- Added automatic detection and support for multiple JSON Schema versions (draft-04 through 2020-12) and OpenAPI versions (3.0 and 3.1).
- Enhanced version-aware feature handling for improved cross-version schema compatibility.
Tests
- Added comprehensive test coverage for version detection and schema feature validation.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

coderabbitai · 2026-01-05T17:44:09Z

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

This PR introduces schema versioning support and feature detection for JSON Schema and OpenAPI. It exposes new public enums, adds version detection utilities, and implements version-aware feature flags and data format mappings across parser classes.

Changes

Cohort / File(s)	Summary
Public API exports `src/datamodel_code_generator/__init__.py`	Exposes three new enums (`JsonSchemaVersion`, `OpenAPIVersion`, `VersionMode`) and two lazy-loaded detection functions (`detect_jsonschema_version`, `detect_openapi_version`) to public API.
New enum definitions `src/datamodel_code_generator/enums.py`	Adds three enums for version tracking: `JsonSchemaVersion` (draft-04 through 2020-12 with auto-detection), `OpenAPIVersion` (3.0, 3.1, auto), and `VersionMode` (lenient, strict). Updates `__all__` exports.
JSON Schema parser versioning `src/datamodel_code_generator/parser/jsonschema.py`	Introduces `schema_features` cached property for version-aware behavior. Extends `_get_type` with optional `data_formats` parameter. Refactors type resolution via `_data_formats` property. Adds version-aware schema path handling (`schema_paths`), array item detection (`_get_array_items`), and root ID context resolution.
OpenAPI parser versioning `src/datamodel_code_generator/parser/openapi.py`	Adds `schema_features` cached property deriving OpenAPI-specific features from detected version. Imports `cached_property`, `OpenAPIVersion`, and type-checking import for `OpenAPISchemaFeatures`.
New schema versioning module `src/datamodel_code_generator/parser/schema_version.py`	Creates comprehensive versioning logic: `JsonSchemaFeatures` and `OpenAPISchemaFeatures` dataclasses with feature flags and `from_version()`/`from_openapi_version()` classmethods. Implements version detection (`detect_jsonschema_version`, `detect_openapi_version`). Provides data format mappings via `get_data_formats()` function.
Test coverage `tests/parser/test_schema_version.py`	Comprehensive test suite covering version detection across all JSON Schema drafts, OpenAPI versions, feature flag inheritance, data format mappings, and parser-specific feature detection.
Test fixture cleanup `tests/data/expected/main/openapi/same_name_objects.py`	Removes `Error` and `Resolved` model classes from expected output fixture.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~45 minutes

Possibly related PRs

koxudaxi/datamodel-code-generator#2877: Modifies parser class initialization and configuration handling, which could interact with the new schema-versioning properties added to JsonSchemaParser and OpenAPIParser.

Suggested labels

breaking-change-analyzed

Poem

🐰 A Schema's Tale

Versions hop through drafts and specs,
Four-to-twenty features check!
Features flag the paths we take,
OpenAPI and JSON shake.
Schema speaks in coded tongue—
Version bells have rung! 🔔

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main change: introducing version-specific schema processing capabilities through a new schema_features property/system across multiple parser modules.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

github-actions · 2026-01-05T17:44:39Z

📚 Docs Preview: https://pr-2934.datamodel-code-generator.pages.dev

src/datamodel_code_generator/parser/schema_version.py

+from datamodel_code_generator.enums import JsonSchemaVersion, OpenAPIVersion
+
+if TYPE_CHECKING:
+    from datamodel_code_generator.types import Types


To fix the problem, remove the unused import of Types from datamodel_code_generator.types inside the if TYPE_CHECKING: block. This resolves the static analysis warning without changing any runtime behavior, since if TYPE_CHECKING: blocks are ignored at runtime.

Concretely, in src/datamodel_code_generator/parser/schema_version.py, delete the line from datamodel_code_generator.types import Types that appears under if TYPE_CHECKING:. No other code changes or new imports are needed.

src/datamodel_code_generator/parser/schema_version.py

+    discriminator_support: bool
+
+    @classmethod
+    def from_openapi_version(cls, version: OpenAPIVersion) -> OpenAPISchemaFeatures:


In general, to fix “explicit returns mixed with implicit returns”, ensure that every code path in a function with a non-None return annotation ends with an explicit return, including the fall-through at the end of the function. This avoids any possibility of returning None implicitly.

For OpenAPISchemaFeatures.from_openapi_version, the match currently has case OpenAPIVersion.V30: and a fallback case _: that both return cls(...). To eliminate any potential implicit return, we can simply add a final return after the match that returns a sensible default instance. Because the case _: branch already represents the default behavior, the safest and behavior-preserving change is to construct and return the same values as in the wildcard case at the end of the function. In practice, this return should be unreachable, but it satisfies the analyzer and guarantees the function never returns None, even if the match were later changed in a way that forgets a return.

Concretely, within src/datamodel_code_generator/parser/schema_version.py, after line 123 (the end of the case _: block in from_openapi_version), add an explicit return cls(...) with the same arguments as in the wildcard case. No new imports or additional helpers are needed.

codspeed-hq · 2026-01-05T17:46:50Z

CodSpeed Performance Report

Merging #2934 will not alter performance

_{Comparing feature/version-specific-processing (dd2aef2) with feature/schema-object-refactoring (811cf13)}

⚠️

Unknown Walltime execution environment detected

Using the Walltime instrument on standard Hosted Runners will lead to inconsistent data.

For the most accurate results, we recommend using CodSpeed Macro Runners: bare-metal machines fine-tuned for performance measurement consistency.

Summary

✅ 11 untouched
⏩ 98 skipped¹

98 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

coderabbitai

Actionable comments posted: 0

🧹 Nitpick comments (4)

src/datamodel_code_generator/parser/schema_version.py (1)
190-190: Remove unused noqa directives.

The # noqa: PLC0415 comments on lines 190 and 251 are not needed as the PLC0415 rule is not enabled in your Ruff configuration.
🔎 Proposed fix
-    from datamodel_code_generator.types import Types  # noqa: PLC0415
+    from datamodel_code_generator.types import Types
Apply the same change on line 251.
Also applies to: 251-251
src/datamodel_code_generator/parser/openapi.py (1)
176-176: Remove unused noqa directive.

The # noqa: PLC0415 comment on line 176 is not needed as the PLC0415 rule is not enabled.
🔎 Proposed fix
-        from datamodel_code_generator.parser.schema_version import (  # noqa: PLC0415
+        from datamodel_code_generator.parser.schema_version import (
             OpenAPISchemaFeatures,
             detect_openapi_version,
         )
src/datamodel_code_generator/__init__.py (1)
46-46: LGTM! Clean public API exposure.

The new version enums and detection functions are properly integrated:

Enums imported from enums module

Detection functions configured for lazy loading

All additions included in __all__ exports

The lazy import pattern is consistent with existing entries like generate_dynamic_models.

However, the # noqa: F822 comments on lines 987-989 can be removed as Ruff is not flagging these lines:
🔎 Proposed fix
-    "clear_dynamic_models_cache",  # noqa: F822
-    "detect_jsonschema_version",  # noqa: F822
-    "detect_openapi_version",  # noqa: F822
+    "clear_dynamic_models_cache",
+    "detect_jsonschema_version",
+    "detect_openapi_version",
Also applies to: 50-50, 54-54, 936-937, 974-974, 979-979, 986-986, 988-989
src/datamodel_code_generator/parser/jsonschema.py (1)

929-941: Consider using _get_array_items helper in existing code.

The _get_array_items staticmethod correctly handles version-aware array item resolution (prefixItems vs items), but it's not called anywhere in this file.

Similar logic exists in parse_array_fields (lines 2959-2970) that could potentially be refactored to use this helper for consistency and DRY.

Is this method intended for:

Future refactoring of parse_array_fields?

Use by openapi.py (listed as a dependent)?

Public API for version-aware item handling?

If not actively used yet, consider either integrating it now or adding a TODO comment explaining its intended use.

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between da32bb7 and 2e1b066.

📒 Files selected for processing (7)

src/datamodel_code_generator/__init__.py
src/datamodel_code_generator/enums.py
src/datamodel_code_generator/parser/jsonschema.py
src/datamodel_code_generator/parser/openapi.py
src/datamodel_code_generator/parser/schema_version.py
tests/data/expected/main/openapi/same_name_objects.py
tests/parser/test_schema_version.py

💤 Files with no reviewable changes (1)

tests/data/expected/main/openapi/same_name_objects.py

🧰 Additional context used

🧬 Code graph analysis (6)

tests/parser/test_schema_version.py (2)

src/datamodel_code_generator/enums.py (3)

JsonSchemaVersion (243-254)

OpenAPIVersion (257-265)

VersionMode (268-276)

src/datamodel_code_generator/parser/schema_version.py (7)

JsonSchemaFeatures (20-81)

OpenAPISchemaFeatures (85-123)

detect_jsonschema_version (139-165)

detect_openapi_version (168-182)

from_version (43-81)

from_openapi_version (99-123)

get_data_formats (261-277)

src/datamodel_code_generator/enums.py (1)

src/datamodel_code_generator/model/enum.py (1)

Enum (39-121)

src/datamodel_code_generator/__init__.py (1)

src/datamodel_code_generator/enums.py (3)

JsonSchemaVersion (243-254)

OpenAPIVersion (257-265)

VersionMode (268-276)

src/datamodel_code_generator/parser/openapi.py (2)

src/datamodel_code_generator/enums.py (1)

OpenAPIVersion (257-265)

src/datamodel_code_generator/parser/schema_version.py (3)

OpenAPISchemaFeatures (85-123)

detect_openapi_version (168-182)

from_openapi_version (99-123)

src/datamodel_code_generator/parser/schema_version.py (2)

src/datamodel_code_generator/enums.py (2)

JsonSchemaVersion (243-254)

OpenAPIVersion (257-265)

src/datamodel_code_generator/types.py (1)

Types (955-994)

src/datamodel_code_generator/parser/jsonschema.py (2)

src/datamodel_code_generator/enums.py (1)

JsonSchemaVersion (243-254)

src/datamodel_code_generator/parser/schema_version.py (3)

JsonSchemaFeatures (20-81)

detect_jsonschema_version (139-165)

from_version (43-81)

🪛 Ruff (0.14.10)

src/datamodel_code_generator/__init__.py

987-987: Unused noqa directive (unused: F822)