feat: parse and preserve $dynamicRef (JSON Schema 2020-12)

[aqeelat]

Part of #359.

Note: This is PR 1 of 2. It does parse / preserve / serialize only. Dynamic-scope resolution during dereferencing is a follow-up tracked in #359 (see the task list there). This PR on its own unblocks downstream tooling (e.g. apple/swift-openapi-generator#547) to observe the keyword.

Summary

Adds parsing and round-trip serialization for the JSON Schema 2020-12 $dynamicRef / $dynamicAnchor keywords (spec §7.7), which OpenAPI 3.1.x adopts as its schema dialect.

$dynamicAnchor parsing landed in #360, but $dynamicRef was dropped: schemas whose only attribute was $dynamicRef decoded as empty fragments with a "Found nothing but unsupported attributes" warning. This PR makes the keyword parse and round-trip on the JSONSchema AST.

Changes

• New JSONDynamicReference type wrapping JSONReference<JSONSchema> with $dynamicRef encode/decode.
• New .anchor(String) case on JSONReference.InternalReference so plain fragment references like #category parse and round-trip.
• New .dynamicReference case on JSONSchema.Schema, threaded through every exhaustive switch and the schema transformations (factory, encode/decode, optional/required/nullable, with(...), fragment combining, external dereferencing).
• Decoder recognizes $dynamicRef before the unsupported-attributes fallthrough.
• DereferencedJSONSchema retains no reference cases: per review feedback, local dereferencing throws when it encounters a .dynamicReference it cannot inline (dynamic-scope resolution is a follow-up), preserving the Dereferenced... invariant that no references remain. The raw JSONSchema AST still carries .dynamicReference for tools that read schemas without dereferencing.

Behavior

• $dynamicRef-only schema → decodes as .dynamicReference, no warning (previously an empty .fragment + "unsupported attributes").
• $dynamicRef survives encode/decode round-trips, including inside real document trees.
• dereferenced(in:) / locallyDereferenced() throws on a $dynamicRef until the resolution follow-up lands (consistent with how unresolvable static $ref values fail).

Testing

• 10 new tests in JSONSchemaDynamicReferenceTests: decode (anchor/component), the no-"unsupported-attributes" regression, encode round-trip, a full document round-trip, accessors/transformations, $ref plain-fragment round-trip, and a throws-on-dereferencing test.
• Full suite passes with no regressions: 2157 tests, 0 failures (2147 prior + 10 new).
• Verified the fix against the validator-backed fixture recursive-category-tree.yaml — $dynamicRef now survives decode (previously stripped).

Breaking change

Source-breaking (new public enum cases), so targets release/7_0. The v7 migration guide is added documenting it.

---

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

[aqeelat]

Two quick design questions before a deeper review — both could change the shape of this PR, so figured I'd surface them up front.

1. Target branch. This adds new cases to public enums (JSONSchema.Schema, DereferencedJSONSchema, JSONReference.InternalReference), so it's source-breaking. I pointed it at main, but CONTRIBUTING.md sends breaking changes for the next major to release/7_0. Happy to retarget — just let me know which you'd prefer.

2. AST shape. I went with a dedicated .dynamicReference enum case (mirroring the feature/359/dynamic-ref sketch). The alternative is a dynamicRef: String? field on CoreContext, which is non-breaking and could land on the 6.x line instead. The enum case is cleaner to pattern-match; the field avoids the major bump. Any preference?

The rest (parse / decode / encode, the decoder no longer warning on $dynamicRef-only schemas, passthrough dereferencing) should be uncontroversial. I deliberately left dynamic-scope resolution out of this PR — that's the subtle part, and I'll send it as a follow-up once this lands.

[mattpolzin]

Hey, thanks for the PR. Just a heads up that I am slow to review non-critical PRs lately for a few reasons but especially given I am on vacation without my computer for another week. Not ignoring you, though!

[aqeelat]

No worries. Enjoy your vacation. Should I ping you again in two weeks?

[aqeelat]

Hi @mattpolzin
Let me know if there is anything I can do to help with the review.

[mattpolzin]

Thanks for reminding me to get this reviewed. It's a busy time of life but I do appreciate the contribution.

Can you point this PR at the release/7_0 branch since it contains breaking changes? The updates you are making to the migration guide here look nice.

I'll want to spend a few minutes poking at the code in the next few days here but for now I just have the one high level question I left inline about whether it is justified to retain dynamic references in Dereferenced... types vs. requiring them all to be able to be derefenced.

[aqeelat]

Thanks for the review, @mattpolzin. All three points addressed:

1. Retargeted to release/7_0.
2. DereferencedJSONSchema no longer retains .dynamicReference. Agreed that the value of the Dereferenced... family is having all references fully removed. Local dereferencing now throws on .dynamicReference, mirroring how unresolvable static $ref values already fail. The raw JSONSchema AST still carries the keyword for tools that read schemas without dereferencing.
3. Removed the file header.

Also squashed into a single commit and cleaned up a few minor things (doc comments, isEmpty over count > 0, whitespace). The migration guide documents the new cases and the throwing behavior.

As a sanity check, I validated the AST against apple/swift-openapi-generator (the downstream consumer in #547) — built a prototype that resolves $dynamicRef to Swift generic types and recursive self-references. The parse/preserve layer this PR provides is sufficient; no additional OpenAPIKit changes are needed for the generator side.

[mattpolzin]

Alright, I've given this a more thorough review now that I've had time to sit down with the code open in an editor and I just have a few small remaining requests before merging.

Thanks for your patience and effort!

[aqeelat]

@mattpolzin

Thank you for taking the time.
I applied your changes.

[mattpolzin]

Thanks!