Schema verifier

Updated in v7.0.0 (breaking). SchemaVerifier.verify() and verify_ucp_transaction() now return a DiagnosticResult instead of an ad-hoc dict. A payload that violates its schema is VERIFIED (the check completed and proved the violation) with developer_fields.is_valid: false — BLOCKED is reserved for schemas the verifier cannot parse or validate. See the changelog for migration details.

The Schema Verifier goes beyond standard JSON validation. It combines Pydantic structure enforcement with Symbolic Math checks deeply embedded within the schema.

How it works

It validates that:

Structure: The output matches the required JSON keys and types.
Logic: The numeric values inside the JSON are mathematically consistent (e.g., total == sum(items)).

The `DiagnosticResult` contract

verify() returns a DiagnosticResult with a status, an agent-safe agent_message, structured developer_fields, and a deterministic proof_ref:

Outcome	`status`	`developer_fields`	`proof_ref`
Payload conforms to the schema	`VERIFIED`	`is_valid: true`, `constraint_id: "schema_verifier.schema_valid"`	Present
Payload violates the schema	`VERIFIED` (as-invalid)	`is_valid: false`, `constraint_id: "schema_verifier.schema_violation"`, `issues`	Present
Schema cannot be parsed	`BLOCKED`	`constraint_id: "schema_verifier.parse_error"`	`null`
Unexpected validation error	`BLOCKED`	`constraint_id: "schema_verifier.validation_error"`	`null`

A schema violation is a completed, proven verdict, so it is VERIFIED — read developer_fields.is_valid for the pass/fail outcome and developer_fields.issues for per-path detail. proof_ref is computed deterministically from a canonical JSON encoding of the schema plus the instance evidence. Unsupported values (non-finite floats such as NaN or ±inf, hostile objects) and cyclic structures fail closed to BLOCKED instead of emitting a proof. Malformed schemas also fail closed: non-dict properties, invalid required entries, invalid numeric constraints, non-finite bounds, and negative size constraints return BLOCKED (schema_verifier.parse_error) instead of being silently treated as empty. agent_message is sanitized — rule IDs, issue types, and schema internals never leak into agent-facing output.

Usage

schema = {
    "type": "object",
    "properties": {
        "items": {"type": "array", "items": {"type": "number"}},
        "total": {"type": "number"}
    },
    # QWED Extension: Math Logic
    "qwed:constraints": [
        "total == sum(items)"
    ]
}

response = client.verify_schema(
    obj={"items": [10, 20], "total": 30},
    schema=schema
)
# -> status: "VERIFIED", developer_fields.is_valid: true

response = client.verify_schema(
    obj={"items": [10, 20], "total": 300}, # LLM hallucinations
    schema=schema
)
# -> status: "VERIFIED", developer_fields.is_valid: false
# -> issue: total (300) != sum(items) (30)

Money arithmetic uses Decimal, not float tolerance — computed-total and tax checks quantize operands to the currency precision and compare exactly, so boundary transactions deterministically pass or fail.

Object validation

The Schema Verifier supports standard JSON Schema object keywords including properties, required, and additionalProperties.

`additionalProperties: false` — strict fail-closed validation

When a schema sets "additionalProperties": false and the verifier runs with strict=True (the default), any property that is not declared in properties causes the payload to fail validation. The verifier records each undeclared property as an ERROR-severity additional_property issue, so developer_fields.is_valid is false. In non-strict mode (strict=False), additionalProperties: false is treated as advisory and undeclared properties do not block validation. Issue types returned for additionalProperties:

Issue type	Severity	Meaning
`additional_property`	`ERROR` (strict)	An undeclared property was present and `additionalProperties` is `false`

Example — strict mode rejects extra fields:

schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"}
    },
    "required": ["name"],
    "additionalProperties": False
}

result = client.verify_schema(
    obj={"name": "rahul", "role": "admin"},
    schema=schema,
    strict=True
)
# -> status: "VERIFIED", developer_fields.is_valid: false
# -> issue type: "additional_property", severity: "ERROR"
# -> message: "Additional property 'role' not allowed"

Example — declared-only payloads pass:

