JSON Schema Generator

Inference gives you a draft, not a contract

A JSON Schema is a specification: it says what a document is *allowed* to be. Generating one from a sample inverts that — it describes what one document happens to be, and assumes the rest look the same. The output is genuinely useful, and it is a starting point rather than an answer.

The distinction matters because the parts inference gets right are the tedious parts, and the parts it cannot know are the parts that catch real bugs. Knowing which is which is most of the skill.

What is inferred

Seven string formats are recognised by shape: date-time, date, time, email, uuid, ipv4 and uri. Detection is regex-based and deliberately conservative, so a value that merely resembles a date is left as a plain string rather than constrained wrongly.

"order_id": "a3f1c2d4-5e6f-7a8b-9c0d-1e2f3a4b5c6d"
"placed_at": "2024-03-11T09:24:00Z"
"email": "sarah@example.com"
"total": 41.5
"qty": 2

"order_id": { "type": "string", "format": "uuid" }
"placed_at": { "type": "string", "format": "date-time" }
"email":     { "type": "string", "format": "email" }
"total":     { "type": "number" }
"qty":       { "type": "integer" }

How `required` is decided

For a plain object, every key present is required — there is no evidence to suggest otherwise. For an array of records the answer is more interesting: the schemas of the items are merged, and a property stays required only if it was present in every sampled item.

"items": [
  { "sku": "A-1", "qty": 2, "price": 9.5, "gift_note": null },
  { "sku": "B-7", "qty": 1, "price": 22.5 }
]

"items": {
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "sku": { "type": "string" },
      "qty": { "type": "integer" },
      "price": { "type": "number" },
      "gift_note": { "type": "null" }
    },
    "required": ["price", "qty", "sku"]
  }
}

gift_note appears in properties but not in required, because the second record does not have it. That intersection is the single most valuable thing the generator does — and it only works if your sample contains records that genuinely differ. Required lists are sorted alphabetically so schemas generated from the same data always match.

That behaviour is the Present in every sample setting, which is the default. Switching to All properties marks everything seen anywhere as required — occasionally what you want when you know the sample is complete and would rather fail loudly on a missing field than accept one.

Merging values that disagree

When one field holds different types across records, the merged schema accepts both. The most common case by far is a nullable field.

{ "note": null }  +  { "note": "hi" }

"note": { "type": ["null", "string"] }

An integer and a number merge to number. An object merged with null keeps its properties and gains "null" in its type list. Arrays merge their item schemas recursively, so an array of objects produces one item schema describing all of them. Up to 2,000 array items are sampled — well past the point where the shape stops changing.

Choosing a draft

Draft 04 predates the null type being usable the way later drafts use it, so a nullable field is emitted differently and automatically:

2020-12   "note": { "type": ["null", "string"] }
draft-04  "note": { "type": "string", "nullable": true }

What inference can never know

These are the constraints worth adding by hand. Every one of them catches bugs that a generated schema will not.

• Enums. A status field that was "active" in all five records is typed string, not enum: ["active", "archived"]. Only you know the full set.
• Ranges. minimum, maximum, minLength, maxLength — a sample cannot tell a legal bound from the largest value that happened to occur.
• Patterns. A regex for an SKU or an account number.
• Uniqueness. uniqueItems, and identifier uniqueness across records — the analyzer will tell you whether it currently holds.
• Cross-field rules. "shipped_at must be present when status is shipped" needs if/then or dependentRequired, written by a person.
• Strictness. additionalProperties: false rejects any property the schema does not name. That is a decision about how your API is versioned rather than a fact about the data, so it is never inferred — add it by hand to the objects where you want it enforced.