How to format json for api documentation and readme examples
- Step 1Capture a representative request/response sample — Grab a real example from curl, Postman, Insomnia, or a log and save it as a
.jsonfile. The tool reads a file (drop or browse), so write the snippet out rather than pasting it. - Step 2Drop the sample onto the prettifier — Drag the
.jsonfile in or clickbrowse. It is read in-browser viafile.text()— important when the sample still contains real customer data you are about to swap for synthetic values. - Step 3Choose the indent for your docs platform — Use
2 spaces(default) for inline Markdown examples and most rendered docs;4 spacesfor wide standalone example files. Those are the only two widths — there is no tab option, so match your docs theme accordingly. - Step 4Sort keys for cross-endpoint consistency — Enable
Sort keys alphabeticallyso every example across your docs lists fields in the same order. This makes a multi-endpoint reference feel uniform. Leave it off if a specific field order tells a story (e.g.statusfirst). - Step 5Replace real data with synthetic values — After prettifying, swap real names, emails, and tokens for clearly-fake examples (
alice@example.com,tok_example_123). Never publish real customer data — it is a privacy and security risk. - Step 6Embed in your docs — Copy the full output (the preview truncates at 5,000 chars; Copy/Download do not) into a fenced ``
json block, an OpenAPIexample` value, or a Postman example. For YAML specs, convert with json-to-yaml first.
Indent and sort choices by docs target
Recommended settings for each documentation destination. Both indent widths and key sorting are the only knobs the tool has.
| Docs target | Indent | Sort keys | Notes |
|---|---|---|---|
| Markdown README fenced block | 2 spaces | On | Compact and consistent; ```json fence gives GitHub syntax highlighting |
OpenAPI/Swagger example (JSON spec) | 2 spaces | On | Paste under content.application/json.example; Swagger UI renders it |
| OpenAPI spec written in YAML | 2 spaces | On | Prettify, then convert with json-to-yaml — YAML is a JSON superset so it round-trips |
| Standalone example file in a docs repo | 4 spaces | Optional | Wider indent reads better as a full-page sample |
| Postman collection example | 2 spaces | Optional | Postman stores raw; consistent indent keeps the example readable in the UI |
Accuracy traps when documenting JSON examples
What to watch so the example you publish actually matches the wire format readers will hit.
| Trap | What happens | Fix |
|---|---|---|
64-bit integer id | Rounded on parse — documented value differs from real value | Document large IDs as JSON strings |
| Trailing comma / comment in sample | Won't parse → no formatted output | Repair with json-format-fixer before formatting |
1.0 price written as a literal | Normalized to 1 — looks like an integer in docs | Add a note, or document money as strings / minor units |
| Real PII left in the example | Privacy/GDPR risk in public docs | Swap for synthetic values after prettifying |
| NDJSON streaming sample | Not one document → parse error | Document a single representative line, or wrap the set in [ ] |
Free vs Pro limits for example files
Per-file JSON limits. Example payloads are almost always tiny, so free tier is usually plenty.
| Tier | Max file size | Batch files (JSON) |
|---|---|---|
| Free | 2 MB | 1 |
| Pro | 100 MB | 10 |
Cookbook
Documentation examples before and after. All values are synthetic.
curl output to a README example
ExampleA compact curl response becomes a clean fenced block at 2-space with keys sorted for consistency across the docs.
Input (curl -s output):
{"role":"admin","id":1001,"email":"u@example.com","active":true}
Output (2-space, Sort keys ON):
{
"active": true,
"email": "u@example.com",
"id": 1001,
"role": "admin"
}
Wrap in a ```json fence in the README.Consistent field order across endpoints
ExampleThree endpoints return the same entity with different field orders. Sort keys ON makes every example present fields identically, so the reference reads uniformly.
GET /users/1 -> {"name":"Ada","id":1}
POST /users -> {"id":2,"name":"Grace"}
PUT /users/3 -> {"name":"Lin","id":3}
All prettified with Sort keys ON:
{ "id": <n>, "name": "<name>" }
-> every endpoint's example now shows id then name.Prettify, then convert to a YAML OpenAPI example
ExampleYour OpenAPI spec is YAML. Prettify the JSON first for a clean shape, then convert it to a YAML example block.
Prettified JSON example:
{
"id": 1,
"status": "active"
}
Run json-to-yaml ->
id: 1
status: active
Place under:
responses:
'200':
content:
application/json:
example:
id: 1
status: activeBig ID would mislead readers
ExampleA documented numeric id over 2^53 is silently rounded. If you publish the rounded value, a reader copying it hits a 404. Document large IDs as strings.
Real response id: 9007199254740993
Prettified (number):
{
"id": 9007199254740992 <- changed!
}
Document it as a string instead:
{
"id": "9007199254740993"
}Reject a broken example before publishing
ExampleA draft example had a trailing comma copied from code. The tool refuses it, so you fix the docs before a reader ever copies a broken snippet.
Draft example:
{
"name": "Ada",
"role": "admin",
}
Result: invalid JSON: Expected double-quoted property name
...at line 4
Remove the trailing comma (or run json-format-fixer),
then prettify and publish.Errors and edge cases
Real errors and silent failures sourced from each platform's own documentation. Match the wording to the row, fix what the row says to fix.
Documented numeric id exceeds 2^53−1
Silent precision lossJSON.parse rounds integers above 9,007,199,254,740,991, so a 19-digit id in a sample is changed before it reaches your docs. Publishing the rounded value means readers copy a wrong ID. There is no BigInt mode — document large identifiers as JSON strings.
Example contains a trailing comma or comment
Parse errorSamples copied straight from code often carry a trailing comma or a // comment. Strict JSON.parse rejects them with a position-tagged error and produces no output. Repair with json-format-fixer first — and remember that real wire JSON never contains comments, so the published example should not either.
Money written as 1.00 or 9.90
Normalized1.00 becomes 1 and 9.90 becomes 9.9 after round-tripping. A reader may misread the documented amount as an integer or wrong precision. For currency, document as strings ("9.90") or minor units (990) and note the convention in the docs.
Real customer data left in the sample
Privacy riskThe tool formats whatever you give it — it does not redact. If you prettify a real response and publish it, real names, emails, and tokens leak into public docs (a GDPR/security problem). After prettifying, replace every real value with a synthetic one before committing the docs. Processing is local, so the data never leaves your browser during formatting.
Streaming/NDJSON sample
Parse errorAn NDJSON or SSE sample (multiple JSON objects separated by newlines) is not a single document and throws Unexpected non-whitespace character after JSON. Document one representative line on its own, or wrap the set in a JSON array [ ... ] if your endpoint actually returns an array.
Sort keys reorders an intentional field sequence
Order changedIf your example deliberately leads with status or error for narrative clarity, turning Sort keys on alphabetizes it and buries that field. Sorting is great for cross-endpoint uniformity but not for a curated example — leave it off when field order is part of the teaching.
Empty object or array example
Supported{} and [] are valid and prettify to themselves. This is expected — an empty-collection example is legitimate documentation for an endpoint that can return no results.
Unicode / emoji in a sample value
PreservedNon-ASCII characters and emoji round-trip correctly because output is UTF-8. A documented name: "José" or a status emoji stays intact. This is expected behavior and safe to publish.
Numeric-string keys reorder
Engine reorderAn example object keyed by stringified numbers ({"1": ..., "2": ...}) is always emitted with those keys first in numeric order, even without Sort keys. Usually fine for docs, but note it if your example intentionally interleaves numeric and named keys.
Example file over the tier limit
Rejected — over tier limitDocumentation examples rarely approach 2 MB, but a giant captured payload would be blocked on free tier with an upgrade prompt (Pro: 100 MB). Trim the example to the fields you actually want to document — shorter examples are better docs anyway.
Frequently asked questions
Should I use real or synthetic data in API examples?
Always synthetic. Use clearly-fake values (alice@example.com, tok_example_123, IDs like 1001) so no real customer data appears in public docs. The prettifier processes locally so your real sample never uploads, but you must still swap the values before committing the docs — formatting does not redact.
How do I get JSON examples into a YAML OpenAPI spec?
Prettify the JSON here for a clean shape, then convert it with json-to-yaml and paste under content.application/json.example. YAML is a superset of JSON, so prettified JSON can also be pasted directly into a YAML file and still parse — but converting gives idiomatic YAML.
What indent should documentation examples use?
2 spaces for inline Markdown and most rendered docs (it is the default), 4 spaces for wide standalone example files. Those are the only two options. Match whichever your docs theme renders most cleanly and stay consistent across the docs.
Will a documented id number stay exact?
Only if it is within JavaScript's safe integer range (≤ 9,007,199,254,740,991). Larger IDs are rounded on parse, so the documented value would differ from reality. Document large IDs as JSON strings — that is also how well-designed APIs return them.
Why won't my example with a comment format?
Strict JSON.parse rejects comments and trailing commas. Real wire JSON has neither, so a published example should not either. If your draft came from code with // notes, run json-format-fixer to strip them, then prettify the clean JSON.
Can I keep a specific field first, like status?
Yes — just leave Sort keys off. The tool preserves your object's key order (except numeric-string keys, which the engine always emits first). Use sorting only when you want uniform field order across many examples rather than a curated single example.
Does the example I publish match the real wire bytes?
For typical objects, yes — only whitespace changes. Three caveats from JSON round-tripping: large integers round, duplicate keys collapse, and number literals normalize (1.00 → 1). For docs that matters mainly for IDs and money, which you should document as strings anyway.
How do I document an endpoint that returns a stream of objects?
NDJSON/SSE isn't a single JSON document and won't parse here. Document one representative line as standalone JSON, and describe the stream framing in prose. If the endpoint truly returns a JSON array, wrap the objects in [ ] and prettify that.
Can I format several endpoint examples at once?
One per run (free JSON batch is 1 file). Examples are small, so this is rarely a bottleneck. For a large docs repo, format your example files with Prettier in CI to keep them all consistent automatically.
Will Unicode and emoji in examples survive?
Yes. Output is UTF-8, so accented names and emoji round-trip exactly. Your documented "city": "München" stays intact and renders correctly in any UTF-8 docs platform.
Is my sample payload uploaded while formatting?
No. The file is read with file.text() and parsed/formatted in your browser. Real data in the sample never reaches JAD Apps servers, which is why it is safe to prettify before you redact. Only an anonymous run counter is stored when signed in.
Can I generate consistent examples automatically?
For repeatable docs builds, use the Pro json-prettifier runner (mirrors indent 2/4 and sortKeys) or Prettier in your docs CI. To produce placeholder sample data for examples, see json-mock-generator — note it emits a fixed record shape (id/name/email/etc.), not your custom schema.
Privacy first
Conversion runs locally in your browser. No file is uploaded — only metadata counters are saved for signed-in dashboard stats.