Add support for $schema and jsonSchemaDialect

Open
#2,963 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Assessment

Difficulty
5/5
Estimated time
Over a week
Newbie friendliness
35/100
Issue type
Feature
Clarity
Mostly clear
Activity status
Active
Tech stack
csharp, openapi
Domain
api, backend-api-design

Research direction

Start by tracing the OpenAPISchema deserializers and serializers and identifying where the 2020-12 assumption is applied. Define the JSON Schema service around dialect registration, fallback resolution, recursive unknown-schema handling, and security constraints; done means $schema and jsonSchemaDialect select the correct known or loaded dialect without breaking existing behavior.

Written by the indexing model from the issue text.

Description

help wanted

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:

  1. parsing that keyword first if it exists, or falling back on the document dialect property, or falling back to the default value for the OpenAPI version.
  2. if that value is known (like https://spec.openapis.org/oas/3.1/dialect/base using the parsing logic associated with that entry
  3. if that value is unknown, we need to load the corresponding schema, and read its schema (recursively) until we find a known value. (note be careful of the security considerations here)

Note: ideally we'd make the OpenAPISchema type generic and allow the caller to provide new registrations of schemas uris with the corresponding parsing logic and data type, but that'd introduce major breaking changes, making the cost prohibitive.

That 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.

Dominant language
C#
Stars
1.6k
Forks
286
Avg merge
6h 38m
Merged PRs (30d)
35

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from microsoft/OpenAPI.NET

All issues in microsoft/OpenAPI.NET

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.