Keep a Narrow jsonschema Resolver Adapter¶
Status: accepted
Date: 2026-10-02
Decision: T08
Context and Problem Statement¶
Caller-supplied extension schemas must be offline, digest-pinned and valid at each reference target used during validation. jsonschema 4.26 has no public per-lookup hook for this check; replacing its validator or traversing every possible schema interpretation would widen the maintenance boundary.
Decision Outcome¶
Keep private _resolver injection confined to
extensions.py.
referencing owns lookup, scope and dynamic-reference behavior. The adapter
checks each encountered target’s metaschema and remains attached across
validator evolution. This per-lookup adapter adds no eager walk of local-reference targets.
The root lockfile resolves jsonschema 4.26.0 and
referencing 0.37.0. Library requirements remain jsonschema>=4.26,<5
with format-nongpl, and referencing>=0.37,<1. Dependency upgrades must review
this private integration and run the extension regressions covering offline
references, malformed targets, scopes, cycles, boolean schemas and dialect changes.
Consequences¶
The adapter has a deliberate upstream compatibility risk; a locked development run does not prove every version permitted by library metadata. Keep the seam small and add regressions for changed upstream behavior. Prefer a public hook when one can preserve these semantics. The adapter is not a general schema sandbox, execution deadline or proof of universal JSON Schema compatibility.