Skip to content

Support contentSchema for OpenAPI 3.1 schemas (parse + ContentSchemaIn30 rule) - #207

Open
takayamaki wants to merge 4 commits into
ota42y:masterfrom
takayamaki:pr16-contentschema
Open

Support contentSchema for OpenAPI 3.1 schemas (parse + ContentSchemaIn30 rule)#207
takayamaki wants to merge 4 commits into
ota42y:masterfrom
takayamaki:pr16-contentschema

Conversation

@takayamaki

Copy link
Copy Markdown
Contributor

Continuing the OpenAPI 3.1 work from #152.

OpenAPI 3.1 adopts JSON Schema 2020-12, which brings the contentSchema annotation.
It attaches a schema to the decoded payload of a string described by contentMediaType / contentEncoding.
3.0 has no keyword for this.

This PR adds parse support and version-mismatch detection.
It completes the trio started in #204 (contentMediaType) and continued with contentEncoding.

Parse layer

contentSchema is parsed as a nested Schema (or Reference) and exposed as content_schema,
following the existing snake_case naming for object attributes (all_of, additional_properties, prefix_items):

schema.content_schema       # => OpenAPIParser::Schemas::Schema
schema.content_schema.type  # => "object"

Following the permissive-parse strategy agreed in #152,
the parse layer accepts contentSchema regardless of the declared OpenAPI version.

contentSchema is an annotation: it describes the decoded payload rather than constraining the string itself,
so there is no runtime validation to add here.
Validating the decoded payload would first require decoding it per contentEncoding,
which is out of scope for this series.

SpecValidator rule

ContentSchemaIn30 reports a violation for each schema in a 3.0 document that uses contentSchema:

OpenAPIParser.load(
  'spec.yaml',
  strict_specification_version: :warn,
)
# [ContentSchemaIn30] #/components/schemas/Attachment — `contentSchema` is a 3.1 addition (from JSON Schema 2020-12); 3.0 has no equivalent

Detection inspects raw_schema key presence,
so it fires whatever the nested schema contains.

`contentSchema` on a 3.0 document warns and raises (JSON Schema 2020-12
annotation with no 3.0 equivalent); the same keyword on a 3.1 document
stays clean.
@takayamaki
takayamaki marked this pull request as ready for review September 12, 2026 01:17
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.

1 participant