Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Support schema reference description overrides #299

Merged
merged 7 commits into from
Aug 26, 2023

Conversation

mattpolzin
Copy link
Owner

@mattpolzin mattpolzin commented Aug 26, 2023

Closes #298.

Implementation
This PR replaces the JSONSchema reference case's ReferenceContext with a CoreContext (only for the OpenAPIKit module, not the OpenAPIKit30 module) and it uses that core context's description to override the description within a referenced schema when calling the dereferenced() or dereferenced(in:) methods on JSONSchema. This carries through, naturally, to dereferencing performed on parent values all the way up to the execution of locallyDereferenced() on OpenAPI.Document.

There is also a new openAPIReference(withDescription description: String? = nil) method on JSONReference to make it easy to elevate a JSONReference to an OpenAPI.Reference. OpenAPIKit does not use this internally at the moment, but turning a JSONReference into an OpenAPI.Reference is a really nice way to carry the "override the referenced description" around so that whenever the reference is looked up the description is overridden without further effort.

Alternatives Considered
It was briefly considered to store an OpenAPI.Reference on a JSONSchema directly in place of the current JSONReference. This would take care of packaging up the description (if present) when parsing which would be the easiest solution from the perspective of downstream implementations. I decided against this implementation both because it is a larger breaking change and, at least as importantly, because OpenAPI.Reference is not the same thing as a JSONReference with an overridden description; it also parses summary and generally holds different semantics. It is elegant that the newest OpenAPI specification completely embeds the JSON Schema specification and can therefore say "anything in the schema is specified in this other specification." I wanted to embrace that here as well which means keeping "OpenAPI" things out of the JSONSchema core representation.

It was also considered to add description to the JSONReference type. This was decided against because currently the JSONReference type is only the $ref part of a schema and given that JSON References are more broadly understood even than in the context of the JSON Schema specification, it is nice to keep reference stuff in JSONReference and non reference stuff (like the behavior of overriding description) outside of JSONReference. Adding more properties to JSONReference also would have been a more disruptive change from a maintenance perspective.

Lastly, it is more correct to allow for all of the CoreContext fields alongside schema references even though the built-in dereferencing logic does not incorporate all of the fields at this time. In fact, JSON Schema now allows even more than the core context fields and it has now gained a caveat in the specification that it is not even always possible to dereference documents and get reasonable results because of the full allowance of keywords alongside $ref. OpenAPIKit will need to make some decisions in the future about how to operate in that reality.

@mattpolzin mattpolzin merged commit 97618fa into release/3_0 Aug 26, 2023
40 checks passed
@mattpolzin mattpolzin deleted the support-schema-ref-descriptions branch August 26, 2023 21:26
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Development

Successfully merging this pull request may close these issues.

1 participant