Repository navigation
Add support for $schema and jsonSchemaDialect #2963
Description
Activity
I would like to take this.
Hi Haseeb Nazir (@iamhaseebn),
Sure, we'll be happy to get a pull request.
Before starting to write code, can you please suggest a design which would inform this work?
Thanks! I was thinking we could keep this internal in
ParsingContextrather than changing the public schema types.When reading a schema, we'd resolve the dialect from its
$schemavalue or inherited dialect, then fall back to the document'sjsonSchemaDialect, and finally the OpenAPI version default. The service would select the matching parsing rules, while keywords we don't understand would stay inUnrecognizedKeywordsso they aren't lost.For an unknown dialect URI, we'd reuse the existing external-loading path, cache the meta-schema, and follow its
$schemachain until reaching a known dialect. This would include cycle detection and reasonable depth and size limits. If it can't be resolved, we'd report a diagnostic instead of silently treating it as JSON Schema 2020-12.I'd apply the same dialect selection when writing and add matching OpenAPI 3.1 and 3.2 tests. If this direction looks right, I'll work from it.
I think that sounds like a great approach. I'm not sure how the mapping from a dialect to the parsing logic will happen, but maybe we can rely on the existing version services? or a similar approach.
Anyway, please start a draft PR, and we can iterate from there.
Sounds good, thanks. I’ll use the existing version services as the starting point for the dialect mapping and open a draft PR so we can work through the details there.
In today's implementation (2.11.0, 3.9.0), the deserialization and serialization of JSON Schemas is effectively hard-coded to 2020-12.
However, starting with OpenAPI 3.1, people can set the $schema property of any given schema to a different dialect (default being documented here.
This entails a couple of things:
https://spec.openapis.org/oas/3.1/dialect/baseusing the parsing logic associated with that entryThat update will most likely require introducing a JSON Schema service of some kind in charge of mapping the known schemas with their deserialization logic, and having the OpenAPISchema deserializers call into that service.