Skip to content

Recipes

Each recipe is one task done end to end with a JSON Schema already in hand, and each says what it cannot do. Each block runs as written. What a keyword compiles to is the compiler page's, and where a reading differs from another validator's is the ledger of differences's.

A model's tool call, against the schema it was shown

A model calling a tool writes the arguments as JSON against the inputSchema it was shown, and nothing about the model makes them belong. Compiling that same schema checks them, so the schema is written once: what the model reads and what the call is held to are one document. load parses the arguments and checks them in one call, and its error names each wrong argument, which the server returns to the model as a tool error:

from valgebra import ValidationError
from valgebra_jsonschema import read_tool

GET_WEATHER = {
    "name": "get_weather",
    "description": "The forecast for a city.",
    "inputSchema": {
        "type": "object",
        "properties": {
            "city": {"type": "string", "minLength": 1},
            "unit": {"enum": ["celsius", "fahrenheit"]},
            "days": {"type": "integer", "minimum": 1, "maximum": 7},
        },
        "required": ["city", "unit"],
        "additionalProperties": False,
    },
}
ARGUMENTS = read_tool(GET_WEATHER).arguments


def call(arguments: str) -> dict[str, object]:
    """Answer a `tools/call` of `get_weather`: the forecast, or an error the model reads."""
    try:
        parsed = ARGUMENTS.load(arguments)
    except ValidationError as error:
        return {"content": [{"type": "text", "text": str(error)}], "isError": True}
    return {"content": [{"type": "text", "text": f"{parsed['city']}: sunny"}], "isError": False}


refused = call('{"city": "Turin", "unit": "kelvin", "country": "IT"}')
assert refused["isError"]
assert refused["content"][0]["text"].splitlines() == [
    "2 validation errors:",
    (
        "at unit: expected one of: the literal 'celsius', the literal 'fahrenheit', "
        "got 'kelvin' [union_error]"
    ),
    "at country: expected no unexpected key, got 'country' [extra_forbidden]",
]
assert not call('{"city": "Turin", "unit": "celsius", "days": 3.0}')["isError"]

"days": 3.0 meets "type": "integer": JSON Schema reads a number by its value, and 3.0 is the integer 3, where valgebra's own int refuses it (valgebra's recipe for a tool call writes the schema a second time, as a TypedDict). An argument the tool does not take is refused by additionalProperties: false; a schema without it admits any other key with any value.

It checks, and does not convert. "days": "3" is a string, and the model is told so rather than the value read as a number. format asserts nothing unless asked: read_tool(spec, assert_format=True) reads nine formats as assertions and refuses a schema naming any other (what a tool's schema may hold).

A schema change, checked before release

Whether a new version of a schema breaks its users is a question about two sets, and which one must hold the other turns on who writes the value (Habib et al. 2021). A request is written by an old client and read by the new server, so every old value must be a new one: the old schema lies inside the new. A response is written by the new server and read by an old client, so the new schema must lie inside the old. Two documents can differ where their sets do not, so the check compares the sets, not the text:

from valgebra_jsonschema import compile_schema

ORDER_V1 = {
    "type": "object",
    "properties": {
        "id": {"type": "integer", "minimum": 1},
        "status": {"enum": ["open", "paid"]},
    },
    "required": ["id", "status"],
}
# The same set, its fields written once under `$defs`.
ORDER_V1_DEFS = {
    "$defs": {"id": {"type": "integer", "minimum": 1}, "status": {"enum": ["open", "paid"]}},
    "type": "object",
    "properties": {"id": {"$ref": "#/$defs/id"}, "status": {"$ref": "#/$defs/status"}},
    "required": ["id", "status"],
}
# A status added.
ORDER_V2 = {
    **ORDER_V1,
    "properties": {**ORDER_V1["properties"], "status": {"enum": ["open", "paid", "refunded"]}},
}
# A field required.
ORDER_V3 = {
    **ORDER_V1,
    "properties": {**ORDER_V1["properties"], "currency": {"type": "string"}},
    "required": ["id", "status", "currency"],
}


def check(old: object, new: object, role: str) -> int:
    """Return a CI step's exit status for a change: 0 compatible, 1 a break, 2 undecided."""
    before, after = compile_schema(old), compile_schema(new)
    inner, outer = (before, after) if role == "request" else (after, before)
    return {"subset": 0, "not_subset": 1, "undecided": 2}[inner.relation_to(outer)]


for role in ("request", "response"):
    assert check(ORDER_V1, ORDER_V1_DEFS, role) == 0
assert check(ORDER_V1, ORDER_V2, "request") == 0
assert check(ORDER_V1, ORDER_V2, "response") == 1  # an old client refuses "refunded"
assert check(ORDER_V1, ORDER_V3, "request") == 1  # an old client sends no currency
assert check(ORDER_V1, ORDER_V3, "response") == 0
assert check({"type": "array"}, {"type": "array", "uniqueItems": True}, "request") == 2

ORDER_V3 holds as a response because the first version is open: it admits a currency of any value already, so every new response is one an old client reads.

Undecided is not compatible. uniqueItems is an opaque keyword, exact on membership, and a relation that looks inside one answers undecided: [1, 1] is an array outside the second schema, and the relation does not refute the request. The exit status keeps the two apart, so a gate passing on 0 alone passes no change it could not decide; a test asserting a compatibility compares with "subset", never with != "not_subset". A proof is about the schemas, not about data stored under the old one, which valgebra's recipe for stored data reads row by row.

A schema split across documents

A $ref may name another document by its URI. Nothing is fetched: each document a reference may name is passed in documents, keyed by the URI the reference resolves to, and a reference to any other is refused when the schema compiles, never when a value is checked:

from valgebra_jsonschema import Unsupported, compile_schema

ADDRESS = {
    "$id": "https://example.com/schemas/address.json",
    "type": "object",
    "properties": {
        "street": {"type": "string"},
        "country": {"type": "string", "pattern": "^[A-Z]{2}$"},
    },
    "required": ["street", "country"],
}
CUSTOMER = {
    "$id": "https://example.com/schemas/customer.json",
    "type": "object",
    "properties": {"name": {"type": "string"}, "shipping": {"$ref": "address.json"}},
    "required": ["name"],
}

customers = compile_schema(CUSTOMER, documents={ADDRESS["$id"]: ADDRESS})
assert customers.is_valid({"name": "Ada", "shipping": {"street": "Via Roma 1", "country": "IT"}})
assert not customers.is_valid(
    {"name": "Ada", "shipping": {"street": "Via Roma 1", "country": "Italy"}}
)

refused = False
try:
    compile_schema(CUSTOMER)
except Unsupported as error:
    refused = True
    assert str(error) == "$ref 'address.json' names a document this one does not hold"
assert refused

address.json resolves against the customer schema's $id to the address schema's. Documents kept as files are read the same way: each file parsed, keyed by its $id, or, where it declares none, by the URI the references name it by. A supplied document declaring no $schema is read in the compiled document's dialect.

A document on the network is the caller's to fetch. A schema naming one by an https URI compiles only once the caller has fetched the document and passed it, so which hosts to trust is the caller's decision; a tool's schema reads the protocol's rule against dereferencing a network reference the same way (what a tool's schema may hold). A URI two schema objects of one document claim is refused where a reference names it (the inventory).

Files checked against a schema

A directory of JSON files, configurations or fixtures, is checked against one schema file by file. validate_json parses each file's bytes and checks the value in one call, building no error for a file that belongs, and each failure carries the path to the wrong value and a code:

from valgebra import ValidationError
from valgebra_jsonschema import compile_schema

SERVICE = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "minLength": 1},
        "release": {"type": "string", "format": "date"},
        "port": {"type": "integer", "minimum": 1, "maximum": 65535},
    },
    "required": ["name", "release"],
    "additionalProperties": False,
}
SERVICES = compile_schema(SERVICE, assert_format=True)


