Generate a JSON Schema From Multiple Samples (Optional & Nullable Fields Done Right)

A schema generated from one JSON sample is wrong from day one: it marks every field as required and locks each field to the exact type that one sample happened to contain. Real API data varies — fields are missing on some records, null on others. The fix is to infer from multiple samples and merge them: a field absent from any sample becomes optional, and a field whose type differs across samples becomes nullable or a union. This guide explains the optional / required / nullable distinction and walks through generating a schema that survives real data.

Why one sample isn't enough

Auto-inference from a single JSON object is fast, but it makes two assumptions that are almost always wrong for real APIs:

• Every field is required. If your one sample includes phone, the schema demands phone on every record — even though many records omit it.
• Every type is fixed. If deleted_at is a string in your sample, the schema rejects the null the API actually returns most of the time.

Both assumptions come from the same root cause: a single sample contains no variation, so the generator has nothing from which to infer what is optional or nullable. Collect a few real responses and merge them, and the variation tells the generator everything it was previously guessing.

Optional vs. required vs. nullable

These three words get used interchangeably, but they are independent properties — and confusing them is one of the most common schema bugs. Optional is about whether the key can be absent. Nullable is about whether the value can be null when the key is present.

An optional-and-nullable field has three distinct states the schema must allow: present with a value, present but null, or absent entirely. A single-sample generator can only ever capture one of those three. Merging real samples is how you cover all of them.

How multi-sample merging works

The Multi-Sample Schema Generator infers a schema for each sample you paste, then folds them together with three rules:

• Required = intersection. A field stays in required only if it is present and non-null in every sample. Missing from one sample, or null in one sample, and it becomes optional.
• Types union per field. If a field is a string in one sample and null in another, the merged type is ["string","null"]. Object-vs-null becomes an anyOf of the object schema and a null type.
• It recurses. Nested objects and array items are merged with the same rules at every depth.

How to do it, step by step

1. Collect 2–5 real samples that differ on purpose — a happy-path record, one with an optional field omitted, and one with a nullable field set to null.
2. Open the Multi-Sample Schema Generator. It runs entirely in your browser; nothing is uploaded.
3. Paste one sample per slot. Click Add sample for up to five slots. Invalid JSON is flagged on the specific slot.
4. Click Merge into Schema. Optional and nullable fields are detected automatically.
5. Review, tighten, and validate. Add the constraints inference can't know (enum, minimum, maximum, pattern), then confirm it in the JSON Schema Validator.

A worked example

Three user records — note that phone appears in one, is missing in another, and is null in a third, while role is missing from the first:

// Sample 1
{ "id": 1, "name": "Alice", "email": "alice@example.com", "phone": "+1-202-555-0143", "active": true }

// Sample 2
{ "id": 2, "name": "Bob", "email": "bob@example.com", "active": false, "role": "admin" }

// Sample 3
{ "id": 3, "name": "Carol", "email": "carol@example.com", "phone": null, "active": true, "role": "editor" }

Merging all three produces a schema that reflects the real variation — phone is optional and nullable, role is optional, and only the fields present in every sample stay required:

{
  "$schema": "https://json-schema.org/draft-07/schema#",
  "type": "object",
  "properties": {
    "id":     { "type": "integer" },
    "name":   { "type": "string" },
    "email":  { "type": "string", "format": "email" },
    "phone":  { "type": ["string", "null"] },
    "active": { "type": "boolean" },
    "role":   { "type": "string" }
  },
  "required": ["id", "name", "email", "active"]
}

Compare that to what a single-sample generator would emit from Sample 1 alone: phone would be a plain required string, and role would not exist in the schema at all. The first time production sends Bob (no phone) or Carol (phone: null), that schema rejects valid data.

The merged schema is still a starting point

Merging fixes structure — which fields exist, which are optional, which are nullable. It cannot infer your rules. A sample can't tell the generator that status must be one of three values, that age is between 0 and 120, or that email must match a pattern. After merging, tighten the schema:

"status": { "type": "string", "enum": ["active", "inactive", "pending"] },
"age":    { "type": "integer", "minimum": 0, "maximum": 120 },
"role":   { "type": "string", "enum": ["admin", "editor", "viewer"] }

Single-sample vs. multi-sample generators