omni_api

omni_api is a payload adaptation layer for platform teams that need to enforce backend API contracts while supporting heterogeneous upstream producers. Requires Python 3.11+.

Install

pip install omni-api-transformer

Optional with uv:

uv add omni-api-transformer

Quickstart

from omni_api import transform

source_payload = {
    "full_name": "John Doe",
    "age": 30,
    "contact": {"email": "john@example.com"},
    "extra_data": "ignored",
}

target_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "age": {"type": "number"},
        "email": {"type": "string"},
    },
    "required": ["name", "age", "email"],
}

result = transform(source_payload, target_schema)
print(result.payload)
# {'name': 'John Doe', 'age': 30, 'email': 'john@example.com'}

API

transform(source_payload, target_schema)

Inputs:

• source_payload: dict[str, Any]
• target_schema: JSON Schema object subset (type, properties, required)

Returns TransformResult:

• payload: transformed payload restricted to target schema keys
• plan: deterministic transform plan with mapping decisions
• report: mapped/dropped/missing fields and warnings

Raises:

• TransformSchemaError: unsupported schema shape
• TransformValidationError: missing required or invalid output payload

Core Architecture Model

omni_api follows a deterministic two-step model:

1. Compile a Transform Plan from source payload plus target contract.
2. Execute that plan with a pure transformation step.

Core components:

• Router: selects target backend profile/route (future extension)
• Schema Loader: loads canonical backend contract
• Planner: generates deterministic mappings
• Executor: applies mappings, defaults, and drops
• Validator: enforces required fields and output constraints
• Diagnostics: emits structured transformation report

Module Relationship Graph

flowchart LR
  init["__init__.py"] --> api["api.py"]
  api --> planner["planner.py"]
  api --> executor["executor.py"]
  api --> validator["validator.py"]
  api --> errors["errors.py"]
  api --> types["plan_types.py"]
  planner --> types
  executor --> types

Loading

Contracts and Canonical Artifacts

• Backend contracts should be maintained as JSON Schema under schemas/<provider>/<endpoint>.json.
• Transform Plan DSL includes mappings, defaults, drops, required.
• Output keys are constrained to schema-defined keys in strict mode.

Development

Run tests with uv:

cd python
uv run pytest -q

Build package artifacts:

cd python
uv run --with build python -m build

Release

Publishing is automated via GitHub Actions (.github/workflows/ci-publish.yml):

• Push to main runs tests and then attempts PyPI publish
• Publish uses GitHub secret PYPI_API_TOKEN
• Bump python/pyproject.toml version before merge to main to avoid duplicate version failures