JSON Schema type: null — Why It's Wrong for Real APIs and How to Fix It

You generate a JSON Schema from a sample where one field is null. The tool spits back "type": "null". You copy the schema, run validation against a real API response — and every non-null value fails. Your schema now only accepts the literal null, which is almost never what an API field means.

What {"type": "null"} actually means

In JSON Schema, type is a validation keyword that restricts what values are allowed. The value null is one of seven primitive types in JSON Schema (along with string, number, integer, boolean, object, array). So:

{ "type": "null" }

…means exactly this: the field must be the JSON literal null. Always. No other value passes.

// Schema: { "type": "null" }

null       ✓ valid
"Alice"    ✗ invalid
42         ✗ invalid
true       ✗ invalid

This is useful in exactly one scenario: a field that is always null by design. In practice, almost no API field works like that. Null in an API means "this optional value is not set right now." When the value exists, it will be a string, number, object, or whatever the actual type is.

Why generators output it anyway

Generators infer types strictly from what they observe in your sample. If they see:

{ "userId": 42, "deletedAt": null }

…they see deletedAt is null and faithfully record that as "type": "null". They cannot know what deletedAt would be when the user is deleted — that information is not in the sample. This is a fundamental limitation of single-sample inference.

Most tools (jsonlint, quicktype, and others) simply output what they observed. A smarter approach is to recognize that a null-only field likely needs refinement and output a union type instead.

The correct pattern: nullable union types

JSON Schema supports type arrays since draft-04. Instead of a single type string, you pass an array of types:

// Nullable string — accepts "2026-05-23T14:00:00Z" OR null
{ "type": ["string", "null"] }

// Nullable integer — accepts 42 OR null
{ "type": ["integer", "null"] }

// Nullable object — accepts {...} OR null
{ "type": ["object", "null"] }

This is the standard way to express nullable fields in JSON Schema draft-07 and later. A validator will accept any value that matches at least one of the listed types:

// Schema: { "type": ["string", "null"] }

null           ✓ valid
"2026-05-23"   ✓ valid
42             ✗ invalid (not string or null)

Simple vs Smart Mode in our generator

Our JSON Schema Generator gives you a choice via the Simple / Smart Mode toggle.

In Smart Mode, null object fields get a description annotation:

{
  "deletedAt": {
    "type": ["null","string","number","boolean","object","array"],
    "description": "Type inferred as null only — refine after seeing non-null samples"
  }
}

Once you have real data where deletedAt is an ISO 8601 timestamp, you refine it to:

{
  "deletedAt": {
    "type": ["string", "null"],
    "format": "date-time"
  }
}

Recommended workflow

1. Paste your JSON sample into the JSON Schema Generator
2. Switch to Smart Mode using the toggle
3. Generate — null fields show all possible types with a refine hint
4. Find a real record where those null fields have actual values
5. Replace the broad union with the specific type: ["string","null"], ["integer","null"], etc.
6. Paste the refined schema into the JSON Schema Validator to confirm it works

When type: null IS correct

There are legitimate uses:

• Explicit null branch in anyOf — if one variant of a discriminated union is "no value": anyOf: [{type: "object", ...}, {type: "null"}]
• Sentinel fields — a field that signals "deleted" by being literally null in every instance of this record type
• Generated discriminators — some code generators use it as a placeholder for unresolved types

If your use case fits one of these, Simple Mode gives you strict type: null output.

Frequently Asked Questions