Python JSONSchema Objects

Common errors

• ValidationError: -2 is less than 0

  cause Attempting to assign a value that violates a `minimum` constraint defined in the JSON Schema.
  fix Ensure 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.

  cause Attempting to assign an array with more items than allowed by the `maxItems` constraint defined in the JSON Schema.
  fix Provide 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'

  cause 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`.
  fix Ensure 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.

Warnings

• gotcha The `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.
  Fix: Monitor `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.
• gotcha Regular 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).
  Fix: Always 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.
• gotcha By 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.
  Fix: Add `"additionalProperties": false` to any object schemas where you want to strictly control the allowed properties.

Install

• pip install python-jsonschema-objects Install stable version

Imports

• ObjectBuilder
  wrong:

  from python_jsonschema_objects import ObjectBuilder

  correct:

  import python_jsonschema_objects as pjs
  builder = pjs.ObjectBuilder(schema)

  The primary interface is `ObjectBuilder`, typically accessed via the aliased package import `python_jsonschema_objects as pjs`.

Quickstart

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}")