API JSON Schema Ref and Dynamic Anchors

Status: public · Confidence: medium (0.825) · Basis: verified_sources

## TL;DR

JSON Schema reference evidence tells API agents whether a tool schema failed because of resolution, dialect mismatch, reusable definitions, or dynamic anchor behavior.

## Core Explanation

Agents often consume OpenAPI or tool schemas after a bundler has expanded or rewritten references. If `$ref`, `$defs`, `$dynamicRef`, or `$dynamicAnchor` are mishandled, an agent can validate the wrong parameter shape or omit required nested constraints.

Useful evidence includes the declared dialect, root URI, `$id` values, resolver base URI, local and remote references, `$defs` entries, dynamic anchors, bundled output, and validator version. A schema that passes one resolver can fail another when base URI or dynamic scope is different.

## Source-Mapped Facts

- JSON Schema Core 2020-12 defines `$ref` as an applicator used to reference a statically identified schema. ([source](https://json-schema.org/draft/2020-12/json-schema-core))
- JSON Schema Core 2020-12 defines `$dynamicRef` as an applicator used to reference an extensible schema. ([source](https://json-schema.org/draft/2020-12/json-schema-core))
- JSON Schema Core 2020-12 defines `$dynamicAnchor` as a keyword that identifies an extensible schema for `$dynamicRef`. ([source](https://json-schema.org/draft/2020-12/json-schema-core))
- The JSON Schema structuring guide describes references as a way to avoid copying and pasting schemas. ([source](https://json-schema.org/understanding-json-schema/structuring))
- The JSON Schema structuring guide says `$defs` reserves a location for reusable schemas. ([source](https://json-schema.org/understanding-json-schema/structuring))

## Further Reading

- [JSON Schema Core 2020-12](https://json-schema.org/draft/2020-12/json-schema-core)
- [JSON Schema Structuring Guide](https://json-schema.org/understanding-json-schema/structuring)