spanforge.validate

JSON Schema validation for Event envelopes.

Validates Event instances against the published JSON Schema. Schema version is selected automatically from the event's schema_version field:

• "1.0" → schemas/v1.0/schema.json
• "2.0" (default) → schemas/v2.0/schema.json

When the optional jsonschema package is installed, full Draft 2020-12 validation is performed. Otherwise a stdlib-only structural check covers all required fields, types, and regex patterns.

Install for full validation:

pip install "spanforge[jsonschema]"

Module-level functions

validate_event(event: Event) -> None

Validate event against the published JSON Schema.

The schema version is read from event.schema_version and the matching schema file is selected automatically (RFC §15.5).

Args:

Raises:

• SchemaValidationError — if the event does not conform to the envelope schema.
• FileNotFoundError — if the matching schema file is missing from the distribution.
• TypeError — if event is not an Event instance.

Example:

from spanforge import Event, EventType
from spanforge.validate import validate_event

event = Event(
    event_type=EventType.TRACE_SPAN_COMPLETED,
    source="llm-trace@0.3.1",
    payload={"span_name": "run", "status": "ok"},
)
validate_event(event)  # passes silently

load_schema(version: Optional[str] = None) -> Dict[str, Any]

Load and cache a JSON Schema from disk by version.

The schema is loaded once per version key and cached in memory. If version is None, the current default ("2.0") is used. Unknown versions raise ValueError.

Args:

Returns: Dict[str, Any] — parsed JSON Schema as a plain Python dict.

Raises:

• FileNotFoundError — if the schema file cannot be found relative to the package root.
• ValueError — if an unknown schema version is requested.

Example:

from spanforge.validate import load_schema

schema_v2 = load_schema()        # loads schemas/v2.0/schema.json
schema_v1 = load_schema("1.0")   # loads schemas/v1.0/schema.json

Validation rules