fix: OAS 3.1 schema generation for raw Object properties by xeulbn · Pull Request #5034 · swagger-api/swagger-core (original) (raw)

Conversation

Pull Request

Thank you for contributing to swagger-core!

Please fill out the following information to help us review your PR efficiently.

Description

Related issue: #4682
This PR fixes an issue in OpenAPI 3.1 schema generation where properties
declared as raw Java Object were rendered as an empty schema ({}).

In the OAS 3.1 path, PrimitiveType.OBJECT#createProperty31() returned an empty
JsonSchema without populating Schema#types. Since OpenAPI 3.1 relies on
JSON Schema semantics and uses types during serialization, the missing type
information caused the schema to be emitted as {}.

To resolve this, the OAS 3.1 schema generation for raw Object types has been
updated to explicitly set types = ["object"].

Additionally, regression tests have been added to cover:

• raw Object properties
• List<Object> item schemas
• Map<String, Object> additionalProperties schemas

Fixes: #4682

Type of Change

• 🐛 Bug fix
• 🧪 Tests

Checklist

• I have added/updated tests as needed
• The PR title is descriptive
• The code builds and passes tests locally
• I have linked related issues (if any)

Screenshots / Additional Context

The tests were executed locally with:

mvn -pl modules/swagger-core -Dtest=ObjectFieldOas31ReproTest test

Before (OAS 3.1)

After (OAS 3.1)

xeulbn changed the titleFix OAS 3.1 schema generation for raw Object properties fix : OAS 3.1 schema generation for raw Object properties

Jan 10, 2026

xeulbn changed the titlefix : OAS 3.1 schema generation for raw Object properties fix: OAS 3.1 schema generation for raw Object properties

Jan 10, 2026

@xeulbn please also check for errors in builds and code scanning jobs.

Sorry I missed the comment before the build test.
I’ll check the build results and update the commit accordingly.

The build failure was caused by the updated OAS 3.1 handling for raw Object, which changes the expected YAML output in ModelResolverOAS31Test:

• status type: [string, number] → [object, string, number]
• extraObject: {} → { type: object }

I updated the OAS 3.1 expected output accordingly.

Verified locally on JDK 17 with:
mvn -pl modules/swagger-core test

All tests passed.
Thanks for the review and the helpful feedback!

Another build failure was caused by the updated OAS 3.1 handling for raw Object, which changes the expected YAML output in several OAS 3.1 test resources and reader tests.

Empty object schemas are now consistently rendered as type: object, and union types inferred from raw Object include object in addition to the previously inferred primitive types.

I updated the affected OAS 3.1 YAML expectations and reader tests accordingly.

In OpenAPI 3.1, type may be a union (Schema#types).

Previously, inferred types (e.g. object from raw Java Object) were merged with
explicit @Schema(types=...), which could unintentionally widen the declared union.

While looking into this, I considered an explicit @Schema(types=...) declaration
as an intention to fully define the allowed types, rather than to merge them with
inferred defaults. Based on that interpretation, this change ignores inferred types
when types is explicitly provided, while preserving inferred object when it is not.

Tests were updated accordingly.

@xeulbn thank you for your PR and for taking the time to contribute to the community. Your effort are truly appreciated!

Thank you for the review and guidance throughout the process.

I appreciate the detailed feedback — it helped me better understand the differences between OAS 3.0 and 3.1 schema handling.
Looking forward to contributing more in the future!

Hi, the changes introduced in this PR seem to conflict with what has previously controlled with the explicit setting "explicit-object-schema", which was introduced and described in #4868 (comment).

Further, now a Map<String, Object> becomes

"additionalProperties": { "type": "object" }

Rather than the previous

"additionalProperties": {}

I can see from the tests that this is intentional. But to my knowledge this new schema expresses a new type of restriction on the request. For example the request

Is now an invalid request, since "value" is not a JSON-object.

So the addition of "type": "object" more aligns with a Java representation that is Map<String, Map<String, Object>>.

Would it be considered correct if I investigated how to best revert the change for a additionalProperties field?

Thanks for raising this.

I think that is a fair point. My intention with this change was to improve how raw Object is represented in OAS 3.1, especially to avoid cases where it was rendered as an empty schema unintentionally.

That said, I agree additionalProperties may be a special case. For Map<String, Object>, changing

"additionalProperties": {}
to
"additionalProperties": { "type": "object" }

can indeed narrow the allowed values and change the schema semantics in a way that is closer to Map<String, Map<String, Object>>.

So I would not see this as invalidating the overall change, but I do think it makes sense to investigate reverting or refining the behavior specifically for additionalProperties.

This was referenced

Apr 4, 2026

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

[ Show hidden characters]({{ revealButtonHref }})

Labels