Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
Original file line number Diff line number Diff line change
Expand Up @@ -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 {

Expand Down Expand Up @@ -350,7 +351,7 @@ public DeferredChanged<ChangedSchema> 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);
}
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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;
Expand Down Expand Up @@ -79,7 +80,8 @@ public <V extends Schema<X>, X> DeferredChanged<ChangedSchema> 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()))
Expand Down
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) {

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>

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;
}
}
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(

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>

"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);
}
}
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();
}
}
23 changes: 23 additions & 0 deletions core/src/test/resources/oas31/null-removal/new-3.0.yaml
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
22 changes: 22 additions & 0 deletions core/src/test/resources/oas31/null-removal/new-3.1.yaml
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]
23 changes: 23 additions & 0 deletions core/src/test/resources/oas31/null-removal/old-3.0.yaml
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
22 changes: 22 additions & 0 deletions core/src/test/resources/oas31/null-removal/old-3.1.yaml
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"]
23 changes: 23 additions & 0 deletions core/src/test/resources/oas31/nullable/new-3.0.yaml
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
Loading