You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
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.
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:
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.
Activity
mattpolzin commentedon Mar 18, 2024
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 ofOpenAPIKitin 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$refsupport and has ideas.mattpolzin commentedon Nov 1, 2024
In preparation for a v4.0.0 release, I am bumping this issue to the v5.x milestone.
aqeelat commentedon Jun 15, 2026
I'll work on this task as part of my initiative https://github.com/aqeelat/openapi-dynamicref-adoption-tracker
PR will be opened soon
feat: parse and preserve $dynamicRef (JSON Schema 2020-12)
aqeelat commentedon Jun 15, 2026
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.fragmentwith 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$dynamicAnchorand$dynamicRefapple/swift-openapi-generator#547) from seeing it.feature/359/dynamic-refsketched an AST design (aJSONDynamicReferencewrapper + a.dynamicReferenceenum case parallel to.reference); this proposal builds on that.Proposed approach
A
.dynamicReferencecase onJSONSchema.Schema(and.anchoronJSONReference.InternalReference) is source-breaking, so it targets the next major. Split for reviewability:$dynamicRefagainst the dynamic scope #504) — merged.thread a dynamic scope (outermost→ inline non-recursive dynamic refs; throw on recursive/unresolvable (consistent with static-ref cycles).$dynamicAnchorwins) throughlocallyDereferenced(), inline non-recursive targets, and preserve.dynamicReferenceon cycles / unresolvable references$dynamicRef(feat: externally dereference$dynamicRef#503) — merged.externallyDereferenceddelegates.dynamicReferenceto the wrappedJSONReference's external deref (same path as$ref); cross-document dynamic-scope resolution is its own discrete task (under theExternalLoadingtrait, caller-suppliedExternalLoader).Design notes
.dynamicReferenceenum case (mirroring thefeature/359/dynamic-refsketch), rather than adynamicRef: String?field onCoreContext.This comment was drafted with assistance from AI tooling. The submitter has reviewed and validated the contents prior to submission.
feat: parse and preserve $dynamicRef (JSON Schema 2020-12)
feat: parse and preserve $dynamicRef (JSON Schema 2020-12)
docs: refine v7 migration guide and mark external-deref TODO per review
feat: resolve $dynamicRef against the dynamic scope during local dere…
feat: externally dereference $dynamicRef
feat: externally dereference $dynamicRef
feat: externally dereference $dynamicRef
aqeelat commentedon Jul 29, 2026
@mattpolzin I think we can close this ticket. Or do you want to wait until v7 is out?
Also, lmk if you need help with other parts of the v7 release goals.
mattpolzin commentedon Jul 29, 2026
No need to wait. I do consider tickets closed once merged into a main or release branch.
aqeelat commentedon Jul 29, 2026
@mattpolzin I don't have permission to close it since I'm not an the author
mattpolzin commentedon Jul 29, 2026
Oh, my apologies, I didn't think of that. I'll close the issue.
fix(deref): resolve component-form $dynamicRef