Skip to content

[BUG][core] OAS 3.1 property with a bare type: "null" resolves to a never-generated Null / ModelNull model (regression in 7.17.0) #24520

Open

Description

@renechoi

Bug Report Checklist

  • Have you provided a full/minimal spec to reproduce the issue?
  • Have you validated the input using an OpenAPI validator?
  • Have you tested with the latest master to confirm the issue still exists?
  • Have you searched for related issues/PRs?
  • What's the actual output vs expected output?
  • [Optional] Sponsorship to speed up the bug fix or feature request
Description

A schema of a bare type: "null" is resolved to a model named Null / ModelNull that is never generated. This regressed at 7.17.0 and affects every generator, because the cause is in OpenAPINormalizer, not in a language template.

Updated after probing. The first revision of this report described this as a property-level defect and suggested that handling it in normalizeProperties would be enough. That was too narrow. Probing 18 null-bearing shapes across 7.16.0–7.24.0 shows three container sites are affected, and one neighbouring case regressed and was fixed again in a way that rules out the obvious revert. Everything below is the widened version.

Affected sites, all in one model:

// generated by 7.24.0 — none of these three names exist; models/ holds only child.ts and parent-bare-null.ts
'dyn'?: Null;                 // property:      type: "null"
'dynList'?: Array<Null>;      // array items:   items: {type: "null"}
'dynRef'?: Null;              // $ref to a component schema that is itself type: "null"
'child'?: Child;              // control: correct

7.16.0 produced any | null, Array<any | null> and any | null for the same three. So the regression costs the | null as well as substituting a fictional model.

The failure mode differs by generator, and the quieter one is worse:

7.16.0 7.17.0 → 7.24.0
typescript-axios any | null, no import Null + import type { Null } from './null', and null.ts is never written
java (--library webclient) JsonNullable<Object> / List<Object> ModelNull / List<ModelNull>, and ModelNull.java is never written

Java fails to compile, which is at least visible. TypeScript does not, because the generated // May contain unused imports in some cases / // @ts-ignore pair sits directly above the dangling import and suppresses it. The properties then silently degrade to any while reading as real named types:

const a: ParentBareNull = { dyn: 12345 };
const b: ParentBareNull = { dyn: 'a string instead' };
const c: ParentBareNull = { dynList: [1, 'two', { three: true }], dynRef: { anything: 'goes' } };
const d = (v: ParentBareNull) => v.dynList![0].whateverMethod().deeply.nested;

tsc --strict exits 0 on all of them.

The shape is not hand-written exotica. @rony-remedio, who found this, reports that Swashbuckle emits a bare type: "null" for an untyped / dynamic member, and measured it on a production 3.1.1 spec (490 component schemas, 486 generated models): it occurs on 4 properties there, all silently degraded to any, confirming the 7.16.0 → 7.24.0 swap four-for-four. Those production figures are theirs; everything else here is from the minimal spec below.

Where this sits relative to what is already fixed

Measured on an 18-shape probe spec with typescript-axios, on 7.16.0, 7.17.0, 7.18.0, 7.19.0, 7.20.0, 7.21.0, 7.22.0, 7.23.0 and 7.24.0:

container branch child shape 7.16.0 7.17.0–7.23.0 7.24.0
map value type: "null" any | null Null any | null — fixed by #23967
map value $ref → bare-null alias any Null any | null — fixed by #23967
parent's own type array $ref → type: [null, object] alias Null Null NullObjectAlias | null — fixed by #24140
property type: "null" / ["null"] / with description any | null Null Null
property $ref → bare-null alias any | null Null Null
array items type: "null" Array<any | null> Array<Null> Array<Null>
property type: "null" + enum: [null] no import unused Null import unused Null import

Two things follow.

This is not a "revert the 7.17.0 early return" situation. Row 3 was broken before 7.17.0 and stayed broken until 7.24.0; dropping the early return would put it back. (Attribution of rows 1–3 is by release boundary plus diff inspection; I did not build the intermediate commits.)

The last row is a separate, smaller defect: type: "null" with enum: [null] emits the Null import while typing the property from the inline-enum path, so the import is emitted by something other than what picks the property type.

openapi-generator version