result = client.verify_schema(
    obj={"name": "rahul"},
    schema=schema,
    strict=True
)
# -> status: "VERIFIED", developer_fields.is_valid: true

Example — nested objects also fail closed:

schema = {
    "type": "object",
    "properties": {
        "user": {
            "type": "object",
            "properties": {"name": {"type": "string"}},
            "required": ["name"],
            "additionalProperties": False
        }
    },
    "required": ["user"]
}

result = client.verify_schema(
    obj={"user": {"name": "rahul", "role": "admin"}},
    schema=schema,
    strict=True
)
# -> status: "VERIFIED", developer_fields.is_valid: false
# -> issue path: "$.user.role", type: "additional_property", severity: "ERROR"

Behavior matrix:

Mode	`additionalProperties`	Extra field present	Result
`strict=True`	`false`	yes	`is_valid: false`, issue severity `ERROR`
`strict=True`	`false`	no	`is_valid: true`
`strict=False`	`false`	yes	`is_valid: true` (permissive)

This fail-closed behavior for strict additionalProperties: false was hardened in the v5.1.x line. See the changelog for the release notes.

Array validation

The Schema Verifier supports standard JSON Schema array keywords including uniqueItems.

`uniqueItems` — fail-closed validation

When a schema sets uniqueItems: true, the verifier checks that every element in the array is distinct. If an element is unhashable or otherwise cannot be compared deterministically (for example, an object containing a Python set), the verifier fails closed — it reports a uniqueness_validation_error issue instead of silently passing. This ensures that unverifiable arrays are never treated as valid. Issue types returned for uniqueItems:

Issue type	Meaning
`uniqueness_violation`	Duplicate items were found in the array
`uniqueness_validation_error`	Uniqueness could not be verified deterministically (fail-closed)

Example — duplicate items:

schema = {"type": "array", "uniqueItems": True}

result = client.verify_schema(obj=[1, 2, 2, 3], schema=schema)
# -> developer_fields.is_valid: false, issue type: "uniqueness_violation"

Example — uncheckable items fail closed:

schema = {"type": "array", "uniqueItems": True}

# Items containing unhashable types cannot be compared deterministically
result = client.verify_schema(obj=[{"bad": {1, 2}}, {"bad": {3, 4}}], schema=schema)
# -> developer_fields.is_valid: false
# -> issue type: "uniqueness_validation_error"
# -> message: "uniqueItems could not be verified deterministically: ..."

This fail-closed behavior shipped in v5.1.0. See the changelog for the full release notes.

UCP transaction verification

verify_ucp_transaction() shares the same DiagnosticResult contract and was hardened in v7.0.0:

Complete verdict fields on every path — the result always carries transaction_type, currency, and schema_verifier.ucp_* constraint ids in developer_fields, for both valid and violated verdicts.
Type safety — string or None amount fields and non-dict transactions produce deterministic verdicts instead of raising TypeError or AttributeError.
Exact money arithmetic — computed-total and tax checks use Decimal quantized to the currency precision, removing the previous 0.01 float tolerance.
tax is selected by key presence, not truthiness — a declared tax: 0 is used instead of silently falling back to tax_amount.

When to use

Invoice Processing: Ensure line items sum to the total.
Financial Reports: Ensure balance sheets balance.
Tax Forms: Ensure calculated fields match underlying data.
Strict API contracts: Reject payloads with undeclared fields when strict=True and additionalProperties: false are combined.

Overview

Core Engines

Analysis Engines

Specialized Engines

How it works

The `DiagnosticResult` contract

Usage

Object validation

`additionalProperties: false` — strict fail-closed validation

Array validation

`uniqueItems` — fail-closed validation

UCP transaction verification

When to use

​How it works

​The DiagnosticResult contract

​Usage

​Object validation

​additionalProperties: false — strict fail-closed validation

​Array validation

​uniqueItems — fail-closed validation

​UCP transaction verification

​When to use

How it works

The `DiagnosticResult` contract

Usage

Object validation

`additionalProperties: false` — strict fail-closed validation

Array validation

`uniqueItems` — fail-closed validation

UCP transaction verification

When to use