Skip to content

Support local dereferencing of schema anchors#492

Open
ayushshrivastv wants to merge 4 commits intomattpolzin:mainfrom
ayushshrivastv:LocalAnchorDereferencing.swift
Open

Support local dereferencing of schema anchors#492
ayushshrivastv wants to merge 4 commits intomattpolzin:mainfrom
ayushshrivastv:LocalAnchorDereferencing.swift

Conversation

@ayushshrivastv
Copy link
Contributor

Closes #363

Summary

  • preserve local #anchor references as a first-class JSONReference.InternalReference case
  • make Document.locallyDereferenced() build an anchor-aware temporary lookup so schema anchors can resolve during local dereferencing
  • teach component lookup to resolve local schema anchors without changing non-schema component lookup behavior
  • add regression coverage for anchor parsing and document dereferencing

Implementation Details

OpenAPI 3.1 schema anchors live outside the Components Object, but local dereferencing in OpenAPIKit currently resolves only through document.components. To keep the fix narrow and avoid changing unrelated reference behavior, this patch keeps the anchor support scoped to local dereferencing:

  • JSONReference<...>.InternalReference now preserves #anchor values as .anchor(name:) instead of collapsing them into a generic path reference.
  • JSONReference<JSONSchema>.anchor(named:) was added as a convenience constructor for local schema anchor references.
  • Document.locallyDereferenced() now uses a temporary, anchor-aware copy of components that is populated by walking the document's inline and component-hosted schemas and registering anchored schemas for lookup during dereferencing.
  • Components+JSONReference now recognizes .anchor(name:) for JSONSchema lookups so the existing dereference machinery can resolve anchored schemas and continue following nested references/cycles consistently.

This keeps the public fix focused on the issue at hand: local document dereferencing now works for $ref: '#someAnchor' without widening non-schema or non-local lookup behavior.

Testing

  • swift test --filter JSONReferenceTests
  • swift test --filter DereferencedDocumentTests
  • swift test --filter ComponentsTests
  • swift test

@ayushshrivastv
Copy link
Contributor Author

CI note: the swift:6.1-noble failure was not caused by the local-anchor dereferencing logic itself. The crashing test was ExternalDereferencingDocumentTests.test_example, and the stack trace showed a bad pointer dereference inside the older async fan-out path used by external dereferencing on Linux 6.1.

This branch was missing the earlier Linux-stability follow-ups that we had already applied on other OpenAPIKit branches, so I pulled those fixes into this PR as well. Concretely, the fix removes the async fan-out in PathItem.externallyDereferenced(...) and avoids concurrent external loads in the shared collection dereferencing helpers, which prevents the runtime crash in the external dereferencing test path.

Local verification after the fix:

  • swift test --filter ExternalDereferencingDocumentTests -Xswiftc -strict-concurrency=complete
  • OpenAPIKitTests.ExternalDereferencingDocumentTests.test_example passed
  • OpenAPIKit30Tests.ExternalDereferencingDocumentTests.test_example passed

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

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Support local dereferencing of $ref to $anchor

1 participant