Registry /
serialization / json-schema-to-pydantic
Install & Compatibility
Where this runs
tested against v0.4.11 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.920 runs
installs and imports cleanly · install 0.0s · import 0.519s · 28MB
glibcpy 3.10–3.920 runs
installs and imports cleanly · install 3.2s · import 0.469s · 28MB
26MB installed
● package 26MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
create_model
✓ from json_schema_to_pydantic import create_model
This quickstart demonstrates how to define a basic JSON Schema and use `create_model` to generate a Pydantic v2 model. It then shows how to instantiate and use the generated model for data validation and serialization.
from json_schema_to_pydantic import create_model
# Define your JSON Schema
schema = {
"title": "User",
"type": "object",
"properties": {
"name": {"type": "string"},
"email": {"type": "string", "format": "email"},
"age": {"type": "integer", "minimum": 0}
},
"required": ["name", "email"]
}
# Generate your Pydantic model
UserModel = create_model(schema)
# Use the model
user_data = {"name": "John Doe", "email": "john@example.com", "age": 30}
user = UserModel(**user_data)
print(user.model_dump_json(indent=2))
# Expected output (approx):
# {
# "name": "John Doe",
# "email": "john@example.com",
# "age": 30
# }
json-schema-to-pydantic --version
Debug
Known issues
breakingThis library is designed exclusively for Pydantic v2 and is not compatible with Pydantic v1 models or schemas. Attempting to use it with Pydantic v1 environments or schemas may lead to unexpected errors.fixEnsure Pydantic v2 (or higher) is installed in your environment. If you are locked into Pydantic v1, consider using 'datamodel-code-generator' or manually creating Pydantic v1 models.
affects: <0.4.5 (Pydantic <3.9 required), All versions (Pydantic v1)
gotchaJSON Schema fields starting with underscores (e.g., `_links`, `_embedded`) are common in OpenAPI specifications but are not valid Pydantic field names. By default, these fields might be dropped or cause issues.fixFor versions 0.4.9 and later, pass `populate_by_name=True` to `create_model` to automatically sanitize these field names and create aliases, allowing population by the original name. Example: `UserModel = create_model(schema, populate_by_name=True)`.
affects: <0.4.9 (fields dropped/errors), >=0.4.9 (requires parameter)
gotchaIf your JSON Schema defines a top-level array or scalar type (not an object), directly mapping it to a `BaseModel` might not work as expected in Pydantic v2 without `RootModel`.fixVersions 0.4.7 and later support top-level array schemas using Pydantic's `RootModel`. Ensure you are on a compatible version. The library handles this automatically for you.
affects: <0.4.7
gotchaSchemas with `oneOf` combiners, especially for simple types or references, can lead to incorrect type discrimination or validation issues in older versions.fixUpgrade to version 0.4.8 or later, which includes fixes for `oneOf` handling. Thoroughly test schemas with complex `oneOf` structures after upgrading.
affects: <0.4.8
gotchaWhen converting loosely defined JSON schemas (e.g., arrays without `items` schema or fields without a `type`), the generated Pydantic models might be too strict or fail during creation.fixUse the `allow_undefined_array_items=True` and/or `allow_undefined_type=True` parameters in `create_model` to relax validation and allow `Any` for such fields. Example: `RelaxedModel = create_model(schema, allow_undefined_array_items=True, allow_undefined_type=True)`.
affects: All versions
Errors
Common errors & fixes
ModuleNotFoundError: No module named 'json_schema_to_pydantic'
The 'json-schema-to-pydantic' library is not installed in the current Python environment.
fixpip install json-schema-to-pydantic
ImportError: cannot import name 'from_json_schema' from 'json_schema_to_pydantic'
The 'from_json_schema' method is a class method of 'JsonSchemaToPydantic', not a top-level function directly importable from the package root.
fixfrom json_schema_to_pydantic.main import JsonSchemaToPydantic
jsonschema.exceptions.ValidationError: 'properties' is a required property
The provided JSON schema is malformed or invalid according to the JSON Schema specification, failing internal validation checks performed by the 'jsonschema' library.
fixCorrect the JSON schema definition to adhere to the JSON Schema specification, ensuring all required properties and valid structures are present.
jsonschema.exceptions.RefResolutionError: Unresolvable JSON pointer: '...'
A '$ref' field in the JSON schema points to a definition that cannot be found or resolved, either due to a non-existent internal path or an unreachable external URI.
fixEnsure all '$ref' pointers correctly target existing definitions within the schema or at accessible external URLs/files.
Upgrade
Version history
0.4.11latest on PyPI · released Mar 9, 2026
Audit
Dependencies
pydanticrequiredThe library generates models for Pydantic v2. Requires Pydantic >=2.0.