2026-09-22 · 8 min read
- json-schema
- validation
- schema-design
JSON Schema references normally identify a fixed schema location. Dynamic references add an extension mechanism: an initial reference target can expose a dynamic anchor whose effective definition is selected through the active dynamic scope.
This supports recursive families such as a base tree whose descendants must obey constraints added by an extending schema. It also introduces behavior that cannot be understood by searching for one matching anchor name in a document.
Decide whether dynamic scope is necessary
Use ordinary $ref when a stable target expresses the model. Choose $dynamicRef only when a documented extension point must be overridden through a reference chain; unnecessary dynamic resolution makes schemas harder to review and less portable.
- Name extension points consistently and case-sensitively.
- Keep the base contract useful on its own.
- Document which resources may redefine each anchor.
- Avoid relying on physical file layout as schema identity.
Model schema resources and identifiers
A compound schema document can contain several schema resources. Assign stable $id values, track each resource's base URI, and register resources by identifier when bundling them. References resolve against identifiers and dialect rules, not merely object nesting.
Declare $schema on the entry resource and confirm how embedded resources inherit or declare dialects. Validators that do not implement the required vocabulary should fail configuration checks instead of silently weakening validation.
Trace initial and dynamic resolution
First resolve the URI reference to its initial resource and anchor. Then inspect the dynamic scope established by the chain of referenced resources and determine whether a matching dynamic anchor changes the effective target.
Capture absolute schema locations, instance locations, evaluated branches, and reference transitions from validator output when possible. Set depth, size, remote-fetch, and cycle controls independently from schema correctness.
Publish cross-validator fixtures
Use Flashman's JSON formatter for schemas and instances, diff for resource revisions, URL tool for public identifiers, YAML converter for configuration sources, and regex tester for harmless pattern constraints.
Test the base resource alone, one and several extensions, nested recursive values, sibling references, missing and duplicate anchors, relative and absolute IDs, compound documents, registry loading, unsupported dialects, deep inputs, and every validator upgrade.