[JAVA, JAVA-SPRING, KOTLIN-CLIENT, KOTLIN-SPRING] - feature - add x-jackson-default-impl / typeInfoDefaultImpls support to allow specifying of fallback schema when deserializing by Picazsoo · Pull Request #23955 · OpenAPITools/openapi-generator

Picazsoo · 2026-06-05T13:29:31Z

Purpose

Complements the current oneOf Jackson polymorphism by making it possible to supply a default fallback value for deserialization. This is useful e.g. when you want to specify a default for deduction-based polymorphism (FasterXML/jackson-databind#3055), or when you want to fall back to some no-op class.

This feature is fully opt-in and has no effect on existing usage. Generated output is unchanged unless you explicitly set x-jackson-default-impl or typeInfoDefaultImpls.

What it adds

Emits @JsonTypeInfo(defaultImpl = ...) on polymorphic oneOf interfaces. Two opt-in ways to configure it (both default to disabled):

Vendor extension x-jackson-default-impl: <ClassName> on a schema.
Generator option typeInfoDefaultImpls: {SchemaName: ClassName}, which overrides the vendor extension when both are set for the same schema.

Class names are resolved via toModelName (honoring model mappings and DTO prefix/suffix); warns on overrides and unknown targets.

Scope

Generator	Support
`java` (client)	deduction + discriminator
`spring`	deduction + discriminator
`kotlin-spring`	deduction + discriminator
`kotlin` (client)	discriminator only
`java-microprofile`	disabled (template doesn't route through oneOf interface)

Resolution is centralized in AbstractJavaCodegen (shared by Java + Spring). Templates only emit defaultImpl when a value is resolved, so output is byte-for-byte identical to before for anyone who doesn't opt in.

Tests & docs

Tests added for Java client, Spring, kotlin-spring, and kotlin client, covering deduction/discriminator cases, config override, model-name suffix handling, and a noDefaultImplWhenNeitherSourceIsSet case that confirms no change when unconfigured.
New shared test spec 3_0/spring/jackson-default-impl.yaml.
Docs updated for java, spring, kotlin-spring, kotlin, and java-camel; new x-jackson-default-impl vendor extension registered.

PR checklist

Read the contribution guidelines.
Run the following to build the project and update samples:
```
./mvnw clean package || exit
./bin/generate-samples.sh ./bin/configs/*.yaml || exit
./bin/utils/export_docs_generators.sh || exit
```
(For Windows users, please run the script in WSL)
Commit all changed files.
This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
These must match the expectations made by your contribution.
You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request. - tagging kotlin, java, java-spring committee members: @bbdouglas, @sreeshas, @jfiala, @lukoyanov, @cbornet, @jeff9finger, @karismann, @Zomzog, @lwlee2608, @martin-mfg, @cachescrubber, @welshm, @MelleD, @atextor, @manedev79, @javisst, @borsch, @banlevente, @andrewemery, @4brunu, @yutaka0m, @stefankoppier, @e5l, @dennisameling

Summary by cubic

Adds opt-in Jackson default deserialization for oneOf interfaces. Previously no default was set; now @JsonTypeInfo(defaultImpl=...) is emitted when configured, with no change when unconfigured.

Resolves x-jackson-default-impl and typeInfoDefaultImpls in AbstractJavaCodegen to x-jackson-resolved-default-impl, honoring toModelName, schema/import mappings, and DTO prefix/suffix. typeInfoDefaultImpls overrides the vendor extension and warns on shadowed/unknown targets.
Emission:
- Java and Spring: defaultImpl for both Id.NAME (discriminator) and Id.DEDUCTION.
- kotlin-spring: supports both deduction and discriminator.
- kotlin client: discriminator-only.
- java-microprofile: disabled.
Templates updated to include defaultImpl in type-info annotations across Java, Spring, kotlin-spring, and kotlin client.
Option registered in CodegenConstants (TYPE_INFO_DEFAULT_IMPLS) and documented across generators; added samples and CI for Java RestClient, Spring Boot, kotlin-spring, kotlin client, and java-camel.
Tests added for Java client, Spring, kotlin-spring, and kotlin client covering deduction/discriminator cases and config precedence.

Migration

To enable a default fallback, set x-jackson-default-impl: ClassName on a schema or configure typeInfoDefaultImpls: {SchemaName: ClassName}; the config option overrides the extension.
No action required if you do not opt in.

^{Written for commit 8d5365a. Summary will update on new commits.}

…foDefaultImpls support Emit `@JsonTypeInfo(defaultImpl = ...)` for both deduction-based and discriminator-based oneOf interfaces. Two configuration sources (config option takes precedence): - Schema extension: `x-jackson-default-impl: ClassName` - Config option: `typeInfoDefaultImpls: {SchemaName: ClassName}` The resolved class name passes through `toModelName()` so schemaMapping, importMapping, and DTO prefix/suffix are all honoured. A LOGGER.warn is emitted when the config option shadows a schema-level annotation.

cubic-dev-ai

1 issue found across 9 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

jpfinne · 2026-06-05T14:49:22Z

    public static final String USE_SEALED_RESPONSE_INTERFACES = "useSealedResponseInterfaces";
    public static final String COMPANION_OBJECT = "companionObject";
    public static final String SUSPEND_FUNCTIONS = "suspendFunctions";
+    public static final String TYPE_INFO_DEFAULT_IMPLS = "typeInfoDefaultImpls";


Move to CodegenConstants ?

@Picazsoo Could you also add the feature to the java generators?
See src/main/resources/Java/deductionAnnotation.mustache and the different typeInfoAnnotation.mustache under java/libraries

I will take a look at it. And this is early implementation without any polish. I marked temporarily as "ready for review" just to gather early feedback from Cubic

But thanks for the review! I will properly tag you once I think it is ready for wasting human review time (-:

Hi @jpfinne, I added it to the java generators as well.

This is now ready for review

# Conflicts: # modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java

…Java generators - Add TYPE_INFO_DEFAULT_IMPLS/DESC constants to CodegenConstants (addresses reviewer request to avoid duplication across SpringCodegen and KotlinSpringServerCodegen) - Move typeInfoDefaultImpls field, option registration, processOpts parsing, and x-jackson-resolved-default-impl resolution loop from SpringCodegen into AbstractJavaCodegen so all Java generators inherit the feature - Remove duplicated code from SpringCodegen; update KotlinSpringServerCodegen to reference CodegenConstants.TYPE_INFO_DEFAULT_IMPLS and apply the same safe instanceof cast fix already present in SpringCodegen - Update Java/deductionAnnotation.mustache: emit defaultImpl = X.class on @JsonTypeInfo(use = DEDUCTION) when x-jackson-resolved-default-impl is set - Update Java/typeInfoAnnotation.mustache: emit defaultImpl = X.class on both @JsonTypeInfo(use = NAME) variants (discriminator present/absent) via discriminator.vendorExtensions.x-jackson-resolved-default-impl - Add JavaClientCodegenTest tests covering deduction, discriminator, typeInfoDefaultImpls config option, and absence cases for Java client Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

cubic-dev-ai

All reported issues were addressed across 17 files

_{Reply with feedback, questions, or to request a fix.

Re-trigger cubic}

cubic-dev-ai

9 issues found across 27 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="modules/openapi-generator/src/main/resources/kotlin-spring/typeInfoAnnotation.mustache">

<violation number="1" location="modules/openapi-generator/src/main/resources/kotlin-spring/typeInfoAnnotation.mustache:6">
P1: Missing validation that the resolved defaultImpl is a subtype of the polymorphic base; misconfigured `x-jackson-default-impl` or `typeInfoDefaultImpls` values will compile but fail at runtime during deserialization.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

# Conflicts: # modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

Picazsoo · 2026-07-01T12:49:27Z

Tagging @wing328 - please consider if this contribution makes sense and if it would make sense for 7.24.0

# Conflicts: # docs/generators/kotlin-spring.md # docs/generators/kotlin.md # modules/openapi-generator/src/test/java/org/openapitools/codegen/java/JavaClientCodegenTest.java # modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

cubic-dev-ai

All reported issues were addressed across 333 files

_{Note: This PR contains a large number of files. cubic only reviews up to 200 files per PR, so some files may not have been reviewed. cubic prioritizes the most important files to review.

Re-trigger cubic}

cubic-dev-ai

All reported issues were addressed across 74 files (changes from recent commits).

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

Picazsoo · 2026-08-08T07:07:36Z

Hi @wing328 , I wonder if this feature is acceptable or not as is?

…on-default # Conflicts: # docs/generators/java-camel.md # docs/generators/spring.md # modules/openapi-generator/src/main/java/org/openapitools/codegen/VendorExtension.java # modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

cubic-dev-ai

2 issues found across 30 files (changes from recent commits).

Prompt for AI agents (unresolved issues)


Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="samples/server/petstore/kotlin-spring-oneof-jackson-default-impl/src/main/kotlin/org/openapitools/model/Soda.kt">

<violation number="1">
P2: This sample regeneration removes `@JsonInclude(NON_NULL)` and `@JsonSetter(nulls = Nulls.SKIP)` from the optional nullable field `sugarGrams`, so the generated `Soda` model will now serialize `"sugarGrams": null` instead of dropping the key when the field is null. This null-handling change is unrelated to the defaultImpl feature and contradicts the PR's stated 'no behavioral change unless opt-in / byte-for-byte identical' guarantee. Confirm this is an intended generator-output change (and matches what the generator actually emits) rather than an unintended side effect of the sample regeneration; if the generator change is spurious it should be reverted in the templates, otherwise update the PR description which claims output is otherwise unchanged.</violation>
</file>

<file name="samples/openapi3/server/petstore/spring-boot-oneof-jackson-default-impl/src/main/java/org/openapitools/model/Apple.java">

<violation number="1">
P2: This regeneration drops `@JsonInclude(JsonInclude.Include.NON_NULL)` from the optional `seeds` field (spec `type: integer`, non-nullable). With the annotation removed, a null `seeds` is now serialized as `"seeds": null` where it was previously omitted. This contradicts the generator's own matrix (optional & non-nullable -> NON_NULL in JsonAnnotationPolicyUtils.resolveJsonIncludePolicy) and diverges from sibling samples (spring-boot-oneof `Pizza.pizzaSize` and spring-boot-springdoc `Tag.id` keep NON_NULL on equivalent optional fields). Restore the annotation and the JsonInclude import, or regenerate the sample under the same config as the sibling samples.</violation>
</file>

_{Tip: Review your code locally with the cubic CLI to iterate faster.

Re-trigger cubic}

cubic-dev-ai · 2026-08-13T18:38:10Z

@@ -0,0 +1,33 @@
+package org.openapitools.model


P2: This sample regeneration removes @JsonInclude(NON_NULL) and @JsonSetter(nulls = Nulls.SKIP) from the optional nullable field sugarGrams, so the generated Soda model will now serialize "sugarGrams": null instead of dropping the key when the field is null. This null-handling change is unrelated to the defaultImpl feature and contradicts the PR's stated 'no behavioral change unless opt-in / byte-for-byte identical' guarantee. Confirm this is an intended generator-output change (and matches what the generator actually emits) rather than an unintended side effect of the sample regeneration; if the generator change is spurious it should be reverted in the templates, otherwise update the PR description which claims output is otherwise unchanged.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/server/petstore/kotlin-spring-oneof-jackson-default-impl/src/main/kotlin/org/openapitools/model/Soda.kt, line 32: <comment>This sample regeneration removes `@JsonInclude(NON_NULL)` and `@JsonSetter(nulls = Nulls.SKIP)` from the optional nullable field `sugarGrams`, so the generated `Soda` model will now serialize `"sugarGrams": null` instead of dropping the key when the field is null. This null-handling change is unrelated to the defaultImpl feature and contradicts the PR's stated 'no behavioral change unless opt-in / byte-for-byte identical' guarantee. Confirm this is an intended generator-output change (and matches what the generator actually emits) rather than an unintended side effect of the sample regeneration; if the generator change is spurious it should be reverted in the templates, otherwise update the PR description which claims output is otherwise unchanged.</comment> <file context> @@ -1,10 +1,7 @@ package org.openapitools.model import java.util.Objects -import com.fasterxml.jackson.annotation.JsonInclude import com.fasterxml.jackson.annotation.JsonProperty -import com.fasterxml.jackson.annotation.JsonSetter -import com.fasterxml.jackson.annotation.Nulls import com.fasterxml.jackson.annotation.JsonIgnoreProperties import com.fasterxml.jackson.annotation.JsonSubTypes </file context>

cubic-dev-ai · 2026-08-13T18:38:10Z

@@ -0,0 +1,121 @@
+package org.openapitools.model;


P2: This regeneration drops @JsonInclude(JsonInclude.Include.NON_NULL) from the optional seeds field (spec type: integer, non-nullable). With the annotation removed, a null seeds is now serialized as "seeds": null where it was previously omitted. This contradicts the generator's own matrix (optional & non-nullable -> NON_NULL in JsonAnnotationPolicyUtils.resolveJsonIncludePolicy) and diverges from sibling samples (spring-boot-oneof Pizza.pizzaSize and spring-boot-springdoc Tag.id keep NON_NULL on equivalent optional fields). Restore the annotation and the JsonInclude import, or regenerate the sample under the same config as the sibling samples.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At samples/openapi3/server/petstore/spring-boot-oneof-jackson-default-impl/src/main/java/org/openapitools/model/Apple.java, line 31: <comment>This regeneration drops `@JsonInclude(JsonInclude.Include.NON_NULL)` from the optional `seeds` field (spec `type: integer`, non-nullable). With the annotation removed, a null `seeds` is now serialized as `"seeds": null` where it was previously omitted. This contradicts the generator's own matrix (optional & non-nullable -> NON_NULL in JsonAnnotationPolicyUtils.resolveJsonIncludePolicy) and diverges from sibling samples (spring-boot-oneof `Pizza.pizzaSize` and spring-boot-springdoc `Tag.id` keep NON_NULL on equivalent optional fields). Restore the annotation and the JsonInclude import, or regenerate the sample under the same config as the sibling samples.</comment> <file context> @@ -28,7 +27,6 @@ public class Apple implements Fruit { - @JsonInclude(JsonInclude.Include.NON_NULL) private @Nullable Integer seeds; public Apple() { </file context>

Picazsoo marked this pull request as ready for review June 5, 2026 13:29

Picazsoo marked this pull request as draft June 5, 2026 13:29

cubic-dev-ai Bot reviewed Jun 5, 2026

View reviewed changes

Comment thread modules/openapi-generator/src/main/java/org/openapitools/codegen/languages/SpringCodegen.java Outdated

jpfinne reviewed Jun 5, 2026

View reviewed changes

Picazsoo and others added 4 commits June 17, 2026 23:18

Merge branch 'master' into feature/use-deduction-default

ffc95a7

# Conflicts: # modules/openapi-generator/src/test/java/org/openapitools/codegen/kotlin/spring/KotlinSpringServerCodegenTest.java

implement CR feedback suggestion

d88082a

update documentation

de72ad2

Picazsoo changed the title ~~feat(kotlin-spring, java-spring): add x-jackson-default-impl / typeInfoDefaultImpls support~~ [kotlin-spring, java(-spring)] -feature - add x-jackson-default-impl / typeInfoDefaultImpls support to allow specifying of fallback schema when deserializing Jun 17, 2026

Picazsoo marked this pull request as ready for review June 17, 2026 22:07

cubic-dev-ai Bot reviewed Jun 17, 2026

View reviewed changes

Comment thread modules/openapi-generator/src/main/resources/kotlin-spring/typeInfoAnnotation.mustache

Picazsoo added 3 commits June 18, 2026 00:18

document the new vendor extension

98ddfb9

feat: add warning for unresolved models in vendor extensions

41dcc13

update documentation

57535bf

cubic-dev-ai Bot reviewed Jun 18, 2026

View reviewed changes

Picazsoo added 4 commits June 18, 2026 10:15

address CR feedback and update documentation

7f2856b

address CR feedback and update documentation

378ac1e

address CR feedback and update documentation

3e19fd9

add to kotlin-client as well.

ea94f96

Merge branch 'master' into feature/use-deduction-default

e005ea4

# Conflicts: # modules/openapi-generator/src/test/java/org/openapitools/codegen/java/spring/SpringCodegenTest.java

Picazsoo requested a review from jpfinne July 1, 2026 12:48

Picazsoo added 2 commits July 13, 2026 00:12

add compiled samples

a5e2a3d

cubic-dev-ai Bot reviewed Jul 15, 2026

View reviewed changes

fix compiled samples

9fa7541

Picazsoo added 3 commits July 15, 2026 23:48

implement CR feedback

b168935

Merge branch 'master' into feature/use-deduction-default

637abce

updated samples

9ae62a1

cubic-dev-ai Bot reviewed Aug 7, 2026

View reviewed changes

Comment thread ...rs/java/restclient-jackson-default-impl/src/main/java/org/openapitools/client/ApiClient.java

Comment thread samples/client/others/java/restclient-jackson-default-impl/.openapi-generator/FILES

updated samples

fb5132e

Picazsoo and others added 2 commits August 13, 2026 20:21

Update samples and documentation

8d5365a

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

cubic-dev-ai Bot reviewed Aug 13, 2026

View reviewed changes

Uh oh!

Uh oh!

Conversation

Picazsoo commented Jun 5, 2026 • edited by cubic-dev-ai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Purpose

What it adds

Scope

Tests & docs

PR checklist

Summary by cubic

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

jpfinne Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

jpfinne Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Picazsoo Jun 5, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Picazsoo Jun 5, 2026

Choose a reason for hiding this comment

Uh oh!

Picazsoo Jun 17, 2026

Choose a reason for hiding this comment

Uh oh!

Picazsoo Jun 18, 2026

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Picazsoo commented Jul 1, 2026

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

cubic-dev-ai Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Picazsoo commented Aug 8, 2026

Uh oh!

cubic-dev-ai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

cubic-dev-ai Bot Aug 13, 2026

Picazsoo commented Jun 5, 2026 •

edited by cubic-dev-ai Bot

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

Picazsoo Jun 5, 2026 •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading

cubic-dev-ai Bot left a comment •

edited

Loading