apischema

JSON (de)serialization, GraphQL and JSON schema generation using Python typing. apischema makes API data handling easier by staying close to the standard library (dataclasses, typing) without requiring base classes, enabling support for any types including ORM models, NewTypes, and generics.

Package Information

• Package Name: apischema
• Language: Python
• Installation: pip install apischema
• Python Support: 3.9+
• Optional Dependencies: pip install apischema[graphql] for GraphQL support

Core Imports

from apischema import deserialize, serialize, ValidationError

For schema generation:

from apischema.json_schema import deserialization_schema, serialization_schema
from apischema.graphql import graphql_schema  # Requires graphql-core

For advanced features:

from apischema import schema, validator, deserializer, serializer
from apischema import alias, discriminator, settings

Basic Usage

from dataclasses import dataclass, field
from uuid import UUID, uuid4
from apischema import deserialize, serialize, ValidationError

# Define schema with standard dataclasses
@dataclass
class Resource:
    id: UUID
    name: str
    tags: set[str] = field(default_factory=set)

# Deserialize JSON data to typed objects
uuid_val = uuid4()
data = {"id": str(uuid_val), "name": "example", "tags": ["tag1", "tag2"]}
resource = deserialize(Resource, data)
print(resource)  # Resource(id=UUID('...'), name='example', tags={'tag1', 'tag2'})

# Serialize objects to JSON-compatible data
result = serialize(Resource, resource)
print(result)  # {'id': '...', 'name': 'example', 'tags': ['tag1', 'tag2']}

# Validation errors provide detailed location information
try:
    deserialize(Resource, {"id": "invalid-uuid", "name": "test"})
except ValidationError as err:
    print(err.errors)  # [{"loc": ["id"], "err": "badly formed hexadecimal UUID string"}]

Architecture

apischema follows a conversion-based architecture that separates data transformation from object creation:

• Serialization/Deserialization: Core functions that convert between Python objects and JSON-like data
• Schema Generation: Unified system for JSON Schema and GraphQL schema generation from Python types
• Conversion System: Extensible type conversion framework for custom serialization logic
• Metadata System: Rich field and type metadata for controlling behavior without inheritance
• Validation Framework: Structured validation with detailed error reporting and location tracking

This design enables apischema to work with any Python types (dataclasses, NamedTuples, NewTypes, ORM models) without requiring base classes or modification of existing code.

Capabilities

Serialization and Deserialization

Core functionality for converting between Python objects and JSON-compatible data structures. Supports dataclasses, standard types, and custom objects with extensive configuration options.

def deserialize(type: AnyType, data: Any, **options) -> Any: ...
def serialize(type: AnyType, obj: Any, **options) -> Any: ...

Serialization and Deserialization

Schema Generation

Generate JSON Schema and GraphQL schemas directly from Python types. Supports all JSON Schema versions and provides comprehensive GraphQL schema generation with built-in types and decorators.

def deserialization_schema(tp: AnyType, **options) -> Dict[str, Any]: ...
def serialization_schema(tp: AnyType, **options) -> Dict[str, Any]: ...
def graphql_schema(query=None, mutation=None, subscription=None, **options) -> GraphQLSchema: ...

Schema Generation

Validation System

Comprehensive validation framework with structured error reporting. Supports field-level validators, custom validation functions, and detailed error location tracking.

class ValidationError(Exception): ...
def validator(func=None, **options) -> Callable: ...
def validate(obj, validators=None, **options): ...

Validation

Type Conversions

Extensible conversion system for custom serialization and deserialization logic. Register converters for any types including third-party libraries and ORM models.

def deserializer(func=None, **options) -> Callable: ...
def serializer(func=None, **options) -> Callable: ...

Type Conversions

Field Metadata and Configuration

Rich metadata system for controlling field behavior without modifying class definitions. Supports aliasing, ordering, conditional serialization, and validation attachment.

def alias(alias_: str) -> Metadata: ...
def schema(**constraints) -> Schema: ...
def discriminator(alias: str, mapping) -> Discriminator: ...
def order(value: int) -> Ordering: ...

Metadata and Configuration

Advanced Features

Advanced functionality including field set tracking, dependency management, recursive type handling, and global settings configuration.

def with_fields_set(cls) -> Callable: ...
def dependent_required(fields, **options) -> Callable: ...
def type_name(ref=None, **options) -> TypeNameFactory: ...

Advanced Features