Skip to content

Support root-level jsonSchemaDialect for OpenAPI 3.1 documents (parse + JsonSchemaDialectIn30 rule) - #201

Merged
geemus merged 4 commits into
ota42y:masterfrom
takayamaki:pr11-jsonschemadialect
Aug 14, 2026
Merged

Support root-level jsonSchemaDialect for OpenAPI 3.1 documents (parse + JsonSchemaDialectIn30 rule)#201
geemus merged 4 commits into
ota42y:masterfrom
takayamaki:pr11-jsonschemadialect

Conversation

@takayamaki

Copy link
Copy Markdown
Contributor

Continuing the OpenAPI 3.1 work from #152.

OpenAPI 3.1 adds a root-level jsonSchemaDialect field:
a URI declaring the default JSON Schema dialect for schemas in the document.
3.0 has no equivalent field.

This PR adds parse support and version-mismatch detection.

Parse layer

jsonSchemaDialect is parsed as a plain string value,
exposed as an accessor on the root object:

root = OpenAPIParser.load('spec_3_1.yaml')
root.json_schema_dialect # => "https://spec.openapis.org/oas/3.1/dialect/base"

Following the permissive-parse strategy agreed in #152,
the parse layer accepts jsonSchemaDialect regardless of the declared OpenAPI version.
Dialect-aware schema interpretation is out of scope for this PR;
the value is exposed for callers to inspect.

SpecValidator rule

JsonSchemaDialectIn30 reports a violation when a 3.0 document declares root-level jsonSchemaDialect:

OpenAPIParser.load(
  'spec.yaml',
  strict_specification_version: :warn,
)
# [JsonSchemaDialectIn30] #/jsonSchemaDialect — `jsonSchemaDialect` is a 3.1 root-level addition; 3.0 documents have no such field

OpenAPI root gains a `json_schema_dialect` String accessor (camelCase
schema key). The matching SpecValidator rule flags the field on 3.0
documents.
A root-level `jsonSchemaDialect` on a 3.0 document warns and raises (3.1
addition); the same field on a 3.1 document stays clean.
@takayamaki
takayamaki marked this pull request as ready for review August 11, 2026 07:11

@geemus geemus left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

lgtm, thanks!

@geemus
geemus merged commit 79b9d9d into ota42y:master Aug 14, 2026
14 checks 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.

2 participants