def problems(text: bytes) -> list[tuple[tuple[object, ...], str]]:
    """Return the path and the code of each reason the schema refuses a file's bytes."""
    try:
        SERVICES.validate_json(text)
    except ValidationError as error:
        return [(item["path"], item["code"]) for item in error.errors]
    return []


# Each file's bytes, as `path.read_bytes()` returns them.
files = {
    "web.json": b'{"name": "web", "release": "2026-11-18", "port": 8080}',
    "jobs.json": b'{"name": "", "release": "18/11/2026", "port": 0, "debug": true}',
    "admin.json": b'{"name": "admin"',
}
assert {name: problems(text) for name, text in files.items()} == {
    "web.json": [],
    "jobs.json": [
        (("name",), "too_short"),
        (("port",), "union_error"),
        (("release",), "union_error"),
        (("debug",), "extra_forbidden"),
    ],
    "admin.json": [((), "json_invalid")],
}

Report the path and the code, not the message. A message renders the set the schema compiled to, not the keyword it was written as: a format reads as its predicate or its regular expression, a pattern as its translation into valgebra's dialect, and an integer with a bound as int and >= 1, float and >= 1. The path names the value and the code the failed check, and both are stable. A file in TOML or YAML is parsed by the library that owns the format, and the value it returns checked with validate, which reads only what json.loads could return: a TOML date is no JSON value, and no schema admits it. assert_format=True refuses a schema whose format is one of the many it does not read, uri among them, so a schema from elsewhere compiles with formats as annotations or not at all.

What a schema asserts

A keyword outside the vocabularies is an annotation, as draft 2020-12 says, so a misspelled one asserts nothing and admits every value. compile_with_fallbacks returns the compiler beside the set, and the compiler records each keyword it read as an annotation in ignored and each it read as an opaque predicate in opaque; compile_schema refuses a keyword it does not read:

from valgebra_jsonschema import Unsupported, compile_schema, compile_with_fallbacks

PROFILE = {
    "type": "object",
    "properties": {
        "name": {"type": "string", "maxLenght": 20},
        "tags": {"type": "array", "uniqueItems": True},
    },
}
compiler, profiles = compile_with_fallbacks(PROFILE, PROFILE)
assert compiler.ignored == {"maxLenght"}
assert compiler.opaque == {"uniqueItems"}
assert profiles.is_valid({"name": "a" * 50})  # the misspelled bound bounds nothing

refused = False
try:
    compile_schema({"type": "object", "dependencies": {"card": ["billing"]}})
except Unsupported as error:
    refused = True
    assert str(error) == "keyword 'dependencies' is not supported"
assert refused

A schema's author reads ignored for a keyword meant to assert, and opaque for the keywords a relation through the schema answers undecided across. dependencies, a draft-07 keyword draft 2020-12 removed, is refused in a 2020-12 schema rather than read as an annotation, since its author wrote it to a draft where it asserts; a schema declaring draft-07 compiles it.

compile_with_fallbacks reads draft 2020-12. It compiles the document as given, so an older one goes through upgrade(document, older(document)) first, which compile_schema does itself. A $defs entry no reference names is never compiled, so a keyword in it is neither recorded nor checked.