Format JSON for GitHub README (Improve Documentation Clarity)
Scope: writing readable JSON snippets for GitHub documentation.
TL;DR: Most parse failures come from a few repeat offenders: trailing commas, invalid quotes, invisible Unicode, and “almost JSON” that is actually a JS object literal. Fix syntax first, then validate and format.
Table of contents
Why this happens
JSON is strict. Copy‑pasting from docs/chats/word processors can introduce characters a parser rejects. If the line/column in the error message looks “wrong,” invisible characters earlier in the file are often the cause.
Example (Before → After)
Before
{"name":"app","version":"1.0.0","scripts":{"start":"node index.js"}}
After
{
"name": "app",
"version": "1.0.0",
"scripts": {
"start": "node index.js"
}
}
Step-by-step solution
- Paste into a plain text editor (strip rich formatting).
- Fix the strict JSON rules (quotes, commas, keys).
- Remove invisible characters (zero‑width / NBSP / BOM) if the error seems off.
- Validate JSON once it looks correct.
- Format (beautify) for readability and safe sharing in docs.
Common mistakes
- Using single quotes instead of double quotes
- Leaving trailing commas in arrays/objects
- Mixing JSON with comments (JSON doesn’t allow comments)
- Copying smart quotes from rich text ( “ ” )
- Assuming a JS object literal is valid JSON
FAQ
Q: Why does this work in JavaScript but not in JSON.parse?
A: JS object literals allow more syntax than JSON.
Q: Do spaces/newlines break JSON?
A: Normal whitespace doesn’t, but hidden Unicode can.
Q: Should I minify or beautify?
A: Beautify for debugging/docs; minify for transport if needed.
Q: What is the fastest check?
A: Scan for trailing commas and quotes first.
Q: How do I prevent these issues?
A: Keep JSON in plain text sources, validate before commit/deploy.
Quick checklist
- Double quotes only
- No trailing commas
- Quote all keys
- Remove invisible Unicode (if needed)
- Validate then format
Related: /blog/