Add URI resolution helpers for base URI resolution

[ayushshrivastv]

Summary

• add reusable URI resolution helpers for raw URLs, JSON references, and documents in both OpenAPIKit and OpenAPIKit30
• add schema base URI helpers and identifier support on OpenAPIKit schema contexts so callers can compose parent base URIs with schema identifiers
• cover the new helpers with focused document, reference, and schema URI resolution tests

Closes #439.

Testing

• swift test --filter JSONReferenceURIResolutionTests
• swift test --filter DocumentURIResolutionTests
• swift test --filter JSONSchemaURIResolutionTests
• git diff --check

[ayushshrivastv]

Follow-up for the failing linux (swift:6.1-jammy) job: the failure was not in the new URI-resolution code. It was the same older Swift async runtime crash in OpenAPI.PathItem.externallyDereferenced / OpenAPIKit30/Path Item/DereferencedPathItem.swift during ExternalDereferencingDocumentTests.test_example. I cherry-picked the proven compatibility fix (bd82590) onto this branch, pushed it, and re-ran the relevant coverage locally.

Additional local verification after the follow-up commit:

• swift test --filter ExternalDereferencingDocumentTests/test_example -Xswiftc -strict-concurrency=complete
• swift test --filter JSONReferenceURIResolutionTests
• swift test --filter DocumentURIResolutionTests
• swift test --filter JSONSchemaURIResolutionTests
• git diff --check

[mattpolzin]

Were these changes generated by an LLM? I ask because there are places where decoding of the same property is being done twice and in one of the two locations, the strategy being used does not fit the patterns established in this codebase.

If this PR was hand written, I am happy to walk through what I mean. However, if this PR was generated code that has not been read and understood by a human, I would request that you spend the time to work through this code on your own and attempt to spot the problem and gain further understanding of the codebase.

[ayushshrivastv]

I put this change together myself while tracing through the existing code and validating it locally. Also I have used Codex at times to help work through failing test cases, but I still verify the changes myself before committing them. Your comment makes it clear that I’ve missed an inconsistency in how this part should be handled, so I’m going to revisit it carefully and align it with the patterns already used in the codebase before I push an update.

For context, I’ve contributed to this project before and have had a couple of PRs merged, including #405 and #404. I’ve also been keeping notes here: OpenAPI Integration with DocC.

[ayushshrivastv]

I went back through the PR again and tightened the remaining pieces to stay aligned with the existing patterns in the codebase. In particular, $id now goes only through the existing CoreContext decoding path, and I cleaned up the schema accessor/initializer usage so it follows the same style already used in main rather than introducing a separate approach. I also reverted the async workaround changes, so this PR no longer changes the existing concurrency behavior in DereferencedPathItem.

[mattpolzin]

I apologize I have not had much time for reviewing PRs in this repo lately. I gave this PR a look tonight with emphasis on understanding if the code adheres to the specification or not. I will have to take more time to look over the implementation itself later, but I wanted to suggest that you add some more test coverage for Document baseURI usage because there are several important combinations of retrieval URL and $self that Appendix F of the spec goes through as examples and it would be good to have test coverage to know the implementation at least treats all of those example situations correctly.

[ayushshrivastv]

Thanks @mattpolzin for the overview! I’ll expand test coverage to ensure those scenarios are properly handled. There’s no urgency on this, so feel free to review at your convenience.

[mattpolzin]

Sorry again for the delayed review. This PR looks like it's in good shape. I've got a couple of small comments or requests.

[ayushshrivastv]

@mattpolzin, I’ve addressed your feedbacks on this PR in this commit: 65941af

Thanks!

[mattpolzin]

Hey, thanks for the continued work on this. I wasn't quite thinking that I wanted to go for optional URL returns when I asked if there was any way we could avoid forcing the string to parse as a URL. Everything else is looking good I think.

What I was hoping for was a way to build a URL from component parts avoiding the need to force an optional because we would know the URL was going to be correct by construction. I went looking at the docs and was surprised (and sad) to see that this isn't actually possible. The closest it seems you can do is construct a URLComponents and then get a URL from that but you still end up with an optional URL even then... disappointing.

Can I request that we go back to non-optional URL returns but instead of forcing a string-parsed URL we create a URLComponents value by adding the fragment onto it and then use url! on that -- we are still forcing, but we are leaving a little bit up to chance than if we go via a plain string value.

[ayushshrivastv]

Agreed, optional returns were a broader API change than needed here. I changed this back to non-optional URL returns and now construct the internal fragment URL with URLComponents, forcing only after the fragment has been set by construction.

[mattpolzin]

This looks good. Thanks for working with me on the URL construction while I figured out what was supported by the URL type itself.

[mattpolzin]

I just had one final thought which was that I would like to avoid adding a generic helper to the URL type given that helper is only used internally by OpenAPIKit and this library is not here to offer "url resolution relative to base urls" to downstream users of the URL type.

I just pushed a change that just moves that function out of an extension to keep the URL type cleaner.