Skip to content

Read the OpenAPI 3.1 type keyword in the type and null rules - #963

Open
Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:feat/950-phase2-types-null
Open

Inf1mum wants to merge 1 commit into
OpenAPITools:masterfrom
Inf1mum:feat/950-phase2-types-null

Conversation

@Inf1mum

@Inf1mum Inf1mum commented Nov 16, 2026 •

Copy link
Copy Markdown

Part of #950 — Phase 2, area 1 of 4: types and null. Prior art: #938 (same root cause for referenced component schemas); the fixture pairs reuse the Phase 0 harness layout from #961.

Spec

The engine picked its type comparison by the Java class shape. The type gate in SchemaDiff#computeDiffForReal compared getType(), which is null for OpenAPI 3.1 schemas (the type keyword lands in the types set at deserialization), so a 3.1→3.1 type change compared null with null and was silently dropped. Nullability had the same gap: in 3.1 type: [string, "null"] is the nullable spelling, but nothing in the engine read "null" from the types set, so adding it produced no_changes.

Implementation

  • New SchemaTypes helper in utils (the issue's small helper, one place for the keyword): reads the type keyword from both shapes while the phase is in progress — getType() for 3.0/Swagger 2.0, getTypes() for 3.1 — and splits it into the two things the rules reason about: the set of non-null types, and whether "null" is one of them.
  • The type gate now compares SchemaTypes.types(left)/types(right) instead of the raw getType() strings. A difference in the non-null type set still takes the exact same getTypeChangedSchema path, so classification stays identical to 3.0 (INCOMPATIBLE via changedType).
  • "null" only goes through the existing null rule: SchemaDiffResult feeds ChangedNullable with SchemaTypes.nullableValue(...) — the 3.0 nullable flag when it is set, otherwise the 3.1 "null" type. Raw nullable values are preserved for 3.0 documents, so ChangedNullable#getLeft()/getRight() keep their old values there (pinned by the existing SchemaDiffTest#changeNullableHandling).

Only existing verdict rules are used; boolean-sibling handling (3.1 exclusiveMinimum: <value> form) is not touched — that is the numeric-bounds area.

Fixtures and tests

Paired fixtures under core/src/test/resources/oas31/<rule>/ (old/new × 3.0/3.1, same layout as #961):

  • type-change and nullable — the harness's own files, byte-identical, so the two branches merge cleanly; this PR is what un-disables their same-version comparisons there.
  • type-multi — reordering type: [integer, string] → [string, integer] is not a change (set comparison; no 3.0 spelling exists for a multi-type keyword, so the 3.0 pair encodes the no-change baseline).
  • null-removal — dropping "null" from the types follows the same COMPATIBLE verdict as the 3.0 nullable rule.

Oas31TypesNullTest (parameterized): 3.0→3.0 keeps the documented verdict, 3.1→3.1 agrees with it, and the same spec written in 3.0 and in 3.1 diffs to no changes (for the rules whose spellings encode the same document). SchemaTypesTest pins the helper contract on constructed schemas. Cross-version comparisons (3.0 old against 3.1 new) stay with Phase 3 (#951).

Verification

Full suite green: core 289 tests (270 on master, +19 new; same 2 pre-existing skips), maven plugin 13. No existing test changed; 3.0 verdicts are unchanged.

Deliberately out of scope

Signed-off-by: Inf1mum vadimlazuk5@gmail.com


Summary by cubic

Fixes 3.1→3.1 schema comparisons silently missing type changes and nullability changes. The engine compared getType(), which is null for OpenAPI 3.1 schemas (the type keyword is in the types set), so type diffs compared null with null and adding "null" produced no_changes.

Changes

  • New SchemaTypes helper reads the type keyword from both 3.0/Swagger 2.0 (getType()) and 3.1 (getTypes()) shapes.
  • The type gate compares the set of non-null types; type changes still classify as INCOMPATIBLE as in 3.0.
  • "null" routes through the existing null rule and feeds ChangedNullable; 3.0 nullable flag values are preserved.
  • Reordering a multi-type keyword ([integer, string] → [string, integer]) is not a change; cross-version comparisons stay with Phase 3.

Tests

  • Paired 3.0/3.1 fixtures for type-change, nullable, type-multi, and null-removal.
  • 3.1→3.1 verdicts match the documented 3.0 verdicts; the same spec written in both versions diffs to no changes.
  • Full suite green (289 core tests, +19 new); no existing test or 3.0 verdict changed.

Written for commit 6585d84. Summary will update on new commits.

View guided diff

Part of OpenAPITools#950 (Phase 2, area 1 of 4: types and null). The engine picked its
type comparison by the Java class shape: the type gate compared getType(),
which is null for 3.1 schemas whose type keyword lives in the types set
(see also OpenAPITools#938), so same-version 3.1 comparisons silently missed type
changes and nullability changes.

The new SchemaTypes helper in utils reads the type keyword from both shapes
while the phase is in progress: 3.0 and Swagger 2.0 documents carry the
type in getType(), 3.1 documents carry it in getTypes(). The type gate now
compares the set of non-null types, and "null" goes through the existing
null rule only: SchemaDiffResult feeds ChangedNullable with the nullable
flag folded with the 3.1 "null" type, preserving the raw nullable values
for 3.0 documents.

The type-change and nullable fixture pairs under core/src/test/resources/
oas31/ are the Phase 0 harness files (OpenAPITools#961), byte-identical so both
branches merge cleanly; type-multi pins that reordering a multi-type
keyword is not a change, and null-removal pins that dropping "null" from
the types follows the same compatible verdict as the 3.0 nullable rule.
Oas31TypesNullTest asserts the documented 3.0->3.0 verdicts, the same
verdicts for 3.1->3.1, and the written-versions equivalence for the rules
whose spellings encode the same document; SchemaTypesTest pins the helper
contract.

Deliberately left to the other Phase 2 areas or later phases: composed
schema flattening and the addSchema merge (area 4, see OpenAPITools#938), array items
(area 3), numeric bounds (area 2), the path matcher's type equality and
the renderers' getType() display reads, and the cross-version comparisons
(Phase 3, OpenAPITools#951).

Full suite green: core 289 tests (was 270, +19 new), maven plugin 13; the
3.0 verdicts are unchanged.

Signed-off-by: Inf1mum <vadimlazuk5@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

2 issues found across 21 files

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java">

<violation number="1" location="core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java:33">
P2: This test uses Java 9 collection factories even though the project supports Java 8, so the test suite fails on a supported Java 8 runtime before exercising any assertions. Replace `Map.of` and `List.of` with Java 8-compatible collection construction.</violation>
</file>

<file name="core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java">

<violation number="1" location="core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java:31">
P1: The helper misses scalar `"null"` values stored in `Schema#getType()`. Such schemas are not normalized into the nullable rule, so valid 3.1 documents can receive a type verdict or miss a nullability change; exclude `NULL_TYPE` from the scalar type and include it when computing `hasNullType`.</violation>
</file>

Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic

*/
public static Set<String> types(Schema<?> schema) {
Set<String> result = new LinkedHashSet<>();
if (schema.getType() != null) {

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P1: The helper misses scalar "null" values stored in Schema#getType(). Such schemas are not normalized into the nullable rule, so valid 3.1 documents can receive a type verdict or miss a nullability change; exclude NULL_TYPE from the scalar type and include it when computing hasNullType.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java, line 31:

<comment>The helper misses scalar `"null"` values stored in `Schema#getType()`. Such schemas are not normalized into the nullable rule, so valid 3.1 documents can receive a type verdict or miss a nullability change; exclude `NULL_TYPE` from the scalar type and include it when computing `hasNullType`.</comment>

<file context>
@@ -0,0 +1,61 @@
+   */
+  public static Set<String> types(Schema<?> schema) {
+    Set<String> result = new LinkedHashSet<>();
+    if (schema.getType() != null) {
+      result.add(schema.getType());
+    }
</file context>


/** Verdict the engine gives for the rule pair when both documents are 3.0. */
private static final Map<String, DiffResult> VERDICT_30 =
Map.of(

Copy link
Copy Markdown

Choose a reason for hiding this comment

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

P2: This test uses Java 9 collection factories even though the project supports Java 8, so the test suite fails on a supported Java 8 runtime before exercising any assertions. Replace Map.of and List.of with Java 8-compatible collection construction.

Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. When an issue isn't valid or won't be fixed in this PR, reply in its thread with the reason and then resolve the thread. At core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java, line 33:

<comment>This test uses Java 9 collection factories even though the project supports Java 8, so the test suite fails on a supported Java 8 runtime before exercising any assertions. Replace `Map.of` and `List.of` with Java 8-compatible collection construction.</comment>

<file context>
@@ -0,0 +1,94 @@
+
+  /** Verdict the engine gives for the rule pair when both documents are 3.0. */
+  private static final Map<String, DiffResult> VERDICT_30 =
+      Map.of(
+          "null-removal", COMPATIBLE,
+          "nullable", COMPATIBLE,
</file context>

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