Why Isn't My Nullable Property Working in Code Generators?

TL;DR: When you use oneOf, anyOf, or allOf, many tools ignore nullable: true. You must explicitly include { type: null } as one of the schema options.

The Problem

You have an OpenAPI schema like this:

type: object
properties:
  status:
    oneOf:
      - type: string
      - type: integer
    nullable: true

This validates fine with OpenAPI validators, but:

Code generators like OpenAPI Generator or NSwag don't treat it as nullable
Runtime validators reject null values
TypeScript/C# generated clients throw errors on null

Why It Happens

The OpenAPI 3.0 spec says that when oneOf, anyOf, or allOf are present, the nullable keyword is effectively ignored by many implementations. The schema must match exactly one of the oneOf options — and null isn't listed.

The Fix

Add an explicit null type to your oneOf array:

type: object
properties:
  status:
    oneOf:
      - type: string
      - type: integer
      - type: "null"  # ← Explicit null option

Now code generators and validators correctly understand that null is a valid value.

Related Issues

Check Your Entire Spec

Use our OpenAPI Silent Failure Validator to catch this and 10+ other patterns that break tooling.

Analyze My Spec