DevKitHub

JSON & Data

JSON Schema Generator — Infer a Schema from a Sample

Paste a JSON document to infer a JSON Schema from it. Arrays of objects are merged across every element, so optional fields stay optional.

1 line
26 lines
  • A schema inferred from one sample describes that sample. Optional fields the sample happens to include will be marked required, and anything it never shows cannot be known about.

This tool runs entirely in your browser. Your input is never uploaded, stored or logged.

How it works

Arrays are where schema generators go wrong, and it is worth knowing how. Given [{"a":1,"b":2},{"a":3}] the common implementations either describe only the first element — so "b" comes out required, and the schema rejects data that is perfectly valid — or union the two into an anyOf that is technically correct and unreadable. Here the element schemas are merged structurally: properties are unioned and `required` is the intersection, so "a" is required and "b" is not. That is the only description of the sample that every element in it actually satisfies.

Numbers are split into integer and number rather than flattened, because a sample of whole numbers tells you something a "number" does not. An array mixing the two widens to number, which is the correct generalisation; two genuinely different types produce an anyOf, which is honest about the fact that they are different. Strings are checked against the common formats — date-time, date, time, email, uuid, uri, ipv4 — in a defined order so a timestamp is never read as a plain date.

An empty array leaves `items` off entirely rather than guessing, because an empty array carries no information about what it would hold. That is the general caveat too, and it is attached to every result: a schema inferred from one sample describes that sample. Optional fields the sample happens to include come out required, and anything it never shows cannot be known about at all. It is a starting point to edit, not a specification.

Common problems

Every example below is run against this tool in our test suite, so what it says here is what the tool actually does.

Expected double-quoted property name in JSON.

{"a":1,}
Why:
A trailing comma. JavaScript object literals allow one and JSON does not, so code that builds JSON by string concatenation produces this constantly.
Fix:
Remove the trailing comma, or serialise with JSON.stringify instead of building the text by hand.

Unexpected token in JSON.

{'a':1}
Why:
Single-quoted keys or strings. JSON requires double quotes; single quotes are a JavaScript literal, not JSON, even though they look interchangeable.
Fix:
Use double quotes throughout.

A field that is optional in my API came out required.

Why:
The sample happened to include it. Inference can only describe what it was shown, and a single document cannot distinguish a field that is always present from one that merely was this time.
Fix:
Paste an array of several representative documents instead of one — a field missing from any element is then correctly left out of required.

Frequently asked questions

Which draft does it emit?
JSON Schema 2020-12 by default, with draft-07 available. The two differ in how they declare themselves and in features this generator does not use, so the output is valid under either.
Why is a field required when my API says it is optional?
Because the sample contained it, and one document cannot tell an always-present field from one that merely was this time. Paste an array of several representative documents and any field missing from one of them is correctly left optional.
Why does an empty array produce no items?
Because it carries no information about what it would hold. Guessing would produce a schema that looks authoritative and is unfounded, so `items` is left off and the reason is stated.

Related tools

Last updated