search

mattpolzin / OpenAPIKit

Codable Swift OpenAPI implementation.
MIT License
275 stars 35 forks source link

Support `$dynamicRef` and `$dynamicAnchor` #359

Open brandonbloom opened 3 months ago

brandonbloom commented 3 months ago

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: https://github.com/apple/swift-openapi-generator/issues/547

mattpolzin commented 3 months ago

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.