Validating external responses with existing schemas

RelPrim has supported result validation since 0.5.0, but validation previously required a callable written specifically for the application.

Version 0.11.0 adds optional adapters for two common validation systems: JSON Schema and Pydantic v2.

Both adapters plug into the existing RelPrim validation pipeline. There is no separate execution path and no new retry or fallback mechanism.

JSON Schema

Install the optional integration:

pip install "relprim[jsonschema]"

Define a schema and create a validator:

from relprim import validation_policy
from relprim.jsonschema import json_schema_validator


schema = {
    "type": "object",
    "required": ["id", "name"],
    "properties": {
        "id": {"type": "integer"},
        "name": {"type": "string"},
    },
}

validation = validation_policy(
    json_schema_validator(schema)
)

The adapter uses the jsonschema package’s native draft discovery. When a schema declares $schema, the corresponding validator is selected.

Schemas are also checked when the adapter is created, so an invalid schema is treated as configuration failure rather than invalid provider data.

Pydantic

Pydantic v2 support is available separately:

pip install "relprim[pydantic]"

A normal model can be used as a RelPrim validator:

from pydantic import BaseModel

from relprim import validation_policy
from relprim.pydantic import pydantic_validator


class ProviderResponse(BaseModel):
    id: int
    name: str


validation = validation_policy(
    pydantic_validator(ProviderResponse)
)

The adapter calls Pydantic’s model_validate() but does not replace the operation result with the temporary model.

RelPrim validation remains validation rather than transformation.

Existing reliability behavior

Because both integrations implement the same validator abstraction as existing callable validators, they automatically participate in the rest of RelPrim.

A validation failure can:

  • trigger another attempt when configured as retryable;
  • proceed to a fallback provider;
  • appear in execution-report metadata;
  • emit structured validation events.

The adapters do not duplicate any of those behaviors.

Useful diagnostics

JSON Schema failures include a concise validation message and the relevant instance path.

Pydantic failures expose the first validation message together with its field location and error type, plus the number of additional errors when applicable.

Large raw inputs and Pydantic documentation URLs are intentionally excluded from these messages.

Optional dependencies

Neither integration is part of the RelPrim core dependency set.

Applications that do not use JSON Schema or Pydantic do not install or import them.

This keeps the base library lightweight while allowing applications to reuse validation systems they already depend on.

Toward 1.0

RelPrim’s currently planned feature additions are now complete.

The next milestone is focused on hardening the existing API, improving typing and consistency, resolving the remaining pre-1.0 issues and freezing the public surface for the first stable release.