[Bug]: Explicit @Schema(type = "number"|"integer"|"boolean") is emitted as "string" under OpenAPI 3.1

[forhadmethun]

Description of the problem/issue

When generating an OpenAPI 3.1 schema, an explicit @Schema(type = "...") on a property is resolved incorrectly. The scalar type is set correctly on the Schema object, but the types set is populated with ["string"]. Since the 3.1 serializer reads the types set, the property is emitted as type: "string" regardless of the declared type.

• Goal: produce a correct OpenAPI 3.1 document for DTOs that use explicit @Schema(type = ...).
• Annotation misbehaving: @Schema — an explicit type = "number" | "integer" | "boolean" is emitted as "string".
• Correct case: properties relying on type inference (no explicit type in @Schema) serialize correctly. Only an explicitly declared scalar type is affected.
• Framework: reproduces on plain swagger-core (ModelConverters + Json31); also observed via springdoc-openapi with springdoc.api-docs.version=openapi_3_1.
• Not examples-related: it reproduces on fields with no example, so it is distinct from [Bug]: Number example treated as a string when generating swagger file. #5061 / fix: treat number example as number and not string #5062 (numeric example serialization).
• Downstream: the resulting spec misreports field types, which breaks OpenAPI-based type/client generation (numbers/booleans generated as string).

Under OpenAPI 3.0 (openapi31 = false) the same DTO serializes correctly, so this is specific to 3.1 generation.

Affected Version

2.2.47

Earliest version the bug appears in (if known):
Not fully bisected. Confirmed present in 2.2.47 and still present in 2.2.52 (latest release at time of filing).

Steps to Reproduce

1. Add a DTO with explicit @Schema(type = ...) properties and resolve it in OpenAPI 3.1 mode:

   import io.swagger.v3.core.converter.AnnotatedType;
   import io.swagger.v3.core.converter.ModelConverters;
   import io.swagger.v3.core.converter.ResolvedSchema;
   import io.swagger.v3.core.util.Json31;
   import io.swagger.v3.oas.annotations.media.Schema;
   import java.math.BigDecimal;
   
   public class Repro {
     enum Freq { DAY, WEEK, MONTH }
   
     static class Dto {
       @Schema(title = "Inferred") public BigDecimal inferred;         // no explicit type (control)
       @Schema(title = "Amount", type = "number")  public BigDecimal amount;
       @Schema(title = "Count",  type = "integer") public Integer count;
       @Schema(title = "Flag",   type = "boolean") public Boolean flag;
       @Schema(title = "Unit")   public Freq unit;                     // enum (control)
     }
   
     public static void main(String[] args) {
       ModelConverters converters = new ModelConverters(true); // openapi31 = true
       ResolvedSchema resolved =
           converters.resolveAsResolvedSchema(new AnnotatedType(Dto.class));
   
       // root cause: scalar type is correct, but the "types" set is ["string"]
       resolved.schema.getProperties().forEach((name, s) ->
           System.out.println(name + " -> getType()=" + s.getType() + " getTypes()=" + s.getTypes()));
   
       System.out.println(Json31.pretty(resolved.schema));
     }
   }

2. Resolve with new ModelConverters(true) (OpenAPI 3.1 mode) and serialize with Json31.

3. Observe the serialized output and inspect the resolved Schema objects.

Expected Behavior

The declared type is preserved:

{
  "properties": {
    "inferred": { "type": "number" },
    "amount":   { "type": "number" },
    "count":    { "type": "integer" },
    "flag":     { "type": "boolean" },
    "unit":     { "type": "string", "enum": ["DAY", "WEEK", "MONTH"] }
  }
}

Actual Behavior

Every property with an explicit scalar type collapses to "string":

{
  "properties": {
    "inferred": { "type": "number" },                                  // OK (inferred, control)
    "amount":   { "type": "string" },                                  // WRONG, declared "number"
    "count":    { "type": "string" },                                  // WRONG, declared "integer"
    "flag":     { "type": "string" },                                  // WRONG, declared "boolean"
    "unit":     { "type": "string", "enum": ["DAY", "WEEK", "MONTH"] }  // OK (enum, control)
  }
}

inferred (inferred type) and unit (enum) serialize correctly — the defect is limited to an explicitly declared scalar type.

Inspecting the resolved (pre-serialization) Schema objects shows the root cause — the scalar type is right, the types set is wrong:

amount -> getType()="number"  getTypes()=["string"]
count  -> getType()="integer" getTypes()=["string"]
flag   -> getType()="boolean" getTypes()=["string"]

Logs / Stack Traces

No exception or log output — the schema is generated silently with the wrong type.

Additional Context

