GrandSchemaThings

GitHub | PyPI

The GrandSchemaThings Python package provides automatic loading and saving of JSON for Python objects, with validation against an automatically-generated schema. It is designed to make it easy to serialize and deserialize objects to and from JSON.

Why use GrandSchemaThings?

Compared to a simple dataclasses.asdict() approach, GrandSchemaThings:

• Reconstructs typed dataclass objects from JSON
• Automatically generates a matching JSON Schema
• Validates incoming data against that schema
• Recursively handles nested objects when deserialising as well as serialising (such as enums, lists, dictionaries, and other GrandSchemaThings objects)

What types does GrandSchemaThings support?

Supported field types are:

• int, str, float and bool
• Enum
• list[T]
• dict[str, T] and dict[Enum, T]
• nested GrandSchemaThings subclasses

The following constraints are enforced:

• GrandSchemaThings follows a strict, fully explicit JSON model: all dataclass fields must have fully concrete, non-nullable types
  • So, Optional[T], T | None, and other Union types are intentionally disallowed
  • Dataclass field defaults are permitted as a Python-side convenience, but are still marked as required in generated JSON schemas
• tuple and set are not supported because they do not have a JSON equivalent
• Enums are serialised using their name (for example, in the example below, Hobby.READING becomes "READING", not "reading") and are represented in the schema as JSON Schema enums

User Guide

System Requirements

• Python >= 3.13

Installation

Install from PyPI using pip:

pip install grandschemathings

Or, if you use uv or Poetry:

uv add grandschemathings
poetry add grandschemathings

Usage

Simple Usage Example

Here's a simple example to illustrate how you can use GrandSchemaThings to serialize and deserialize an object.

from dataclasses import dataclass
from pathlib import Path

from grandschemathings import GrandSchemaThings


@dataclass
class Person(GrandSchemaThings):
    name: str
    age: int


# Create an instance
data = Person(name="Alice", age=30)

# Serialize to JSON file
data.to_file(Path("data.json"), pretty=True)

# Deserialize from JSON file
loaded_data = Person.from_file(Path("data.json"))
print(loaded_data)

Complex Usage Example

This demonstrates how to handle nested objects and dictionaries with enum keys.

from dataclasses import dataclass
from enum import Enum
from pathlib import Path

from grandschemathings import GrandSchemaThings


class Hobby(Enum):
    READING = "reading"
    CYCLING = "cycling"
    COOKING = "cooking"
    GARDENING = "gardening"


@dataclass
class Address(GrandSchemaThings):
    street: str
    city: str
    postcode: str


@dataclass
class User(GrandSchemaThings):
    name: str
    age: int
    address: Address
    hobbies: dict[Hobby, int]


# Create an instance
user = User(
    name="Robert",
    age=42,
    address=Address(street="28 Alderwick Road", city="London", postcode="SW14 7QJ"),
    hobbies={Hobby.READING: 5, Hobby.CYCLING: 3, Hobby.COOKING: 4, Hobby.GARDENING: 1},
)

# Serialize to JSON file
user.to_file(Path("user.json"), pretty=True)

# Deserialize from JSON file
loaded_user = User.from_file(Path("user.json"))
print(loaded_user)

API Reference

The following instance and class methods are available for GrandSchemaThings objects.

Developer Guide

Development Setup

To modify GrandSchemaThings, you can clone the repository and install the development dependencies using Poetry:

1. Install Poetry: If you haven't already got Poetry installed, follow the instructions on their website.
2. Clone the repository:

   git clone https://github.com/cambridgeconsultants/GrandSchemaThings.git
   cd grandschemathings
   

3. Install dependencies:

   poetry install
   

Running Tests

Run the validation suite:

poetry run validate

License

This project is licensed under the Apache License 2.0. See the LICENSE file for details.