`z.coerce.number().min(0)` generates `nullable: true` while `min(1)` does not

[tobigumo]

Summary

z.coerce.number().min(0) incorrectly generates nullable: true in OpenAPI schema, while z.coerce.number().min(1) does not.

Reproduction

https://stackblitz.com/edit/vitejs-vite-urf1hjcy?file=src%2Frepro-nullable-bug.ts

const QuerySchema = z.object({
  limit: z.coerce.number().int().min(1).default(100), // OK
  skip: z.coerce.number().int().min(0).default(100), // BUG: generates nullable: true
});

Output

{
  "paths": {
    "/test": {
      "get": {
        "parameters": [
          {
            "schema": {
              "type": "integer",
              "minimum": 1,
              "default": 100
            },
            "required": false,
            "name": "limit",
            "in": "query"
          },
          {
            "schema": {
              "type": "integer",
              "nullable": true,
              "minimum": 0,
              "default": 100
            },
            "required": false,
            "name": "skip",
            "in": "query"
          }
        ]
      }
    }
  }
}

Expected

Both limit and skip should NOT have nullable: true. The only difference is min(1) vs min(0), which should not affect nullability.

Versions

Tested and confirmed on:

• zod: 3.25.76, 4.3.5
• @asteasolutions/zod-to-openapi: 7.3.4, 8.4.0

[tobigumo]

After further analysis, I realized the current behavior might actually be correct.

Why the behavior is consistent:

• safeParse(null).success determines nullability
• min(0): null → coerced to 0 → passes validation → nullable: true
• min(1): null → coerced to 0 → fails validation → nullable: false

This makes sense: "nullable = the schema accepts null as valid input"

Why a fix might not be desirable:

Consider a "quantity" field where empty input should default to 0:

quantity: z.coerce.number().min(0).default(0)

This is a natural use case, and the current nullable: true correctly indicates that null is accepted as input.

Our use case:

For pagination params like limit/skip, having different types (number vs number | null) is confusing. But that's specific to our scenario.

Workaround:

For those who want to force nullable: false, use .openapi():

skip: z.coerce
  .number()
  .int()
  .min(0)
  .default(0)
  .openapi({ type: 'integer', minimum: 0, default: 0 })

Question:
Is the current behavior intentional? If so, this might be worth documenting since the interaction between coerce and nullable inference can be surprising.