$recursiveAnchor : Boolean

$recursiveAnchor

Boolean

This keyword is used to dynamically identify a base URI at runtime by marking where such a calculation can start, and where it stops.

Value	This keyword must be set to a boolean that determines whether the reference destination is must be determined by examining the dynamic scope or not Hint: Use the `jsonschema metaschema` and `jsonschema lint` commands to catch keywords set to invalid values
Kind	Identifier
Applies To	Any
Base Dialect	2019-09
Changed In	None
Introduced In	2019-09
Vocabulary	Core
Specification	https://json-schema.org/draft/2019-09/draft-handrews-json-schema-02#rfc.section.8.2.4.2.2
Metaschema	https://json-schema.org/draft/2019-09/meta/core
Official Tests	draft2019-09/recursiveRef.json
Default	`false`
Annotation	None
Affected By	None
Affects	$ref (Vocabulary: Core) $recursiveRef (Vocabulary: Core)
Also See	$id (Vocabulary: Core) $anchor (Vocabulary: Core)

The $recursiveAnchor keyword is an extension of the $anchor keyword that, when set to true, associates a subschema with a special empty URI fragment identifier and records this association in the dynamic scope. When resolving this anchor using the $recursiveRef keyword, the base URI of the origin is not considered. Instead, evaluation jumps to the first encountered occurrence of the given recursive anchor in the stack of schema resources traversed so far.

Best Practice

This advanced feature was only designed for supporting meta-schemas. Avoid using this keyword if you are not defining a meta-schema.

Digging Deeper

The official JSON Schema meta-schemas all define the recursive anchor. as a fundamental building block for schema extensibility. The meta-schema of every vocabulary (official or third-party) hooks into the recursive anchor to extend the recursive definition of what constitutes a valid schema for the given dialect.

More specifically, by relying on the recursive anchor, a vocabulary meta-schema can validate the presence of a new keyword and have those constraints be automatically discovered and applied by any applicator of any other vocabulary (even future ones).

Common Pitfall

The schema resource from where the recursive anchor lookup originates must declare the recursive anchor. Otherwise, the schema would be unusable until another schema provides a definition for the recursive anchor. This rule is informally referred to as the bookending requirement.

To debug which recursive anchor the evaluation process is jumping to, try the jsonschema validate command with the --trace option. This option prints a trace of every step in the evaluation process alongside the corresponding keywords and their respective locations, letting you know which destination was preferred when encountering a recursive reference. For example:

$ jsonschema validate custom-metaschema.json schema.json --trace
...

-> (push) "/$ref/allOf/1/$ref/properties/additionalProperties/$recursiveRef" (ControlDynamicAnchorJump)
   at "/additionalProperties"
   at keyword location "https://json-schema.org/draft/2019-09/meta/applicator#/properties/additionalProperties/$recursiveRef"
   at vocabulary "https://json-schema.org/draft/2019-09/vocab/core"

-> (push) "/$ref/allOf/1/$ref/properties/additionalProperties/$recursiveRef/properties" (LogicalWhenType)
   at "/additionalProperties"
   at keyword location "https://example.com/custom-metaschema#/properties"
   at vocabulary "https://json-schema.org/draft/2019-09/vocab/applicator"
...

Examples

A custom meta-schema that extends the JSON Schema 2019-09 dialect with a custom keyword Schema

{
  "$schema": "https://json-schema.org/draft/2019-09/schema",
  "$id": "https://example.com/custom-metaschema",
  "$recursiveAnchor": true,
  "$ref": "https://json-schema.org/draft/2019-09/schema",
  "properties": {
    "my-custom-keyword": { "type": "string" }
  }
}

Valid An object with a top-level occurrence of the custom keyword is valid Instance

{ "my-custom-keyword": "foo" }

Annotations

{ "keyword": "/properties", "instance": "", "value": [ "my-custom-keyword" ] }

Valid An object with a nested occurrence of the custom keyword is valid Instance

{ "additionalProperties": { "my-custom-keyword": "foo" } }