Regression. Bisected on typescript-axios: correct on 7.12.0–7.16.0, broken from 7.17.0 through 7.24.0. A 7.25.0-SNAPSHOT build of the current tree produces output byte-identical to 7.24.0's for this spec (diff -r clean apart from the version stamp), so master is still affected. java --library webclient bisects to the same 7.17.0 boundary.

OpenAPI declaration file content or url
openapi: 3.1.0
info:
  title: Repro bare null property
  version: 1.0.0
components:
  schemas:
    Child:
      type: object
      properties:
        name:
          type: string

    # a component schema that is itself a bare null type
    NullAlias:
      type: "null"

    ParentBareNull:
      type: object
      properties:
        # 1. property: Swashbuckle emits this shape for an untyped / `dynamic` member
        dyn:
          type: "null"
        # 2. array items
        dynList:
          type: array
          items:
            type: "null"
        # 3. property that $refs a null-typed component schema
        dynRef:
          $ref: "#/components/schemas/NullAlias"
        # control: an ordinary $ref property, which stays correct
        child:
          $ref: "#/components/schemas/Child"
Generation Details
openapi-generator-cli generate -i spec.yaml -g typescript-axios -o out \
  --additional-properties=withSeparateModelsAndApi=true,modelPackage=models,apiPackage=api

Output is byte-identical with and without --openapi-normalizer NORMALIZE_31SPEC=true (diff -r clean), so the rule is not involved either way.

Steps to reproduce
  1. Generate with 7.16.0 → models/parent-bare-null.ts declares 'dyn'?: any | null;, 'dynList'?: Array<any | null>;, 'dynRef'?: any | null; and imports only Child.
  2. Generate the same spec with 7.17.0 or later → Null, Array<Null>, Null plus an import of ./null, while models/ contains only child.ts, index.ts and parent-bare-null.ts.
  3. Run tsc --strict on the output → exits 0. Assign a number, a string or an object to any of the three → still exits 0.
  4. Repeat with -g java --library webclient → private ModelNull dyn, private List<ModelNull> dynList, private ModelNull dynRef, with no ModelNull.java; model/ holds only Child.java and ParentBareNull.java.
Suggested cause

OpenAPINormalizer#normalizeSchema gained this guard in 7.17.0 (absent at v7.16.0, present at v7.17.0); it is currently at OpenAPINormalizer.java:940:

if (ModelUtils.isNullTypeSchema(openAPI, schema)) {
    return schema;
}

ModelUtils.isNullTypeSchema dereferences $refs and returns true for a single-entry type array of "null" (and for a single-entry enum of null), so such a schema is returned untouched no matter which normalizer rules are enabled, and DefaultCodegen#getPrimitiveType then resolves it to the literal type name "null", which becomes a model reference.

Because the early return is inside normalizeSchema itself, a null-type schema can only be rewritten by its parent — and the parent branches do not treat their children alike:

  • map (else if (schema.getAdditionalProperties() instanceof Schema)) checks ModelUtils.isNullTypeSchema(openAPI, additionalProperties) before recursing. That interception is [BUG][core] Normalize OAS 3.1 type: null map value (additionalProperties) under NORMALIZE_31SPEC #23967, and it is why rows 1–2 above are fixed.
  • properties (normalizeProperties) calls normalizeSchema(property, new HashSet<>()) on each child with no such check.
  • array calls normalizeSchema(result.getItems(), visitedSchemas) with no such check.

normalizeNullTypeArray31, present in both the properties and map branches, handles the parent's own type array; that is a different axis (it is what #24140 added and what fixed row 3), which is why the parent-level fix left rows 4–6 broken.

So the missing piece is a child-level interception in the properties and array branches, mirroring what the map branch already does.

Related issues/PRs

Found by @rony-remedio while reviewing #24519; filed separately so it doesn't widen that PR's scope.

