2026-09-24 · 8 min read
- json-schema
- validation
- architecture
A JSON Schema dialect is defined by a metaschema and the vocabularies it composes. A vocabulary gives semantics to a related set of keywords, while the metaschema describes valid schema syntax and can declare whether implementation support is required.
Teams need this distinction when they adopt new specification drafts, create organization-specific keywords, or run schemas through several languages and gateways. Syntactic acceptance alone does not prove equivalent validation.
Pin the schema contract
Require an explicit $schema value for governed schemas and resolve it through an approved registry. Record the metaschema URI, $vocabulary declarations, required versus optional support, validator versions, extensions, output format, and policy for unknown keywords.
- Use stable absolute identifiers for published dialects.
- Treat required vocabulary support as a startup invariant.
- Document optional vocabulary fallback behavior.
- Keep schema retrieval bounded and observable.
Separate syntax from semantics
A metaschema can constrain where keywords appear and what values they accept, but a validator implementation must supply their runtime meaning. For each keyword that affects acceptance, create a positive instance and a negative instance that passes if the keyword is ignored.
Assertions, annotations, applicators, and output details have different roles. Compare the final validation result first, then inspect annotations and diagnostic locations without making business logic depend on unstable message text.
Govern custom vocabularies
Give custom keywords precise instance semantics, schema-value syntax, interaction rules, security limits, and test vectors. Publish a metaschema and implementation package together, and reject schemas requiring the vocabulary when the package is unavailable.
Avoid using annotations as hidden authorization or data-mutation instructions. Validation should remain deterministic for the declared dialect, while side effects and business policy stay in explicit application stages.
Control references and upgrades
Allowlist remote origins or mirror schemas into a versioned registry. Apply retrieval timeouts, document-size limits, reference-depth controls, cycle handling, content integrity checks, and cache invalidation. Do not fetch arbitrary schema URIs from untrusted instance data.
Before upgrading a validator or dialect, run the same corpus across old and new stacks and classify intentional semantic changes. Roll out producers and consumers in an order that never requires unsupported vocabulary from an older service.
Publish a conformance suite
Use Flashman's JSON formatter for schemas, YAML/JSON converter for configuration, diff for cross-validator results, hash tool for fixture identity, and Base64 tool when public encoded fixtures are needed.
Cover required and optional vocabularies, unknown keywords, nested resource dialects, $ref boundaries, offline resolution, malformed metaschemas, plugin failures, annotation output, large or cyclic reference graphs, library upgrades, and every production language.