JsonSerde

Type-safe JSON serialization framework integrated with the JAM codec system.

Core Components

JsonCodec

Core serialization engine that handles type-safe conversion between JAM types and JSON:

• Type inference and validation

• Primitive type conversion

• Container type handling

• Dataclass support

• Custom type conversion

JsonSerde

Base mixin for adding JSON capabilities to classes:

• to_json() for serialization

• from_json() for deserialization

• Field metadata support

• Inheritance-based usage

Decorators

• @json_serializable: Add JSON capabilities to classes

• @json_field: Configure field serialization

• @with_json_metadata: Bulk field configuration

Type Resolution

Primitive Types

• bool -> true/false

• int -> number

• str -> string

• bytes -> hex string

• Null -> null

Container Types

• Array[T] -> [T, …]

• Vector[T] -> [T, …]

• Dict[K,V] -> {K: V, …}

• Option[T] -> T | null

• Enum -> value | name

Custom Types

• @json_serializable -> object

• JsonSerde -> custom conversion

Error Handling

• JsonSerializationError: Base serialization error

• JsonDeserializationError: Base deserialization error

• JsonFieldError: Field-specific errors

Usage Examples

Basic Usage

from dataclasses import dataclass
from jam.utils.json import json_serializable, json_field

@json_serializable
@dataclass
class Point:
    x: int
    y: int = json_field(name="yCoord")

point = Point(1, 2)
data = point.to_json()  # -> {"x": 1, "yCoord": 2}
decoded = Point.from_json(data)  # -> Point(x=1, y=2)

Field Customization

@json_serializable
@dataclass
class Document:
    id: str
    tags: list[str] = json_field(skip_if_none=True)
    metadata: dict = json_field(name="meta")

doc = Document("123", ["a", "b"], {"key": "value"})
# -> {
#     "id": "123",
#     "tags": ["a", "b"],
#     "meta": {"key": "value"}
# }

Error Handling

try:
    Point.from_json({"x": "not_a_number", "y": 2})
except JsonFieldError as e:
    print(e)  # Field 'x' (int): Expected int, got str

Submodules

• jam.utils.json.codec
  • Type Resolution
  • Implementation Details
  • Error Handling
  • API Reference
  • Examples
• jam.utils.json.serde
  • Core Components
  • Implementation Details
  • Error Handling
  • API Reference
  • Examples
• jam.utils.json.decorators module
  • Core Decorators
  • Implementation Details
  • Error Cases
  • API Reference
  • Examples

Module Contents

JSON serialization framework integrated with JAM codec system.

Core: * JsonCodec: Type-safe conversion engine * JsonSerde: Base mixin for JSON capabilities * JsonFieldMetadata: Field configuration

Type Resolution: * bool -> true/false * int -> number * str -> string * bytes -> hex string * Null -> null * Array[T] -> [T, …] * Vector[T] -> [T, …] * Dict[K,V] -> {K: V, …} * Option[T] -> T | null * Enum -> value | name * @json_serializable -> object * JsonSerde -> custom conversion

class jam.utils.json.JsonSerde

Bases: object

Base mixin for JSON serialization.

to_json() → Any

Convert to JSON-compatible value.

classmethod from_json(data: Any) → T

Create from JSON-compatible value.

classmethod __json_metadata__() → Dict[str, JsonFieldMetadata]

Get JSON metadata for fields.

class jam.utils.json.JsonCodec

Bases: object

Core JSON serialization engine.

static to_json(obj: Any) → Any

Convert object to JSON-compatible value.

static from_json(data: Any, target_type: Type[T]) → T

Convert JSON-compatible value to target type.

static _get_dataclass_fields(cls: Type) → Dict[str, Any]

Get and cache dataclass field information.

static _dataclass_to_json(obj: Any) → Dict[str, Any]

Convert dataclass instance to JSON dict

static _dataclass_from_json(data: Dict[str, Any], cls: Type[T]) → T

Convert JSON dict to dataclass instance.

jam.utils.json.json_serializable(cls: Type[T]) → Type[T]

Add JSON serialization to a class.

jam.utils.json.json_field(*, name: str | None = None, skip_if_none: bool = False) → Any

Field decorator for JSON customization.

jam.utils.json.json_field_metadata(field_name: str, *, json_name: str | None = None, skip_if_none: bool = False) → Dict[str, Any]

Create metadata for a JSON field.

jam.utils.json.with_json_metadata(**field_metadata: Dict[str, Any])

Add JSON metadata to multiple fields.

exception jam.utils.json.JsonSerializationError

Bases: Exception

Base exception for JSON serialization errors.

exception jam.utils.json.JsonDeserializationError

Bases: Exception

Base exception for JSON deserialization errors.

exception jam.utils.json.JsonFieldError(field_name: str, field_type: Type, message: str)

Bases: JsonSerializationError

Field-specific JSON conversion error.

__init__(field_name: str, field_type: Type, message: str)

class jam.utils.json.JsonFieldMetadata(name: str | None = None, skip_if_none: bool = False, format: str | None = None)

Bases: object

Field customization metadata.

name: str | None = None

skip_if_none: bool = False

format: str | None = None

__init__(name: str | None = None, skip_if_none: bool = False, format: str | None = None) → None