Repository navigation
Read the OpenAPI 3.1 type keyword in the type and null rules #963
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Open
Inf1mum
wants to merge
1
commit into
OpenAPITools:master
Choose a base branch
from
Inf1mum:feat/950-phase2-types-null
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
61 changes: 61 additions & 0 deletions
61
core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,61 @@ | ||
| package org.openapitools.openapidiff.core.utils; | ||
|
|
||
| import io.swagger.v3.oas.models.media.Schema; | ||
| import java.util.LinkedHashSet; | ||
| import java.util.Set; | ||
|
|
||
| /** | ||
| * Reads the type keyword from the two shapes the engine sees while the OpenAPI 3.1 phase is in | ||
| * progress. In 3.0 (and Swagger 2.0) documents the parser stores the type in {@link | ||
| * Schema#getType()}; in 3.1 documents the type keyword lands in the {@link Schema#getTypes()} set | ||
| * and {@code getType()} is null. The helpers in this class accept both shapes and split the keyword | ||
| * into the two things the engine reasons about: the set of non-null types, and whether null is one | ||
| * of them. While the phase is in progress both shapes are accepted, so 3.0 documents keep their | ||
| * current verdicts. | ||
| */ | ||
| public class SchemaTypes { | ||
|
|
||
| /** The JSON Schema 2020-12 type value that stands for null. */ | ||
| public static final String NULL_TYPE = "null"; | ||
|
|
||
| private SchemaTypes() {} | ||
|
|
||
| /** | ||
| * The effective set of non-null types of a schema: the 3.0 {@code type} string and the 3.1 {@code | ||
| * types} entries, minus {@value #NULL_TYPE}. "null" never appears here; nullability goes through | ||
| * the null rule ({@link #nullableValue(Schema)}) instead. Returns an empty set when the schema | ||
| * carries no type keyword, so two untyped schemas compare as equal. | ||
| */ | ||
| public static Set<String> types(Schema<?> schema) { | ||
| Set<String> result = new LinkedHashSet<>(); | ||
| if (schema.getType() != null) { | ||
| result.add(schema.getType()); | ||
| } | ||
| if (schema.getTypes() != null) { | ||
| for (String type : schema.getTypes()) { | ||
| if (type != null && !NULL_TYPE.equals(type)) { | ||
| result.add(type); | ||
| } | ||
| } | ||
| } | ||
| return result; | ||
| } | ||
|
|
||
| /** Whether the 3.1 types set contains {@value #NULL_TYPE}. */ | ||
| public static boolean hasNullType(Schema<?> schema) { | ||
| return schema.getTypes() != null && schema.getTypes().contains(NULL_TYPE); | ||
| } | ||
|
|
||
| /** | ||
| * The value the null rule compares: the 3.0 {@code nullable} flag when it is set, otherwise | ||
| * whether {@value #NULL_TYPE} is one of the 3.1 types. Returns null when the schema says nothing | ||
| * about nullability, so the compared values keep the raw nullable flag exactly as before for 3.0 | ||
| * documents. | ||
| */ | ||
| public static Boolean nullableValue(Schema<?> schema) { | ||
| if (schema.getNullable() != null) { | ||
| return schema.getNullable(); | ||
| } | ||
| return hasNullType(schema) ? Boolean.TRUE : null; | ||
| } | ||
| } | ||
94 changes: 94 additions & 0 deletions
94
core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,94 @@ | ||
| package org.openapitools.openapidiff.core; | ||
|
|
||
| import static org.assertj.core.api.Assertions.assertThat; | ||
| import static org.openapitools.openapidiff.core.model.DiffResult.COMPATIBLE; | ||
| import static org.openapitools.openapidiff.core.model.DiffResult.INCOMPATIBLE; | ||
| import static org.openapitools.openapidiff.core.model.DiffResult.NO_CHANGES; | ||
|
|
||
| import java.util.List; | ||
| import java.util.Map; | ||
| import java.util.stream.Stream; | ||
| import org.junit.jupiter.api.DisplayName; | ||
| import org.junit.jupiter.params.ParameterizedTest; | ||
| import org.junit.jupiter.params.provider.MethodSource; | ||
| import org.openapitools.openapidiff.core.model.DiffResult; | ||
|
|
||
| /** | ||
| * Area 1 of Phase 2 of the OpenAPI 3.1 plan (issue #950): the engine reads the type keyword from | ||
| * the types set and routes "null" through the null rule. | ||
| * | ||
| * <p>Fixtures follow the paired layout of the Phase 0 harness (#961): every rule directory {@code | ||
| * core/src/test/resources/oas31/<rule>/} holds the same minimal document as old-3.0.yaml/ | ||
| * new-3.0.yaml and old-3.1.yaml/new-3.1.yaml. The type-change and nullable pairs are the same files | ||
| * the harness carries; the Phase 2 area-1 fix un-disables their same-version comparisons there. | ||
| * | ||
| * <p>Acceptance: a 3.1 document gives the same verdict as the same change written in 3.0, and the | ||
| * same spec written in 3.0 and in 3.1 diffs to no changes. Cross-version comparisons (3.0 old | ||
| * against 3.1 new) stay with Phase 3 (#951). | ||
| */ | ||
| class Oas31TypesNullTest { | ||
|
|
||
| /** Verdict the engine gives for the rule pair when both documents are 3.0. */ | ||
| private static final Map<String, DiffResult> VERDICT_30 = | ||
| Map.of( | ||
|
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 Prompt for AI agents |
||
| "null-removal", COMPATIBLE, | ||
| "nullable", COMPATIBLE, | ||
| "type-change", INCOMPATIBLE, | ||
| "type-multi", NO_CHANGES); | ||
|
|
||
| private static final List<String> RULES = | ||
| List.of("null-removal", "nullable", "type-change", "type-multi"); | ||
|
|
||
| /** | ||
| * Rules whose 3.0 and 3.1 spellings encode the same document. The multi-type keyword has no 3.0 | ||
| * spelling, so for type-multi the two versions are different specs and the written-versions | ||
| * equivalence does not apply. | ||
| */ | ||
| private static final List<String> WRITTEN_EQUIVALENCE_RULES = | ||
| List.of("null-removal", "nullable", "type-change"); | ||
|
|
||
| static Stream<String> rules() { | ||
| return RULES.stream(); | ||
| } | ||
|
|
||
| static Stream<String> writtenEquivalenceRules() { | ||
| return WRITTEN_EQUIVALENCE_RULES.stream(); | ||
| } | ||
|
|
||
| private static DiffResult verdict(String oldSpec, String newSpec) { | ||
| return OpenApiCompare.fromLocations(oldSpec, newSpec).isChanged(); | ||
| } | ||
|
|
||
| private static DiffResult verdict30to30(String rule) { | ||
| return verdict("oas31/" + rule + "/old-3.0.yaml", "oas31/" + rule + "/new-3.0.yaml"); | ||
| } | ||
|
|
||
| private static DiffResult verdict31to31(String rule) { | ||
| return verdict("oas31/" + rule + "/old-3.1.yaml", "oas31/" + rule + "/new-3.1.yaml"); | ||
| } | ||
|
|
||
| /** The 3.0->3.0 comparison detects the change with the documented verdict. */ | ||
| @ParameterizedTest(name = "{0}: 3.0->3.0 keeps its documented verdict") | ||
| @MethodSource("rules") | ||
| void changeDetectedIn30WithDocumentedVerdict(String rule) { | ||
| assertThat(verdict30to30(rule)).isEqualTo(VERDICT_30.get(rule)); | ||
| } | ||
|
|
||
| /** The 3.1->3.1 comparison of the same change agrees with the 3.0 verdict. */ | ||
| @ParameterizedTest(name = "{0}: 3.1->3.1 agrees with the 3.0 verdict") | ||
| @MethodSource("rules") | ||
| void sameVerdictIn31AsIn30(String rule) { | ||
| assertThat(verdict31to31(rule)).isEqualTo(verdict30to30(rule)); | ||
| } | ||
|
|
||
| /** The same document written in 3.0 and in 3.1 diffs to no changes. */ | ||
| @ParameterizedTest(name = "{0}: the 3.0 and 3.1 spellings agree") | ||
| @MethodSource("writtenEquivalenceRules") | ||
| @DisplayName("written versions agree") | ||
| void writtenVersionsAgree(String rule) { | ||
| assertThat(verdict("oas31/" + rule + "/old-3.0.yaml", "oas31/" + rule + "/old-3.1.yaml")) | ||
| .isEqualTo(NO_CHANGES); | ||
| assertThat(verdict("oas31/" + rule + "/new-3.0.yaml", "oas31/" + rule + "/new-3.1.yaml")) | ||
| .isEqualTo(NO_CHANGES); | ||
| } | ||
| } | ||
75 changes: 75 additions & 0 deletions
75
core/src/test/java/org/openapitools/openapidiff/core/utils/SchemaTypesTest.java
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,75 @@ | ||
| package org.openapitools.openapidiff.core.utils; | ||
|
|
||
| import static org.assertj.core.api.Assertions.assertThat; | ||
|
|
||
| import io.swagger.v3.oas.models.media.JsonSchema; | ||
| import io.swagger.v3.oas.models.media.Schema; | ||
| import io.swagger.v3.oas.models.media.StringSchema; | ||
| import java.util.LinkedHashSet; | ||
| import java.util.Set; | ||
| import org.junit.jupiter.api.Test; | ||
|
|
||
| /** The helper reads both shapes the engine sees while the 3.1 phase is in progress (#950). */ | ||
| class SchemaTypesTest { | ||
|
|
||
| @Test | ||
| void readsThe30TypeString() { | ||
| Schema<?> schema = new StringSchema(); | ||
| assertThat(SchemaTypes.types(schema)).containsExactly("string"); | ||
| assertThat(SchemaTypes.hasNullType(schema)).isFalse(); | ||
| } | ||
|
|
||
| @Test | ||
| void readsThe31TypesSet() { | ||
| JsonSchema schema = new JsonSchema(); | ||
| schema.setTypes(new LinkedHashSet<>(Set.of("integer", "string"))); | ||
| assertThat(SchemaTypes.types(schema)).containsExactlyInAnyOrder("integer", "string"); | ||
| assertThat(SchemaTypes.hasNullType(schema)).isFalse(); | ||
| } | ||
|
|
||
| @Test | ||
| void splitsNullOutOfTheTypesSet() { | ||
| JsonSchema schema = new JsonSchema(); | ||
| schema.setTypes(new LinkedHashSet<>(Set.of("string", SchemaTypes.NULL_TYPE))); | ||
| assertThat(SchemaTypes.types(schema)).containsExactly("string"); | ||
| assertThat(SchemaTypes.hasNullType(schema)).isTrue(); | ||
| } | ||
|
|
||
| @Test | ||
| void unionsBothShapesWhenBothAreSet() { | ||
| Schema<?> schema = new Schema<>(); | ||
| schema.setType("string"); | ||
| schema.setTypes(new LinkedHashSet<>(Set.of("integer"))); | ||
| assertThat(SchemaTypes.types(schema)).containsExactlyInAnyOrder("string", "integer"); | ||
| } | ||
|
|
||
| @Test | ||
| void anUntypedSchemaComparesAsEmpty() { | ||
| assertThat(SchemaTypes.types(new Schema<>())).isEmpty(); | ||
| } | ||
|
|
||
| @Test | ||
| void nullableValueKeepsTheRaw30Flag() { | ||
| Schema<?> schema = new StringSchema(); | ||
| schema.setNullable(false); | ||
| assertThat(SchemaTypes.nullableValue(schema)).isFalse(); | ||
| schema.setNullable(true); | ||
| assertThat(SchemaTypes.nullableValue(schema)).isTrue(); | ||
| } | ||
|
|
||
| @Test | ||
| void nullableValueReadsThe31NullType() { | ||
| JsonSchema schema = new JsonSchema(); | ||
| assertThat(SchemaTypes.nullableValue(schema)).isNull(); | ||
| schema.setTypes(new LinkedHashSet<>(Set.of("string", SchemaTypes.NULL_TYPE))); | ||
| assertThat(SchemaTypes.nullableValue(schema)).isTrue(); | ||
| } | ||
|
|
||
| @Test | ||
| void theRawNullableFlagWinsOverTheNullType() { | ||
| JsonSchema schema = new JsonSchema(); | ||
| schema.setNullable(false); | ||
| schema.setTypes(new LinkedHashSet<>(Set.of("string", SchemaTypes.NULL_TYPE))); | ||
| assertThat(SchemaTypes.nullableValue(schema)).isFalse(); | ||
| } | ||
| } |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| openapi: 3.0.3 | ||
| info: | ||
| title: oas31 harness fixture (null-removal) | ||
| version: "1.0" | ||
| paths: | ||
| /things: | ||
| get: | ||
| operationId: getThing | ||
| responses: | ||
| "200": | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/Thing" | ||
| components: | ||
| schemas: | ||
| Thing: | ||
| type: object | ||
| properties: | ||
| notes: | ||
| type: string | ||
| nullable: false |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| openapi: 3.1.0 | ||
| info: | ||
| title: oas31 harness fixture (null-removal) | ||
| version: "1.0" | ||
| paths: | ||
| /things: | ||
| get: | ||
| operationId: getThing | ||
| responses: | ||
| "200": | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/Thing" | ||
| components: | ||
| schemas: | ||
| Thing: | ||
| type: object | ||
| properties: | ||
| notes: | ||
| type: [string] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| openapi: 3.0.3 | ||
| info: | ||
| title: oas31 harness fixture (null-removal) | ||
| version: "1.0" | ||
| paths: | ||
| /things: | ||
| get: | ||
| operationId: getThing | ||
| responses: | ||
| "200": | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/Thing" | ||
| components: | ||
| schemas: | ||
| Thing: | ||
| type: object | ||
| properties: | ||
| notes: | ||
| type: string | ||
| nullable: true |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,22 @@ | ||
| openapi: 3.1.0 | ||
| info: | ||
| title: oas31 harness fixture (null-removal) | ||
| version: "1.0" | ||
| paths: | ||
| /things: | ||
| get: | ||
| operationId: getThing | ||
| responses: | ||
| "200": | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/Thing" | ||
| components: | ||
| schemas: | ||
| Thing: | ||
| type: object | ||
| properties: | ||
| notes: | ||
| type: [string, "null"] |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,23 @@ | ||
| openapi: 3.0.3 | ||
| info: | ||
| title: oas31 harness fixture (nullable) | ||
| version: "1.0" | ||
| paths: | ||
| /things: | ||
| get: | ||
| operationId: getThing | ||
| responses: | ||
| "200": | ||
| description: OK | ||
| content: | ||
| application/json: | ||
| schema: | ||
| $ref: "#/components/schemas/Thing" | ||
| components: | ||
| schemas: | ||
| Thing: | ||
| type: object | ||
| properties: | ||
| notes: | ||
| type: string | ||
| nullable: true |
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
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 inSchema#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; excludeNULL_TYPEfrom the scalar type and include it when computinghasNullType.Prompt for AI agents