Generate Documentation from JSON

Most JSON you inherit — an API response, a webhook payload, a config file — arrives with no explanation. You can see that a field is a string or a number, but not what it represents, which values are valid, or whether it is optional. Documenting a JSON data model means capturing that missing intent alongside the structure: for each field, its type, its meaning, and how it fits the whole document.

A JSON Schema is a natural place to keep this. Schema already describes types, required fields, and nesting in a machine-readable way; adding a description to each property turns the same file into human-readable documentation. One artifact then does two jobs — it validates incoming data and explains it to the next developer who reads it.

That is what this tool produces. From a single sample it emits a schema in which each field is annotated with a written description, so you get a documented data model without maintaining a separate wiki page that quietly drifts out of sync with the real payload.

The action runs in two stages. First it infers structure: it walks your sample, records each key, and assigns a JSON type (string, number, integer, boolean, object, or array) to build a draft-07 base schema — the same kind of inference a JSON Schema generator performs. Then the AI layer reads the keys and their example values and writes a plain-English description for each field, plus one for the root object.

Because those descriptions come from an AI model, this step sends your JSON to the model and spends credits; the local formatter, validator, and tree view never do. You see a credit estimate before the action runs, and new accounts start with 1,000 free credits, so you can try it on real payloads before choosing a plan.

The quality of the output tracks the quality of the input. A field named "amt" holding 0 gives the model little to work with, while "amount_due_cents": 4200 lets it write something precise. Representative values — real-looking strings, non-null numbers, at least one element per array — produce the sharpest descriptions.

API documentation is the obvious fit. Paste a real endpoint response and you get a described schema you can drop into an OpenAPI components section, a README, or an internal reference — a faster starting point than writing every field row by hand and keeping it current.

Team handoffs are another. When you pass a service or dataset to another engineer, a documented schema answers the questions they would otherwise send you on Slack: what is this field, what type is it, is it always present. It travels with the code and reviews cleanly in a pull request.

Integration specs benefit too. Partners consuming your webhooks or data exports need the shape and meaning of every field before they build against it. A described schema is precise enough to code against and readable enough to hand to a non-author, which shortens the back-and-forth that usually surrounds a new integration.

Start with a representative sample, not the biggest one. A single object that includes every field you care about beats a 10,000-line array of near-identical records: it costs fewer credits and gives the model exactly the surface it needs to describe.

Use meaningful keys. The model reads your field names as its main signal, so "user_email" documents far better than "ue". If your payload uses opaque or abbreviated keys, include a realistic value for each one so the model can infer intent from the data instead.

Treat the output as a first draft. AI descriptions are accurate for common patterns but cannot know your business rules — that a "status" of 3 means "refunded", for example. Read each description, correct anything domain-specific, and add constraints (enum, required, min/max) the generator could not infer. Because the result is plain JSON Schema, you can edit it in the same editor and re-run validation immediately.