Support `$dynamicAnchor` and `$dynamicRef`

[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

Proposed solution

Schemas containing $defs generate types that include the defs as members. If the schemas contain $dynamicAnchor, they create protocols with associated types instead of concrete types with type aliases. The schema of the dynamic-anchored types are used as the type constraint for the associated types.

Dynamic reference schemas (those containing the $dynamicRef keyword) refer to associated types and may supply generic parameters using their own $defs and $dynamicAnchor keywords.

Alternatives considered

Avoid generating protocols / associated types, and instead always generate concrete types, treating dynamic refs/anchors as template instantiation.

Additional information

This would depend on support in OpenAPIKit. Upstream issue filed: mattpolzin/OpenAPIKit#359

[czechboy0]

Thanks @brandonbloom - I'll mark this one as blocked, until the OpenAPIKit support is landed.

[czechboy0]

I wonder, have you also considered generating generic types, instead of protocols? From my reading of the specification, that might be the closest representation in Swift to the requested feature.

[mattpolzin]

I've begun exploring this in OpenAPIKit. I've only thought on it for a few minutes so far, but I wanted to make sure to extend an invitation for help deciding how to integrate these new references into OpenAPKit if anyone over here has thoughts; I know it isn't always possible to comment directly on third party repositories, I will do my best to coordinate any conversation that happens split between the two disparate GitHub issues.

My initial thinking is I cannot simply support an additional key and boolean property on the JSONReference type since that type is deeply integrated with knowledge about how $ref tags behave and $dynamic-ref tags have different semantics and rules -- even that assumption is up for discussion, though.

[czechboy0]

I wonder what the minimum support for a generic type would be here. Basically, knowing that a type is generic over N types, and OpenAPIKit filling them in.

Re references, in 3.1 there's OpenAPI.Reference, maybe that's where some of it could be added?

[mattpolzin]

OpenAPI.Reference may not quite fit the needs here since that type wraps a reference and adds description/summary overriding; it does manage to introduce different behavior compared to JSONReference, but since it was introduced to support the OpenAPI-specific extensions to $ref it isn't currently supported within JSONSchema (it's used everywhere outside of JSONSchema, though).

[czechboy0]

Fair enough - yeah maybe a way to make progress here would be to first identify the minimum work needed to support the simple List<T> use case, and generalize from there.

[mattpolzin]

@brandonbloom do you have an example or two of OpenAPI documents that take advantage of $dynamicRef? I'm curious if they tend to use local $defs within the json-schemas or if (being OpenAPI Documents) they tend to put the $dynamicAnchors inside the #components/schemas which would be my instinct personally.

[brandonbloom]

I wonder, have you also considered generating generic types, instead of protocols? From my reading of the specification, that might be the closest representation in Swift to the requested feature.

I considered it briefly & perhaps discarded it prematurely. The reasons I was immediately drawn to protocols is because generics use positional type parameters, which don't have a clean mapping to the dynamicRef concept as far as I can tell. Associatedtypes seem more similar to what the local $defs look like.

do you have an example or two

Examples from Github: https://github.com/search?q=%28%22%24dynamicRef%22+OR+%22%24dynamicAnchor%22%29+%28path%3A**%2F*.yaml+OR+path%3A**%2F*.yml+OR+path%3A**%2F*.json%29&type=code