Registry /
serialization / python-jsonschema-objects
Install & Compatibility
Where this runs
tested against v0.5.7 · 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.910 runs
installs and imports cleanly · install 0.0s · import 0.381s · 22.6MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 2.5s · import 0.354s · 23MB
21MB installed
● package 21MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ObjectBuilder
✓ import python_jsonschema_objects as pjs
builder = pjs.ObjectBuilder(schema)
✗ from python_jsonschema_objects import ObjectBuilder
The primary interface is `ObjectBuilder`, typically accessed via the aliased package import `python_jsonschema_objects as pjs`.
This quickstart demonstrates how to define a JSON Schema, build Python classes from it using `ObjectBuilder`, instantiate a generated class, and observe built-in validation upon property assignment. It also shows how to serialize the object back to JSON.
import python_jsonschema_objects as pjs
import json
schema_str = '''
{
"title": "Example Schema",
"type": "object",
"properties": {
"firstName": {"type": "string"},
"lastName": {"type": "string"},
"age": {"description": "Age in years", "type": "integer", "minimum": 0},
"dogs": {"type": "array", "items": {"type": "string"}, "maxItems": 4}
},
"required": ["firstName", "lastName"]
}
'''
schema = json.loads(schema_str)
builder = pjs.ObjectBuilder(schema)
ns = builder.build_classes()
# Access the generated class by its title
Person = ns.ExampleSchema
# Create an instance and set properties
james = Person(firstName="James", lastName="Bond")
print(f"Created person: {james.firstName} {james.lastName}")
# Properties are validated on assignment
try:
james.age = -2
except pjs.ValidationError as e:
print(f"Validation error: {e.message}")
try:
james.dogs = ["Jasper", "Spot", "Noodles", "Fido", "Dumbo"]
except pjs.ValidationError as e:
print(f"Validation error: {e.message}")
# Serialize the object to JSON
json_output = james.serialize(sort_keys=True)
print(f"Serialized object: {json_output}")
Debug
Known issues
gotchaThe `jsonschema` library, a core dependency, has deprecated `jsonschema.RefResolver` in its v4.0.0+ releases in favor of the `referencing` library. `python-jsonschema-objects` still relies on `jsonschema.RefResolver`. This might lead to compatibility issues or unexpected behavior if a very recent `jsonschema` version is installed alongside `python-jsonschema-objects` or if `RefResolver`'s behavior changes significantly in future `jsonschema` updates.fixMonitor `python-jsonschema-objects` updates for `referencing` library adoption. If issues arise, consider pinning `jsonschema < 4.0.0` in your project's dependencies temporarily, or explicitly handle `$ref` resolution if possible.
affects: All versions depending on `jsonschema < 4.0.0` or `jsonschema >= 4.0.0` where `RefResolver` is deprecated.
gotchaRegular expressions in JSON Schema (and thus in `python-jsonschema-objects`) are interpreted using Python's full regex engine, not just the subset allowed by the JSON Schema specification. This can lead to non-portable schemas or unexpected matches if patterns are not properly anchored with `^` (start) and `$` (end).fixAlways anchor regular expression patterns in your JSON schemas with `^` at the beginning and `$` at the end (e.g., `"pattern": "^[Y|N]$"`) to ensure exact matches and portability.
affects: All versions
gotchaBy default, JSON Schemas often allow additional properties beyond those explicitly defined. If strictness is desired (i.e., disallowing any properties not defined in the schema), you must explicitly set `"additionalProperties": false` in your schema. Otherwise, `python-jsonschema-objects` will allow extra fields when deserializing or validating objects.fixAdd `"additionalProperties": false` to any object schemas where you want to strictly control the allowed properties.
affects: All versions
Errors
Common errors & fixes
ValidationError: -2 is less than 0
Attempting to assign a value that violates a `minimum` constraint defined in the JSON Schema.
fixEnsure that assigned values adhere to all schema constraints, such as `minimum`, `maximum`, `minLength`, `maxLength`, etc. Example: `james.age = 5` instead of `james.age = -2`.
ValidationError: ['Jasper', 'Spot', 'Noodles', 'Fido', 'Dumbo'] has too many elements. Wanted 4.
Attempting to assign an array with more items than allowed by the `maxItems` constraint defined in the JSON Schema.
fixProvide an array with a number of elements within the bounds specified by `minItems` and `maxItems`. Example: `james.dogs = ['Jasper', 'Spot']`.
AttributeError: 'Namespace' object has no attribute 'MySchema'
The generated class for your schema could not be found in the `Namespace` object returned by `builder.build_classes()`. This often happens if the schema's `title` field doesn't match the expected attribute name, or if `named_only=True` was used without a `title`.
fixEnsure your schema has a `"title"` property (e.g., `"title": "MySchema"`) and access the generated class using `ns.MySchema`. Alternatively, iterate through `ns.__dict__` to see available generated classes.
Upgrade
Version history
0.5.7latest on PyPI · released Nov 13, 2024
Audit
Dependencies
jsonschemarequiredUsed internally for schema resolution and validation, specifically `jsonschema.RefResolver` and `jsonschema.exceptions.ValidationError`.
Resources
No resource links recorded.