iso-obs-schemas

The authoritative shared schema contract for Reliability Studio by Iso AI. This package defines the Pydantic v2 models that every other part of the system is built against:

• the Python SDK (iso_obs) emits traces shaped by these models,
• the API (apps/api) validates and persists them,
• the web app (apps/web) code-generates its TypeScript types from the JSON Schema exported here.

If a shape changes here, it changes everywhere. Treat this package as the single source of truth and change it deliberately.

• PyPI name: iso-obs-schemas
• Import name: iso_obs_schemas
• Python: >=3.12

Install

pip install iso-obs-schemas
# for development (tests):
pip install "iso-obs-schemas[dev]"

What's inside

from iso_obs_schemas import Run, BaseEvent, RunStatus, generate_id, IdPrefix

run = Run(
    id=generate_id(IdPrefix.RUN),
    workspace_id=generate_id(IdPrefix.WORKSPACE),
    project_id=generate_id(IdPrefix.PROJECT),
    suite_execution_id=generate_id(IdPrefix.EVALUATION_SUITE),
    system_version_id=generate_id(IdPrefix.SYSTEM_VERSION),
    environment_version_id=generate_id(IdPrefix.ENVIRONMENT_VERSION),
    scenario_version_id=generate_id(IdPrefix.SCENARIO_VERSION),
    seed=7,
    status=RunStatus.COMPLETED,
)

Typed id conventions

Every persistent object carries a typed, prefixed string id (e.g. run_9f8c2a...). The prefix names the object kind, so ids are self-describing in logs, traces, and URLs, and the API can reject a mismatched id at the edge. The prefix set is closed — adding a kind means adding an IdPrefix member and a matching validated alias in ids.py.

The id aliases are validated: assigning a ws_... id to a field typed as a ProjectId raises a ValidationError.

Exporting JSON Schema

The web app codegen consumes JSON Schema for the public models. Regenerate it into schemas/json/ with:

python -m scripts.export_json_schema

Tests

pytest