References and Anchors

References, Definitions and Dynamic Anchors

$ref points at a schema by URI: #/$defs/item is a JSON Pointer into the same document, money.json resolves against $id, and #item names an $anchor. $ref always means the same target; $dynamicRef resolves during validation, so a generic schema can leave a hole that a specific one fills, as in a paged API response:

A generic page schema specialized for books with $dynamicRefPython

from jsonschema import Draft202012Validator
from referencing import Registry, Resource
S = "https://json-schema.org/draft/2020-12/schema"
page = {"$schema": S, "$id": "https://example.com/page", "type": "object",
        "properties": {"results": {"type": "array", "items": {"$dynamicRef": "#item"}}},
        "$defs": {"any": {"$dynamicAnchor": "item"}}}
book_page = {"$schema": S, "$id": "https://example.com/book-page", "$ref": "page",
             "$defs": {"book": {"$dynamicAnchor": "item", "required": ["id", "title"]}}}
reg = Registry().with_resources((s["$id"], Resource.from_contents(s))
                                for s in (page, book_page))
doc = {"results": [{"id": 1, "title": "The Quiet Harbor"}, {"id": 2}]}
for schema in (page, book_page):
    errs = Draft202012Validator(schema, registry=reg).iter_errors(doc)
    print(schema["$id"], [f"{e.json_path}: {e.message}" for e in errs])

Output

https://example.com/page []
https://example.com/book-page ["$.results[1]: 'title' is a required property"]

Alone, page resolves #item to its permissive default. Entered through book-page, the outermost schema in the dynamic scope declaring $dynamicAnchor: item wins, so every result must be a book. Keep schemas in a local registry like this one.

MENU