jsonschema-consistency

jsonschema (Python) — consistent, modern idioms

The jsonschema package is stable, but its conveniences mislead: bare validate() stops at one error and picks a draft for you, format: does nothing unless a format checker is attached, and a decade of RefResolver examples predate the referencing library that replaced it. This skill pins the canonical idiom set for jsonschema 4.x.

Canonical idioms — always X, never Y

Always	Never	Why
pick the validator from the schema: validator_for(schema) (honors $schema) or an explicit Draft202012Validator	bare validate(instance, schema) everywhere	The convenience function hides draft selection and gives only the first error.
validator.check_schema(schema) (or cls(schema) after check_schema) at startup	trusting the schema is itself valid	A typo'd schema ("requried") validates nothing and raises no alarm.
errors = sorted(v.iter_errors(instance), key=lambda e: e.json_path)	first-error-only reporting to users	One round-trip per error exhausts everyone; report all.
Draft202012Validator(schema, format_checker=Draft202012Validator.FORMAT_CHECKER)	assuming format: "email" is enforced	Format checking is opt-in; without the checker every format passes.
build a validator once, reuse it	re-validating with validate() in hot paths	Validator construction does schema processing; reuse is the cheap path.
$ref across files via referencing.Registry + Resource	RefResolver	RefResolver is deprecated (the referencing library is the replacement); new code on it accrues warnings and dead-end APIs.
best_match(v.iter_errors(i)) for the single most relevant error	next(iter_errors(...)) arbitrary first	best_match descends combinators to the likeliest cause.
remember: defaults are not applied — validation never mutates the instance	expecting default: to fill values	The spec says defaults are annotations; filling them requires the documented extended-validator pattern.
schemas as data files (JSON/YAML) with $id and $schema declared	anonymous inline dict schemas scattered through code	Files get checked, reused, and referenced; inline dicts drift.

House style:

from jsonschema import Draft202012Validator
from jsonschema.exceptions import best_match

validator = Draft202012Validator(
    schema,
    format_checker=Draft202012Validator.FORMAT_CHECKER,
)
validator.check_schema(schema)  # at startup / in tests

def check(instance) -> list[str]:
    errors = sorted(validator.iter_errors(instance), key=lambda e: e.json_path)
    return [f"{e.json_path}: {e.message}" for e in errors]

# headline error for logs:
err = best_match(validator.iter_errors(instance))

Pitfalls that produce silently wrong validation

• Wrong-draft validation: validate() uses the $schema-declared draft if present, else the latest. A draft-07 schema without $schema validated under 2020-12 changes semantics (e.g. tuple items vs prefixItems are ignored as unknown keywords — unknown keywords never error). Declare $schema in every schema file.
• Format checking is layered opt-in: even with FORMAT_CHECKER, some formats need extras — install jsonschema[format] (or format-nongpl) for email, uri, date-time-strictness, idn-*; without the extra deps those formats silently pass.
• Schema typos validate everything: "required": "name" (string, not list), "type": "String", properties nested under the wrong key — check_schema catches the structural ones; tests with known-bad instances catch the rest. Every schema deserves one failing-instance test.
• Python types vs JSON types: type: "number" accepts ints; True/False are not accepted by "type": "integer"-vs-bool subtleties (bool is an int subclass — jsonschema special-cases it correctly; hand-rolled checks don't). Tuples are not arrays by default.
• ValidationError anatomy: .message (human), .json_path/.absolute_path (where in the instance), .validator/.validator_value (failing keyword), .context (sub-errors inside anyOf/oneOf). Build reporting from these fields, not by string-parsing .message.
• anyOf/oneOf error floods: the raw error claims the combinator failed and buries branch detail in .context — recurse into context (or use best_match) when reporting.
• Validation ≠ parsing: data arrives as Python objects already (json.loads first); a "schema-valid" string that was never parsed is a different object than its parse.

Version notes

Target jsonschema 4.18+ (where referencing integration landed; current 4.2x). The deprecation models keep generating: RefResolver (and resolver= argument) → registry= with referencing.Registry. Draft classes available: Draft202012Validator, Draft201909Validator, Draft7Validator, Draft6Validator, Draft4Validator — the package validates all of them; your code should pin one per schema family.

Workflow

1. Author the schema as a file with $schema (and $id); check_schema it in tests alongside at least one passing and one failing instance.
2. Construct the right validator once (draft-matched, format checker attached, registry for refs); export it from a module.
3. Validate with iter_errors; sort by path; report all errors (best_match for a headline).
4. Handle refs by registering every referenced schema in a Registry — no network, no filesystem guessing.
5. When reviewing, hunt: bare validate() in loops/hot paths, format reliance with no checker, RefResolver, first-error-only UX, schemas never check_schema'd, default values assumed to apply.

For the validator/draft matrix, referencing-registry recipes, error-tree handling, and the defaults-filling extended validator, read references/jsonschema-patterns.md.