mkschema

Generate a JSON Schema from real JSON — and feed it more than one sample. You have an API response, a config, a pile of log records, and you want a JSON Schema for validation, docs, or contract tests. Hand-writing it is tedious; most generators take a single example and over-fit it — every field marked required, types pinned to whatever that one record happened to contain. mkschema merges many samples: a field in every sample is required, a field in only some is optional, and differing types are unioned. Zero dependencies, no network.

pip install mkschema

$ printf '{"id":1,"name":"Ada","age":30}\n{"id":2,"age":30.5}\n' | mkschema --ndjson -

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "age":  { "type": "number" },        // 30 and 30.5 unioned to number
    "id":   { "type": "integer" },
    "name": { "type": "string" }
  },
  "required": ["age", "id"]               // name was missing from the 2nd sample, so it's optional
}

This is the Python build. A behavior-equivalent Node build is on npm: npx mkschema (https://github.com/jjdoor/mkschema).

Usage

mkschema sample.json                 # infer from one file
mkschema a.json b.json c.json        # merge several samples into one schema
mkschema --ndjson records.ndjson     # one sample per line (logs, exports)
cat response.json | mkschema -        # read a JSON value from stdin
mkschema users.json --title User --id https://ex.com/user.schema.json

Schema goes to stdout, so redirect it: mkschema data.json > schema.json.

What it infers

• Types — null, boolean, integer, number, string, array, object. Numbers are classified by value, so 5.0 is an integer and the Python and Node builds agree.
• String format — date-time, date, email, uuid, ipv4, uri (kept only when all samples of a field agree).
• required — the intersection across samples: a key present in every sample. (One sample ⇒ everything required.)
• Arrays — items is the merge of all element schemas, so [1, "x"] becomes { "type": ["integer", "string"] }.
• Unions — a field that is an integer in one sample and a float in another becomes number; genuinely different types become a sorted type array.

Options

Notes

• Output is draft 2020-12 JSON Schema, deterministic (properties and required are sorted) so it diffs cleanly in version control.
• Same tool, two builds. A behavior-equivalent Node build is on npm (npx mkschema); use whichever your stack has.
• It infers structure, not constraints — add your own minLength, enum, pattern, etc. afterward. mkschema gives you the scaffold from real data.

Exit codes

License

MIT