Skip to content

Detect nullable in OpenAPI 3.1 documents (NullableDeprecation rule)#193

Open
takayamaki wants to merge 2 commits into
ota42y:masterfrom
takayamaki:pr5-nullable-deprecation
Open

Detect nullable in OpenAPI 3.1 documents (NullableDeprecation rule)#193
takayamaki wants to merge 2 commits into
ota42y:masterfrom
takayamaki:pr5-nullable-deprecation

Conversation

@takayamaki

@takayamaki takayamaki commented Jun 21, 2026

Copy link
Copy Markdown
Contributor

ref: #152

Continuing the OpenAPI 3.1 work from #192.

This PR adds a new SpecValidator rule:

  • OpenAPIParser::SpecValidator::Rules::NullableDeprecation

Design

In 3.0, nullable: true marks a schema as accepting null.
3.1 removed the keyword entirely in favor of type: [..., "null"].

The rule flags the mere presence of nullable on a 3.1 document — true and false are both violations, since the field itself is gone.
This matches how OAS treats removed keywords: it is not about the value, it is about the keyword being there at all.

# 3.1 document
schema:
  type: string
  nullable: false   # flagged — keyword removed in 3.1, even though false is the safe value

Implementation details

Detection inspects raw_schema directly

schema.nullable returns false when the key is absent and when it is explicitly set to false. The rule needs to distinguish those two states,
so it checks schema.raw_schema.key?('nullable') instead of the accessor:

each_schema(root) do |schema|
  next unless schema.raw_schema.is_a?(Hash) && schema.raw_schema.key?('nullable')
  violations << violation(path: schema.object_reference, message: ...)
end

Wiring

One line added to the rules array in SpecValidator, plus the rule file under spec_validator/rules/. No changes to the parse layer or runtime
— parsing continues to accept nullable on either version; only the validator reports it.

Tests

  • Unit specs cover: 3.0 with nullable: true / false (clean), 3.1 with nullable: true / false (both flagged), 3.1 without nullable
    (clean), :unknown version (skipped).
  • Integration spec exercises the warn/raise dispatch path with openapi_3_1/nullable_30.yaml and nullable_31.yaml fixtures.

Spec_validator only. `nullable` is removed in 3.1; any presence on
a 3.1 document is flagged, regardless of true/false. Detection
inspects raw_schema directly so a literal `nullable: false` is not
confused with the field being absent.
`nullable` on a 3.1 document warns and raises (removed in favour of
type: [..., null]); the same keyword on a 3.0 document stays clean.
@takayamaki takayamaki marked this pull request as ready for review June 21, 2026 14:01
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