• The same DTO serialized under OpenAPI 3.0 (new ModelConverters(false)) produces correct types, confirming this is a 3.1-generation regression.
• Likely related to BUG @Schema#implementation not processed on properties when generating open api 3.1.0 #4679 (@Schema type/implementation ignored under OpenAPI 3.1).
• Distinct from [Bug]: Number example treated as a string when generating swagger file. #5061 / fix: treat number example as number and not string #5062, which concern numeric example serialization; this issue is about the property type and reproduces with no example present.
• Current workaround: a post-processing pass that re-syncs each schema's types set to its scalar type produces a correct 3.1 document.

Checklist

• I have searched the existing issues and this is not a duplicate.
• I have provided sufficient information for maintainers to reproduce the issue.

Repro.java

[Mattias-Sehlstedt]

If we are aiming the specification resolving towards 3.1 why would we not use @Schema(types = {"X"}) to set the type field? The type property has been replaced with types in OAS 3.1.

[forhadmethun]

If we are aiming the specification resolving towards 3.1 why would we not use @Schema(types = {"X"}) to set the type field? The type property has been replaced with types in OAS 3.1.

type isn't removed in OAS 3.1 — in JSON Schema 2020-12 it's still valid, either a single value ("type": "number") or an array. swagger-models just models it internally as a types set, so @Schema(type = "number") remains valid 3.1 intent, and type() isn't deprecated on the annotation.

swagger-core also already treats type() as valid for 3.1 elsewhere — e.g. ModelResolver resolves an explicit type() via PrimitiveType.createProperty31(), which populates the types set correctly. The getSchemaFromAnnotation path is just inconsistent: it routes type() through the legacy scalar setType(), while the sibling types() branch right below uses setTypes(). The fix only makes the two consistent.

Also, the same annotated code is meant to generate both 3.0 and 3.1 (the openapi31 flag), so requiring types = {...} for 3.1 would force per-version annotations. And the current behavior is silent corruption — type = "number" emits type: "string", a wrong type rather than a migration hint.

If deprecating type() for 3.1 is the intended direction, that'd be worth documenting explicitly.

[Mattias-Sehlstedt]

I do not see how it would be possible to deprecate type in the annotation since it is the solution for OAS 3.0. The same goes for nullable and any other explicit OAS 3.0 definition that has been replaced in OAS 3.1.

The fix could definitely be considered valid, but if the use case is aimed against 3.1., I would suggest that you instead use types, since that is the native way to control types for OAS 3.1. This is highlighted with @OpenAPI31 on the field itself. The reason why this is beneficial is that once you start using nullability or several types, then it will be confusing in your code why it is sometimes @Schema(type = ...) and sometimes @Schema(types = {...}).

If there are cases where you want it to resolve towards both, isn't the best behavior then to try to remove the "bridging" between the types, since if that is done it might become confusing and buggy to support them both? Will @Schema(types = {"string", "integer", "null"}) become @Schema(type = "string", nullable = true) or @Schema(type = "integer", nullable = true)? And what should something be done when there are opposite values @Schema(types = {"string", "null"}, nullable = false)?

To me it makes the most sense to leave it entirely to the user to use the annotation fields that are relevant for the target OAS version. And if it happens that they want different versions to communicate different things, then that is entirely possible by just using type, types and nullable. Having these be entirely decoupled makes it possible to change the specification however, and that is the main point of the annotation as I understand it (allow the user to redefine what is interpreted from heuristics).

[forhadmethun]

That's a fair design rationale, keeping type / types / nullable fully decoupled and letting the user pick the fields relevant to the target OAS version makes sense, and I agree the bridging gets ambiguous once nullability or multiple types are involved. I won't push the auto-mapping approach.

One thing that still seems worth separating from the type-vs-types question: today @Schema(type = "number") under 3.1 doesn't just ignore type() — it emits type: "string", i.e. an actively contradictory type, because the types set defaults to ["string"]. Even under the "use types for 3.1" guidance, silently emitting string for a declared number is surprising. Would it make sense to, in the 3.1 path, simply not apply the default ["string"] when an explicit type() was provided (leave it to inference / the user's types()), rather than overriding with string?

Either way, thanks for the guidance.

[Mattias-Sehlstedt]

Yes the behavior of defaulting to string seems very incorrect. I would strongly agree with you that it should use the same heuristics that would be used for OAS 3.0. and create integer/boolean or any other relevant type.

I am unfortunately only a contributor to this project, so I cannot implement a fix and get it merged instantly. But if you do not have a concrete fix for it as of now, then I could investigate it and see if I can have a PR for it later this week.

---

I have found the cause for the issue and documented it here, I have a solution that fixes it but I am not entirely happy with it, so will see if I can find a better solution.