diff --git a/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java b/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java index fadae7a1d..c21348e10 100644 --- a/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java +++ b/core/src/main/java/org/openapitools/openapidiff/core/compare/SchemaDiff.java @@ -27,6 +27,7 @@ import org.openapitools.openapidiff.core.model.deferred.RecursiveSchemaSet; import org.openapitools.openapidiff.core.utils.RefPointer; import org.openapitools.openapidiff.core.utils.RefType; +import org.openapitools.openapidiff.core.utils.SchemaTypes; public class SchemaDiff { @@ -350,7 +351,7 @@ public DeferredChanged computeDiffForReal( // SchemaDiffResult and // return the object if ((left == null || right == null) - || !Objects.equals(left.getType(), right.getType()) + || !SchemaTypes.types(left).equals(SchemaTypes.types(right)) || !Objects.equals(left.getFormat(), right.getFormat())) { return getTypeChangedSchema(left, right, context); } diff --git a/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java b/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java index 67d976a33..e65136c95 100644 --- a/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java +++ b/core/src/main/java/org/openapitools/openapidiff/core/compare/schemadiffresult/SchemaDiffResult.java @@ -25,6 +25,7 @@ import org.openapitools.openapidiff.core.model.schema.ChangedReadOnly; import org.openapitools.openapidiff.core.model.schema.ChangedRequired; import org.openapitools.openapidiff.core.model.schema.ChangedUniqueItems; +import org.openapitools.openapidiff.core.utils.SchemaTypes; public class SchemaDiffResult { protected ChangedSchema changedSchema; @@ -79,7 +80,8 @@ public , X> DeferredChanged diff( right.getExclusiveMaximum(), context)) .setMultipleOf(new ChangedMultipleOf(left.getMultipleOf(), right.getMultipleOf())) - .setNullable(new ChangedNullable(left.getNullable(), right.getNullable())) + .setNullable( + new ChangedNullable(SchemaTypes.nullableValue(left), SchemaTypes.nullableValue(right))) .setPattern(new ChangedPattern(left.getPattern(), right.getPattern(), context)) .setUniqueItems(new ChangedUniqueItems(left.getUniqueItems(), right.getUniqueItems())) .setExamples(new ChangedExamples(left.getExamples(), right.getExamples())) diff --git a/core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java b/core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java new file mode 100644 index 000000000..b7714db20 --- /dev/null +++ b/core/src/main/java/org/openapitools/openapidiff/core/utils/SchemaTypes.java @@ -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 types(Schema schema) { + Set 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; + } +} diff --git a/core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java b/core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java new file mode 100644 index 000000000..8cd8f58eb --- /dev/null +++ b/core/src/test/java/org/openapitools/openapidiff/core/Oas31TypesNullTest.java @@ -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. + * + *

Fixtures follow the paired layout of the Phase 0 harness (#961): every rule directory {@code + * core/src/test/resources/oas31//} 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. + * + *

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 VERDICT_30 = + Map.of( + "null-removal", COMPATIBLE, + "nullable", COMPATIBLE, + "type-change", INCOMPATIBLE, + "type-multi", NO_CHANGES); + + private static final List 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 WRITTEN_EQUIVALENCE_RULES = + List.of("null-removal", "nullable", "type-change"); + + static Stream rules() { + return RULES.stream(); + } + + static Stream 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); + } +} diff --git a/core/src/test/java/org/openapitools/openapidiff/core/utils/SchemaTypesTest.java b/core/src/test/java/org/openapitools/openapidiff/core/utils/SchemaTypesTest.java new file mode 100644 index 000000000..a04e0635d --- /dev/null +++ b/core/src/test/java/org/openapitools/openapidiff/core/utils/SchemaTypesTest.java @@ -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(); + } +} diff --git a/core/src/test/resources/oas31/null-removal/new-3.0.yaml b/core/src/test/resources/oas31/null-removal/new-3.0.yaml new file mode 100644 index 000000000..be8480b49 --- /dev/null +++ b/core/src/test/resources/oas31/null-removal/new-3.0.yaml @@ -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 diff --git a/core/src/test/resources/oas31/null-removal/new-3.1.yaml b/core/src/test/resources/oas31/null-removal/new-3.1.yaml new file mode 100644 index 000000000..3b9ed3fbe --- /dev/null +++ b/core/src/test/resources/oas31/null-removal/new-3.1.yaml @@ -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] diff --git a/core/src/test/resources/oas31/null-removal/old-3.0.yaml b/core/src/test/resources/oas31/null-removal/old-3.0.yaml new file mode 100644 index 000000000..e8f489be8 --- /dev/null +++ b/core/src/test/resources/oas31/null-removal/old-3.0.yaml @@ -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 diff --git a/core/src/test/resources/oas31/null-removal/old-3.1.yaml b/core/src/test/resources/oas31/null-removal/old-3.1.yaml new file mode 100644 index 000000000..968dd627f --- /dev/null +++ b/core/src/test/resources/oas31/null-removal/old-3.1.yaml @@ -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"] diff --git a/core/src/test/resources/oas31/nullable/new-3.0.yaml b/core/src/test/resources/oas31/nullable/new-3.0.yaml new file mode 100644 index 000000000..570f5abfb --- /dev/null +++ b/core/src/test/resources/oas31/nullable/new-3.0.yaml @@ -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 diff --git a/core/src/test/resources/oas31/nullable/new-3.1.yaml b/core/src/test/resources/oas31/nullable/new-3.1.yaml new file mode 100644 index 000000000..0b94cb620 --- /dev/null +++ b/core/src/test/resources/oas31/nullable/new-3.1.yaml @@ -0,0 +1,22 @@ +openapi: 3.1.0 +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, "null"] diff --git a/core/src/test/resources/oas31/nullable/old-3.0.yaml b/core/src/test/resources/oas31/nullable/old-3.0.yaml new file mode 100644 index 000000000..12931e13c --- /dev/null +++ b/core/src/test/resources/oas31/nullable/old-3.0.yaml @@ -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: false diff --git a/core/src/test/resources/oas31/nullable/old-3.1.yaml b/core/src/test/resources/oas31/nullable/old-3.1.yaml new file mode 100644 index 000000000..d34ac482c --- /dev/null +++ b/core/src/test/resources/oas31/nullable/old-3.1.yaml @@ -0,0 +1,22 @@ +openapi: 3.1.0 +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] diff --git a/core/src/test/resources/oas31/type-change/new-3.0.yaml b/core/src/test/resources/oas31/type-change/new-3.0.yaml new file mode 100644 index 000000000..91ace4296 --- /dev/null +++ b/core/src/test/resources/oas31/type-change/new-3.0.yaml @@ -0,0 +1,22 @@ +openapi: 3.0.3 +info: + title: oas31 harness fixture (type-change) + 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: + weight: + type: string diff --git a/core/src/test/resources/oas31/type-change/new-3.1.yaml b/core/src/test/resources/oas31/type-change/new-3.1.yaml new file mode 100644 index 000000000..289c69f94 --- /dev/null +++ b/core/src/test/resources/oas31/type-change/new-3.1.yaml @@ -0,0 +1,22 @@ +openapi: 3.1.0 +info: + title: oas31 harness fixture (type-change) + 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: + weight: + type: string diff --git a/core/src/test/resources/oas31/type-change/old-3.0.yaml b/core/src/test/resources/oas31/type-change/old-3.0.yaml new file mode 100644 index 000000000..075a3aa8d --- /dev/null +++ b/core/src/test/resources/oas31/type-change/old-3.0.yaml @@ -0,0 +1,22 @@ +openapi: 3.0.3 +info: + title: oas31 harness fixture (type-change) + 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: + weight: + type: integer diff --git a/core/src/test/resources/oas31/type-change/old-3.1.yaml b/core/src/test/resources/oas31/type-change/old-3.1.yaml new file mode 100644 index 000000000..fbe20717b --- /dev/null +++ b/core/src/test/resources/oas31/type-change/old-3.1.yaml @@ -0,0 +1,22 @@ +openapi: 3.1.0 +info: + title: oas31 harness fixture (type-change) + 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: + weight: + type: integer diff --git a/core/src/test/resources/oas31/type-multi/new-3.0.yaml b/core/src/test/resources/oas31/type-multi/new-3.0.yaml new file mode 100644 index 000000000..961777590 --- /dev/null +++ b/core/src/test/resources/oas31/type-multi/new-3.0.yaml @@ -0,0 +1,22 @@ +openapi: 3.0.3 +info: + title: oas31 harness fixture (type-multi) + 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: + weight: + type: integer diff --git a/core/src/test/resources/oas31/type-multi/new-3.1.yaml b/core/src/test/resources/oas31/type-multi/new-3.1.yaml new file mode 100644 index 000000000..b944cbc46 --- /dev/null +++ b/core/src/test/resources/oas31/type-multi/new-3.1.yaml @@ -0,0 +1,22 @@ +openapi: 3.1.0 +info: + title: oas31 harness fixture (type-multi) + 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: + weight: + type: [string, integer] diff --git a/core/src/test/resources/oas31/type-multi/old-3.0.yaml b/core/src/test/resources/oas31/type-multi/old-3.0.yaml new file mode 100644 index 000000000..961777590 --- /dev/null +++ b/core/src/test/resources/oas31/type-multi/old-3.0.yaml @@ -0,0 +1,22 @@ +openapi: 3.0.3 +info: + title: oas31 harness fixture (type-multi) + 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: + weight: + type: integer diff --git a/core/src/test/resources/oas31/type-multi/old-3.1.yaml b/core/src/test/resources/oas31/type-multi/old-3.1.yaml new file mode 100644 index 000000000..ec728c038 --- /dev/null +++ b/core/src/test/resources/oas31/type-multi/old-3.1.yaml @@ -0,0 +1,22 @@ +openapi: 3.1.0 +info: + title: oas31 harness fixture (type-multi) + 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: + weight: + type: [integer, string]