Activity

  1. rony-remedio commented on Jul 29, 2026

    @rony-remedio

    Thanks for writing this up properly — the bisect and the OpenAPINormalizer.java:940 root cause are the whole substance here.

    Confirming your 7.16.0 → 7.17.0 boundary on the production spec rather than a minimal one, since a real-world regression is a different argument from a hand-written repro. Same spec, same options, no normalizer rules enabled, only the generator version differs:

    7.16.0 7.24.0
    ?: any | null; 4 0
    ?: Null; 0 4
    models/null.ts generated no no

    A clean four-for-four swap, matching your table exactly. The four affected properties live in two model files.

    Two details that may be worth having in the report:

    The nullability is lost as well as the type. 7.16.0 produced any | null — honest about being unconstrained, and still nullable, which is correct for type: "null". 7.24.0 produces Null, which is neither. So the regression costs the | null in addition to substituting a fictional model, and that part is invisible even in Java, where the missing ModelNull.java at least stops the build.

    The dangling import predates the regression, harmlessly. In 7.16.0 three model files already carried import type { Null } from './null' with null.ts never generated — but nothing referenced Null, so the @ts-ignore above it made them genuinely unused imports, exactly as the boilerplate comment claims. 7.17.0 did not introduce the bogus import; it started using it as a property type, which is what turned inert boilerplate into a silent any. That may narrow where to look, since whatever emits the import was already doing so before the regression.

    Relationship to #24519. On this spec the two are cleanly separable: after building that branch, ?: Null; is still 4, and the two files that still import ./null are precisely the two holding these four properties. So #24519 neither fixes nor worsens this, which matches what you found — the map-branch fix and this property-branch gap are independent.

    Happy to re-measure on any branch that attempts this one; the spec and the tooling are set up.

  2. renechoi commented on Jul 29, 2026

    @renechoi
    ContributorAuthor

    Both of your points measured. One of them came out the other way, and chasing it turned up two more sites.

    I built an 18-shape probe spec (S1..S18, every way I could construct a null type into a schema: bare, single-entry array, $ref to a null-typed component, array items, map values, anyOf/oneOf members, null-first type arrays, null enum) and ran it through typescript-axios on 7.16.0, 7.17.0, 7.18.0, 7.19.0, 7.20.0, 7.21.0, 7.22.0, 7.23.0 and 7.24.0, plus java --library webclient on the endpoints.

    The unused import at 7.16.0 does not reproduce here

    At 7.16.0 exactly one file in the whole output tree imports ./null, and it uses the import. Zero unused ones, across all 18 shapes.

    That one file is a property that $refs a component schema declared type: ["null", "object"] — which, as it happens, is broken at 7.16.0 and correct at 7.24.0 (fourth row of the table below). If the three files on your spec are that shape, the import would match but the "nothing referenced Null" part would not. Could you check what those three property schemas look like? It is the one part of your report I can't put a shape to.

    The separation you describe is real — the witness is at 7.24.0, not 7.16.0

    dyn:
      type: "null"
      enum: [null]

    generates import type { Null } from './null' while the property types as S12NullEnumDynEnum | null. The import is emitted and never used, on 7.17.0 through 7.24.0.

    ModelUtils.isNullTypeSchema returns true for a single-entry enum of null (the branch above the getTypes() one), so this schema takes the same untouched path as a bare type: "null", but the datatype then comes from the inline-enum handling while the import still comes from the type name. So your read is right: whatever emits the import is not what picks the property type.

    The regression is wider than properties — array items are hit identically

    7.16.0 7.17.0 → 7.24.0
    items: {type: "null"}, typescript-axios Array<any | null> Array<Null>
    items: {type: "null"}, java webclient List<Object> List<ModelNull>, no ModelNull.java

    A property that $refs a component schema which is itself a bare type: "null" degrades the same way, and resolves to Null rather than to the alias's own name. Neither null.ts nor the alias model is written in any version I tested.

    Two members of this family are already fixed in-tree

    Full matrix, all measured on the probe spec:

    container branch child shape 7.16.0 7.17.0–7.23.0 7.24.0
    map value type: "null" any | null Null any | null — fixed
    map value $ref → bare-null alias any Null any | null — fixed
    parent's own type array $ref → type: [null, object] alias Null Null NullObjectAlias | null — fixed
    property type: "null" / ["null"] / + description any | null Null Null
    property $ref → bare-null alias any | null Null Null
    array items type: "null" Array<any | null> Array<Null> Array<Null>
    property type: "null" + enum: [null] no import unused import unused import

    The first two rows are #23967. The third is #24140 — I attribute it by the release boundary (broken through 7.23.0, correct at 7.24.0) and by its diff, which is the only change in that range touching this path; I did not build the intermediate commits to confirm.

    Two consequences for whoever fixes this:

    1. This is not a "revert the 7.17.0 early return" situation. The third row was broken before 7.17.0 and stayed broken until 7.24.0. Dropping the early return would put it back.
    2. The gap is a child interception, not a parent one. In normalizeSchema, the properties branch and the array branch hand each child straight back to normalizeSchema, where the isNullTypeSchema early return returns it untouched. The map branch does not: [BUG][core] Normalize OAS 3.1 type: null map value (additionalProperties) under NORMALIZE_31SPEC #23967 added an explicit isNullTypeSchema(additionalProperties) check in the parent's branch, before the child is recursed into. normalizeNullTypeArray31 in the properties and map branches handles the parent's own type array, which is a different axis and is why the parent-level fix in fix: normalize OAS 3.1 schemas with type:[object,"null"] to set nullable:true correctly #24140 left these three rows broken.

    On #24519 separability

    Whole-tree diff -r between 7.24.0 output and that branch is empty apart from .openapi-generator/VERSION — on 18 shapes rather than one, including all six broken rows above. Matches what you measured; that PR neither causes nor fixes any of this.

    I'm widening the report body: it currently describes a property-level defect and suggests that handling normalizeProperties would be enough, and array items make that too narrow.

  3. rony-remedio commented on Jul 29, 2026

    @rony-remedio

    Checked the shape you asked about. It is not a $ref to a null-typed alias — it is the nullable map from #24519, and the three files are exactly the three that PR changes.

    # 5 properties across 2 of the 3 schemas
    someCounts:
      type: ["null", "object"]
      additionalProperties: {type: integer, format: int32}
    
    # 1 property in the third
    devices:
      type: ["null", "object"]
      additionalProperties: {$ref: "#/components/schemas/<ValueSchema>"}

    So my "nothing referenced Null" holds on this spec — Null appears on the import line and nowhere else in all three files, at 7.16.0 and at 7.24.0 — but the producer is a shape your probe wouldn't have flagged as an unused-import case, because at 7.16.0 it is not otherwise broken. That makes it a third member of the family rather than a contradiction of your enum witness:

    shape 7.16.0 7.24.0 unused Null import
    type: ["null", object] + additionalProperties correct type, no | null correct type, no | null yes, both versions
    type: "null" + enum: [null] no import typed from inline enum yes, 7.17.0+

    Two things follow.

    The separation you identified is visible across a wider version range than the enum witness. This shape emits the import at 7.16.0 too, where nothing is broken and the property types correctly as a map. So whatever emits the import has been decoupled from the datatype since before 7.17.0 — the regression made that decoupling harmful for bare-null properties, it did not create it.

    #24519 removes three unused imports as a side effect, which neither of us noted. Full 7.24.0 account on this spec, five importers of ./null:

    So the two issues partition our five importers exactly, with no overlap, which is a stronger form of the separability we both measured.

    On my earlier claim, one correction. I said "three files already carried the import with null.ts never generated, but nothing referenced Null" and offered it as evidence for the emitter/type split. The observation is right and I've re-verified it, but I reached it by grepping ?: Null; — which would have missed Array<Null> or a map value. On this spec it happens not to matter, since those three files mention Null exactly once each. It was a narrower check than the claim deserved, and your probe spec is the right instrument for that question rather than one production spec.

    Nothing here changes the array-items finding or your matrix — I have no shape in this spec that exercises items: {type: "null"}, so I can't corroborate that row either way.

  4. renechoi commented on Jul 29, 2026

    @renechoi
    ContributorAuthor

    That shape closes it, and it turns my 7.16.0 result around. I added it to the probe as two schemas — someCounts with an int32 value and devices with a $ref value — and regenerated typescript-axios on 7.16.0 through 7.24.0.

    You are right, and my "does not reproduce" was a hole in the spec rather than a measurement: the 18 shapes contained no nullable map, only maps whose values were null-typed, so nothing in that tree could emit the import without also using it.

    property generated ./null imported Null referenced
    type: ["null", object] + additionalProperties: {type: integer} 'someCounts'?: { [key: string]: number; }; yes no
    type: ["null", object] + additionalProperties: {$ref: Child} 'devices'?: { [key: string]: Child; };, no Child import yes no

    Both rows are byte-identical on all nine releases I have jars for (7.16.0, 7.17.0, 7.18.0, 7.19.0, 7.20.0, 7.21.0, 7.22.0, 7.23.0, 7.24.0). So the decoupling you describe is not just older than 7.17.0 — nothing in that whole range touches it.

    That makes #24517 not a regression at all, which I had not stated anywhere. I re-ran the PR's fixture — these two shapes plus the nullable-array control — on each of those nine releases: models/ and docs/ are identical throughout. So the two issues differ in age as well as in mechanism. #24520 bisects to 7.17.0; the map gap has been there for at least the last nine releases, and they only resemble each other because they meet at the same import emitter.

    The partition reproduces on the probe. At 7.24.0, 8 files import ./null. The #24519 branch leaves 6, and they are exactly the bare-null family: bare type: "null", type: ["null"], a $ref to a null-typed alias, items: {type: "null"}, the null enum, and the described variant. The two it removes are the two nullable maps. Same shape as your 3 + 2, no overlap.

    tsc --strict over the probe models: 1 error before (TS2304: Cannot find name 'Child', the $ref map), 0 after. The six remaining dangling imports stay invisible to tsc either way, since the @ts-ignore suppresses the unresolved module and Null then resolves to any where it is used — which is the #24520 symptom rather than a separate one.

    One correction on "neither of us noted": the import removal is in the PR description's primitive-map before/after, and testNullableMapWithPrimitiveValueKeepsNullability asserts the generated model has no ./null import, so that half is guarded. What is new is the partition itself — that framing is what makes the two separable rather than merely independent-looking, and I have added the version range to the PR description.

    On the ?: Null; grep: it happened not to matter here, but Array<Null> and { [key: string]: Null; } both occur on the probe, so it is worth widening if you re-run it on anything else.

  5. rony-remedio commented on Jul 29, 2026

    @rony-remedio

    Corroborated on the production spec, and your correction stands.

    The three nullable-map files are byte-identical between 7.16.0 and 7.24.0 — 0 differing lines each — and no map property carries | null in either version. So the map gap is unchanged across that range on real-world input too, and #24517 is not a regression. My report didn't claim it was, but it didn't say it wasn't either, and "these two look like the same bug" was the natural reading given they surface at the same import. Worth having stated explicitly.

    I also widened the grep as you suggested: Array<Null> and { [key: string]: Null; } are both zero on this spec, in both versions. So its five importers really are just the two shapes, and the partition is not hiding a third case behind my narrow pattern. Your probe is the better instrument for that — this spec only exercises two of the seven rows in your matrix.

    Fair on "neither of us noted": the import removal is in the primitive-map before/after and testNullableMapWithPrimitiveValueKeepsNullability asserts it. I overstated — the partition framing was the new part, not the removal.

    Net from my side: #24519 is verified on 486 real models (1 → 0 tsc errors, 6 map properties gaining | null, nothing else moving), and #24520 has a real-world witness for its 7.17.0 boundary at 4 properties. Nothing outstanding that I can measure. I'll keep the build and the trees around, so ping me if a fix lands for this one and I'll re-run the same two checks against it.

    Thanks for the depth on both of these — going from "the import is missing" to a seven-row matrix with the age of each row is a lot more than the report deserved.

  6. renechoi commented on Sep 7, 2026

    @renechoi
    ContributorAuthor

    The obvious normalizer fix is the wrong layer, which may be why the property branch was never done alongside #24558.

    Intercepting a bare type: "null" in normalizeProperties fixes this but breaks Oas31GeneratedIrTest.generatesTypedJsonValuesForOpenApi31Schemas: cpp-boost-beast-client maps a null property to std::nullptr_t on purpose. That class is 11/11 on master, 10/11 with the change.

    So the null type has to survive the normalizer. Generators with no null typeMapping fall through DefaultCodegen.getSingleSchemaType to toModelName("null"), which is where Null comes from.

  7. renechoi commented on Sep 13, 2026

    @renechoi
    ContributorAuthor

    Re-measured on master (7.26.0-20260911.085220-74): the TypeScript row above understates this, because the silent-any outcome is layout-dependent.

    • withSeparateModelsAndApi=true — the @ts-ignore above the dangling import type { Null } from './null' suppresses it and tsc --strict exits 0, as reported.
    • default single-file layout — no import is emitted at all, so Null is simply an undeclared name and tsc --strict fails with 3 x TS2304: the property, the array items, and the $ref to a bare-null alias.

    Map values come out correct on master. Those three sites do not.

  8. added 2 commits that reference this issue on Oct 2, 2026
    0bf2d42
    7b76554
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions