Skip to content

fix: OAS 3.1 schema generation for raw Object properties is controlled with explicit-object-schema flag #5112

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.

Sign up for GitHub

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
Mattias-Sehlstedt wants to merge 1 commit into
base: master
Choose a base branch
from
Open

fix: OAS 3.1 schema generation for raw Object properties is controlled with explicit-object-schema flag #5112

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
12 changes: 7 additions & 5 deletions modules/swagger-core/src/main/java/io/swagger/v3/core/jackson/ModelResolver.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -603,9 +603,7 @@ public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context
} else if (hasCompositionKeywords) {
model = openapi31 ? new JsonSchema() : new ComposedSchema();
model.name(name);
if (
(openapi31 && Boolean.TRUE.equals(PrimitiveType.explicitObjectType)) ||
(!openapi31 && (!Boolean.FALSE.equals(PrimitiveType.explicitObjectType)))) {
if (isExplicitObjectType()) {
if (openapi31 && resolvedArrayAnnotation == null) {
model.addType("object");
} else {
Expand All @@ -621,8 +619,7 @@ public Schema resolve(AnnotatedType annotatedType, ModelConverterContext context
return model;
} else {
model = openapi31 ? new JsonSchema().name(name) : new Schema().name(name);
if ((openapi31 && Boolean.TRUE.equals(PrimitiveType.explicitObjectType)) ||
(!openapi31 && (!Boolean.FALSE.equals(PrimitiveType.explicitObjectType)))) {
if (isExplicitObjectType()) {
if (openapi31 && resolvedArrayAnnotation == null) {
model.addType("object");
} else {
Expand Down Expand Up @@ -3579,4 +3576,9 @@ private boolean isStreamType(JavaType type) {
type.getRawClass() != null &&
java.util.stream.Stream.class.isAssignableFrom(type.getRawClass());
}

private boolean isExplicitObjectType() {
return (openapi31 && Boolean.TRUE.equals(PrimitiveType.explicitObjectType)) ||
(!openapi31 && (!Boolean.FALSE.equals(PrimitiveType.explicitObjectType)));
}
}
2 changes: 1 addition & 1 deletion modules/swagger-core/src/main/java/io/swagger/v3/core/util/PrimitiveType.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -239,7 +239,7 @@ public Schema createProperty() {
}
@Override
public Schema createProperty31() {
return explicitObjectType == null || explicitObjectType ? new JsonSchema().typesItem("object") : new JsonSchema();
return Boolean.TRUE.equals(explicitObjectType) ? new JsonSchema().typesItem("object") : new JsonSchema();
Copy link
Copy Markdown
Contributor Author

@Mattias-Sehlstedt Mattias-Sehlstedt Apr 4, 2026

Choose a reason for hiding this comment

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

This is the main change where null is changed from true to false

}
};

Expand Down
3 changes: 1 addition & 2 deletions ...s/swagger-core/src/test/java/io/swagger/v3/core/resolving/v31/ModelResolverOAS31Test.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -240,8 +240,7 @@ public void testOAS31Fields() {
" creditCard:\n" +
" $ref: \"#/components/schemas/CreditCard\"\n" +
" properties:\n" +
" extraObject:\n" +
" type: object\n" +
" extraObject: {}\n" +
"MultipleBaseBean:\n" +
" type: object\n" +
" description: MultipleBaseBean\n" +
Expand Down
55 changes: 51 additions & 4 deletions ...les/swagger-core/src/test/java/io/swagger/v3/core/serialization/Oas31ObjectFieldTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,7 @@
package io.swagger.v3.core.serialization;

import io.swagger.v3.core.converter.ModelConverters;
import io.swagger.v3.core.util.PrimitiveType;
import io.swagger.v3.oas.models.media.Schema;
import org.testng.Assert;
import org.testng.annotations.Test;
Expand All @@ -9,19 +10,56 @@
import java.util.Map;

public class Oas31ObjectFieldTest {
@Test(description = "Repro #4682: In OAS 3.1, raw Object property should not be rendered as an empty schema")
public void rawObjectPropertyShouldBeObjectSchema() {

@Test(description = "Regression test for #4868: In OAS 3.1, raw Object property should be rendered as an empty schema")
public void rawObjectPropertyShouldBeEmptySchema() {
Map<String, Schema> schemas = ModelConverters.getInstance(true).readAll(PojoUsingObjectField.class);
Schema pojo = schemas.get("PojoUsingObjectField");
Assert.assertNotNull(pojo, "PojoUsingObjectField schema should exist");
Schema myField = (Schema) pojo.getProperties().get("myField");
Assert.assertNotNull(myField, "myField schema should exist");
Assert.assertNull(myField.getTypes(), "Expected raw Object property to be an empty schema in OAS 3.1, but was: type=" + myField.getType() + ", types=" + myField.getTypes() + ", class=" + myField.getClass());
}

@Test(description = "Regression test for #4868: OAS 3.1: List<Object> items schema should be empty")
public void listOfObjectItemsShouldBeEmptySchema() {
Map<String, Schema> schemas = ModelConverters.getInstance(true).readAll(PojoUsingListOfObject.class);
Schema pojo = schemas.get("PojoUsingListOfObject");
Assert.assertNotNull(pojo, "PojoUsingListOfObject schema should exist");
Schema itemsProp = (Schema) pojo.getProperties().get("items");
Assert.assertNotNull(itemsProp, "items property schema should exist");
Schema itemSchema = itemsProp.getItems();
Assert.assertNotNull(itemSchema, "List<Object> items schema should exist");
Assert.assertNull(itemSchema.getTypes(), "Expected List<Object> items to be an empty schema in OAS 3.1, but was: type=" + itemSchema.getType() + ", types=" + itemSchema.getTypes() + ", class=" + itemSchema.getClass());
}

@Test(description = "Regression test for #4868: OAS 3.1: Map<String,Object> additionalProperties schema should be empty")
public void mapOfObjectAdditionalPropertiesShouldBeEmptySchema() {
Map<String, Schema> schemas = ModelConverters.getInstance(true).readAll(PojoUsingMapStringToObject.class);
Schema pojo = schemas.get("PojoUsingMapStringToObject");
Assert.assertNotNull(pojo, "PojoUsingMapStringToObject schema should exist");
Schema additionalProp = (Schema) pojo.getProperties().get("additional");
Assert.assertNotNull(additionalProp, "additional property schema should exist");
Schema valueSchema = (Schema) additionalProp.getAdditionalProperties();
Assert.assertNotNull(valueSchema, "Map<String,Object> additionalProperties (value schema) should exist");
Assert.assertNull(valueSchema.getTypes(), "Expected Map<String,Object> additionalProperties to be an empty schema in OAS 3.1, but was: type=" + valueSchema.getType() + ", types=" + valueSchema.getTypes() + ", class=" + valueSchema.getClass());
}

@Test(description = "Repro #4682: In OAS 3.1, raw Object property should not be rendered as an empty schema if explicit-object-schema is enabled")
public void rawObjectPropertyShouldBeObjectSchema() {
setExplicitTypeObject(true);
Map<String, Schema> schemas = ModelConverters.getInstance(true).readAll(PojoUsingObjectField.class);
Schema pojo = schemas.get("PojoUsingObjectField");
Assert.assertNotNull(pojo, "PojoUsingObjectField schema should exist");
Schema myField = (Schema) pojo.getProperties().get("myField");
Assert.assertNotNull(myField, "myField schema should exist");
Assert.assertTrue(isObjectSchema(myField), "Expected raw Object property to be an object schema in OAS 3.1, but was: type=" + myField.getType() + ", types=" + myField.getTypes() + ", class=" + myField.getClass());
setExplicitTypeObject(null);
}

@Test(description = "OAS 3.1: List<Object> items schema should be object")
@Test(description = "OAS 3.1: List<Object> items schema should be object if explicit-object-schema is enabled")
public void listOfObjectItemsShouldBeObjectSchema() {
setExplicitTypeObject(true);
Map<String, Schema> schemas = ModelConverters.getInstance(true).readAll(PojoUsingListOfObject.class);
Schema pojo = schemas.get("PojoUsingListOfObject");
Assert.assertNotNull(pojo, "PojoUsingListOfObject schema should exist");
Expand All @@ -30,10 +68,12 @@ public void listOfObjectItemsShouldBeObjectSchema() {
Schema itemSchema = itemsProp.getItems();
Assert.assertNotNull(itemSchema, "List<Object> items schema should exist");
Assert.assertTrue(isObjectSchema(itemSchema), "Expected List<Object> items to be an object schema in OAS 3.1, but was: type=" + itemSchema.getType() + ", types=" + itemSchema.getTypes() + ", class=" + itemSchema.getClass());
setExplicitTypeObject(null);
}

@Test(description = "OAS 3.1: Map<String,Object> additionalProperties schema should be object")
@Test(description = "OAS 3.1: Map<String,Object> additionalProperties schema should be object if explicit-object-schema is enabled")
public void mapOfObjectAdditionalPropertiesShouldBeObjectSchema() {
setExplicitTypeObject(true);
Map<String, Schema> schemas = ModelConverters.getInstance(true).readAll(PojoUsingMapStringToObject.class);
Schema pojo = schemas.get("PojoUsingMapStringToObject");
Assert.assertNotNull(pojo, "PojoUsingMapStringToObject schema should exist");
Expand All @@ -42,6 +82,7 @@ public void mapOfObjectAdditionalPropertiesShouldBeObjectSchema() {
Schema valueSchema = (Schema) additionalProp.getAdditionalProperties();
Assert.assertNotNull(valueSchema, "Map<String,Object> additionalProperties (value schema) should exist");
Assert.assertTrue(isObjectSchema(valueSchema), "Expected Map<String,Object> additionalProperties to be an object schema in OAS 3.1, but was: type=" + valueSchema.getType() + ", types=" + valueSchema.getTypes() + ", class=" + valueSchema.getClass());
setExplicitTypeObject(null);
}

/**
Expand Down Expand Up @@ -88,4 +129,10 @@ public void setAdditional(Map<String, Object> additional) {
this.additional = additional;
}
}

// We need to set it programmatically rather than with system properties since the field instantiation is static
// (only read from system env once, thus it cannot be changed/alternated back and forth)
private void setExplicitTypeObject(Boolean value) {
PrimitiveType.explicitObjectType = value;
}
}
5 changes: 0 additions & 5 deletions modules/swagger-jaxrs2/src/test/java/io/swagger/v3/jaxrs2/ReaderTest.java
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -3596,7 +3596,6 @@ public void testOas31Petstore() {
" name:\n" +
" type: string\n" +
" annotated:\n" +
" type: object\n" +
" $ref: \"#/components/schemas/Category\"\n" +
" description: child description\n" +
" properties:\n" +
Expand Down Expand Up @@ -3650,7 +3649,6 @@ public void test31RefSiblings() {
" type: object\n" +
" properties:\n" +
" annotated:\n" +
" type: object\n" +
" $ref: \"#/components/schemas/SimpleCategory\"\n" +
" description: child description\n" +
" properties:\n" +
Expand Down Expand Up @@ -4113,7 +4111,6 @@ public void testMisc31() {
" type: object\n" +
" properties:\n" +
" country:\n" +
" type: object\n" +
" const: United States\n" +
" CreditCard:\n" +
" type: object\n" +
Expand All @@ -4124,13 +4121,11 @@ public void testMisc31() {
" type: object\n" +
" properties:\n" +
" postalCode:\n" +
" type: object\n" +
" pattern: \"[0-9]{5}(-[0-9]{4})?\"\n" +
" PostalCodePattern:\n" +
" type: object\n" +
" properties:\n" +
" postalCode:\n" +
" type: object\n" +
" pattern: \"[A-Z][0-9][A-Z] [0-9][A-Z][0-9]\"\n" +
" PropertyNamesPattern:\n" +
" pattern: \"^[A-Za-z_][A-Za-z0-9_]*$\"\n";
Expand Down
6 changes: 2 additions & 4 deletions modules/swagger-jaxrs2/src/test/resources/petstore/WebHookResource.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -24,11 +24,9 @@ webhooks:
$comment: random comment
$id: http://yourdomain.com/schemas/myschema.json
dependentSchemas:
pet:
type: object
pet: {}
patternProperties:
user:
type: object
user: {}
webhook1:
post:
description: "subscribes a client to updates relevant to the requestor's account,\
Expand Down
6 changes: 2 additions & 4 deletions modules/swagger-jaxrs2/src/test/resources/petstore/callbacks/ComplexCallback31Resource.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,11 +32,9 @@ paths:
$comment: random comment
$id: http://yourdomain.com/schemas/myschema.json
dependentSchemas:
pet:
type: object
pet: { }
patternProperties:
user:
type: object
user: { }
testCallback2:
http://www.url2.com:
get:
Expand Down
3 changes: 1 addition & 2 deletions modules/swagger-jaxrs2/src/test/resources/petstore/parameters/Parameters31Resource.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -96,8 +96,7 @@ paths:
user:
$ref: "#/components/schemas/User"
properties:
extraObject:
type: object
extraObject: {}
components:
schemas:
Category:
Expand Down
12 changes: 4 additions & 8 deletions modules/swagger-jaxrs2/src/test/resources/petstore/requestbody/RequestBody31Resource.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -40,20 +40,16 @@ paths:
- string
- number
- object
if:
type: object
then:
type: object
else:
type: object
if: {}
then: {}
else: {}
$anchor: parameter $anchor
$schema: parameter $schema
description: User description
example: User Description
exclusiveMaximum: 100
exclusiveMinimum: 1
unevaluatedProperties:
type: object
unevaluatedProperties: {}
required: true
responses:
default:
Expand Down