Skip to content

Support $dynamicRef and $dynamicAnchor #359

Closed

Description

@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

Activity

  1. mattpolzin commented on Mar 18, 2024

    @mattpolzin
    Owner

    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.

  2. mattpolzin commented on Nov 1, 2024

    @mattpolzin
    Owner

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

  3. aqeelat commented on Jun 15, 2026

    @aqeelat
    Contributor

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

  4. aqeelat commented on Jun 15, 2026

    @aqeelat
    Contributor

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

    Background

    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.

  5. aqeelat commented on Jul 29, 2026

    @aqeelat
    Contributor

    @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.

  6. mattpolzin commented on Jul 29, 2026

    @mattpolzin
    Owner

    No need to wait. I do consider tickets closed once merged into a main or release branch.

  7. aqeelat commented on Jul 29, 2026

    @aqeelat
    Contributor

    @mattpolzin I don't have permission to close it since I'm not an the author

  8. mattpolzin commented on Jul 29, 2026

    @mattpolzin
    Owner

    Oh, my apologies, I didn't think of that. I'll close the issue.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions