2026-09-24 · 6 min read · Rahul Chitturi
- json-schema
- validation
- debugging
A JSON Schema dialect can identify vocabularies and mark each one as required for implementations of that dialect. Validation becomes unreliable when a library accepts the metaschema URI but silently lacks a required vocabulary or treats its keywords as annotations.
The same schema may therefore reject startup in one service, pass every instance in another, and appear valid in an editor that uses a different dialect or validator build.
Record the effective dialect
Capture the root $schema value, referenced metaschema, its $vocabulary object, validator name and version, enabled plugins, schema registry behavior, and compilation diagnostics. Resolve trusted metaschemas without letting arbitrary schemas redirect loading to unapproved networks.
- Distinguish a vocabulary URI from a keyword namespace.
- Treat true entries as required implementation support.
- Document behavior for optional false entries.
- Fail deployment when required support is absent.
Prove keyword evaluation
Build one minimal schema and instance pair per important keyword, including a case that must fail only when that keyword is evaluated. Merely compiling a schema or recognizing a keyword name does not prove the required semantics are active.
Compare output formats and annotations separately from pass or fail results. A custom vocabulary also needs a stable metaschema, implementation registration, URI policy, and compatibility plan.
Keep conformance fixtures portable
Use Flashman's JSON formatter for schemas, YAML/JSON converter for configuration copies, diff for validator output, and hash tool for public fixture identity.
Test missing vocabulary support, unknown optional vocabularies, nested $schema boundaries, remote references, offline registries, plugin disabled states, validator upgrades, malformed metaschemas, and identical fixtures in CI and production.