Fix Zod Parse Errors on Nullable OpenAPI Fields

Quick answer: why nullable OpenAPI fields fail

Most nullable OpenAPI parse errors happen because the runtime payload returns `null` but the generated Zod schema expects a string, or because the field is omitted but the schema only modeled nullable. Nullable and optional are different contracts.

OpenAPI 3.0 nullable example

OpenAPI 3.0 commonly represents nullable values with `nullable: true`. A converter should turn that into a Zod nullable field, not a plain string.

{
  "type": "object",
  "required": ["id", "nickname"],
  "properties": {
    "id": { "type": "string" },
    "nickname": {
      "type": "string",
      "nullable": true
    }
  }
}

OpenAPI 3.1 nullable example

OpenAPI 3.1 aligns more closely with JSON Schema and can represent nullable values with a type union that includes `null`.

{
  "type": "object",
  "required": ["id", "nickname"],
  "properties": {
    "id": { "type": "string" },
    "nickname": {
      "type": ["string", "null"]
    }
  }
}

Generated Zod fix

When the API can return `null`, the Zod schema needs `.nullable()`. When the API can omit the property, the schema needs `.optional()`.

const UserSchema = z.object({
  id: z.string(),
  nickname: z.string().nullable(),
  avatarUrl: z.string().url().nullable().optional(),
});

nullable is not optional

A nullable field can be present with the value `null`. An optional field can be missing. If the API does both, the Zod field must model both behaviors.

• Use `.nullable()` for `null` values.
• Use `.optional()` for omitted keys.
• Use `.nullable().optional()` only when both payload shapes are valid.

safeParse debugging workflow

Use `safeParse` while debugging contract drift so you can inspect issue paths without crashing the caller.

const result = UserSchema.safeParse(payload);

if (!result.success) {
  console.table(
    result.error.issues.map((issue) => ({
      path: issue.path.join("."),
      code: issue.code,
      message: issue.message,
    })),
  );
}

OpenAPI 3.0 vs 3.1 checklist

Check the OpenAPI version before deciding whether `nullable: true` or a `type` array should be expected in the schema document.

• For OpenAPI 3.0, review `nullable: true` on schema properties.
• For OpenAPI 3.1, review `type: ["string", "null"]` or equivalent JSON Schema output.
• Confirm `required` controls presence, not whether a present value can be null.
• Test generated Zod against real payloads, not only against the schema document.

Production checklist

Before shipping a generated OpenAPI-to-Zod schema, add tests for present values, null values, omitted fields, and malformed values.

• Keep nullable fixtures in test data.
• Review required arrays and optional properties together.
• Do not silence nullable parse errors with `z.any()`.
• Regenerate schemas after upstream OpenAPI nullable changes.

Nullable versus optional fields

Use FrameworkKit to generate the starter code, then review the output before shipping it in production.

OpenAPI to Zod resources

FAQ

Related tools