Support `$dynamicRef` and `$dynamicAnchor`

[brandonbloom]

Motivation

These keywords are defined in the JSON Schema 2020-12 dialect.

Release notes: https://json-schema.org/draft/2020-12/release-notes

These are useful for representing generics: https://json-schema.org/blog/posts/dynamicref-and-generics

Specification of dynamic scope rules: https://json-schema.org/draft/2020-12/json-schema-core#name-lexical-scope-and-dynamic-s

Additional information

Also filed follow-on issue: apple/swift-openapi-generator#547

[mattpolzin]

Thanks for summing this up nicely. I am currently playing with the implementation and trying to decide if there's a good way to introduce this without it being a breaking change to OpenAPIKIt. I've got v4 of OpenAPIKit in alpha already, so I can add it there even if it is breaking, but ideally I'd be able to surface this in a minor v3 version as well.

My very early gut feeling is it will be difficult to work this into the v3 understanding of json-schema since OpenAPIKit "knows how to work with $refs" (i.e. you can tell it to dereference a document by following all refs throughout) but these dynamic references have different dereferencing semantics and rules. If I did find a backwards compatible path, it would likely be to simply parse the references/anchors but not support them more deeply than that. That would be fine with me (with a deeper understanding of the references coming in v4, likely) but it remains to be seen if I can find a good design for that superficial support.

I'm certainly open to implementation suggestions, too, if anyone coming to this issue has looked over OpenAPIKit's $ref support and has ideas.

[mattpolzin]

In preparation for a v4.0.0 release, I am bumping this issue to the v5.x milestone.

[aqeelat]

I'll work on this task as part of my initiative https://github.com/aqeelat/openapi-dynamicref-adoption-tracker
PR will be opened soon

[aqeelat]

I've been looking into this and have a concrete proposal, split into two reviewable pieces. Leaving a plan here for visibility.

Background

• $anchor / $dynamicAnchor: parsed and preserved (Add JSONSchema support for anchors #360).
• $dynamicRef (pre-feat: parse and preserve $dynamicRef (JSON Schema 2020-12) #501): a $dynamicRef-only schema decodes as an empty .fragment with a "Found nothing but unsupported attributes" warning, dropping the keyword — the gap addressed by feat: parse and preserve $dynamicRef (JSON Schema 2020-12) #501, which otherwise blocks downstream tooling (e.g. Support $dynamicAnchor and $dynamicRef apple/swift-openapi-generator#547) from seeing it.
• feature/359/dynamic-ref sketched an AST design (a JSONDynamicReference wrapper + a .dynamicReference enum case parallel to .reference); this proposal builds on that.

Proposed approach

A .dynamicReference case on JSONSchema.Schema (and .anchor on JSONReference.InternalReference) is source-breaking, so it targets the next major. Split for reviewability:

• parse / preserve / serialize (feat: parse and preserve $dynamicRef (JSON Schema 2020-12) #501) — merged.
• dynamic-scope-aware dereferencing (feat: resolve $dynamicRef against the dynamic scope #504) — merged. thread a dynamic scope (outermost $dynamicAnchor wins) through locallyDereferenced(), inline non-recursive targets, and preserve .dynamicReference on cycles / unresolvable references → inline non-recursive dynamic refs; throw on recursive/unresolvable (consistent with static-ref cycles).
• External dereferencing of $dynamicRef (feat: externally dereference $dynamicRef #503) — merged. externallyDereferenced delegates .dynamicReference to the wrapped JSONReference's external deref (same path as $ref); cross-document dynamic-scope resolution is its own discrete task (under the ExternalLoading trait, caller-supplied ExternalLoader).

Design notes

• AST shape: a dedicated .dynamicReference enum case (mirroring the feature/359/dynamic-ref sketch), rather than a dynamicRef: String? field on CoreContext.
• Scope of feat: parse and preserve $dynamicRef (JSON Schema 2020-12) #501: parse/preserve/serialize only — the "parse the references/anchors but not support them more deeply" option; no dynamic-scope resolution.

---

This comment was drafted with assistance from AI tooling. The submitter has reviewed and validated the contents prior to submission.