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.