Last Tuesday, I spent forty-five minutes hunting a bug that turned out to be a missing comma in a JSON configuration file. Forty-five minutes. The file looked fine in my editor, but somewhere in the 300 lines of minified-style JSON, something was broken. That's when I learned my lesson about JSON formatting.
Why JSON Formatting Matters
JSON (JavaScript Object Notation) is everywhere. APIs, configuration files, database responses, you name it. And while it's human-readable by design, unformatted JSON is about as pleasant to debug as a tax audit.
When I first started coding, I'd copy-paste JSON responses directly into my editor and wonder why I couldn't find the bug. The answer was always the same: the JSON was a single wall of text, and I was missing the obvious.
The Pain Points of Unformatted JSON
Let me paint a picture. You receive this from an API:
{"users":[{"id":1,"name":"Sarah Connor","email":"sarah@resistance.io","roles":["admin","developer"]},{"id":2,"name":"John Smith","email":"john@company.com","roles":["user"]}],"meta":{"total":2,"page":1,"per_page":10}}Can you spot the error? There's a missing opening quote on the email field for the first user. Good luck finding that in production.
Professional JSON Workflows
Here's what I do now. Every time I receive JSON—whether it's from an API response, a config file, or a colleague's code—I run it through a formatter before anything else.
Step 1: Always Validate First
Before formatting, validate. A formatter will happily format invalid JSON into nicely-organized invalid JSON, which doesn't help anyone. Validation catches syntax errors before they become headaches.
Most validators will tell you exactly where the error is—the line number, the column, and often a suggestion for what's wrong. This alone can save you hours of debugging.
Step 2: Pretty-Print for Readability
Once validation passes, pretty-print that JSON. Add indentation, proper spacing, and structure. The standard is typically 2 or 4 spaces per level—I prefer 2 spaces because it keeps deep nesting manageable on smaller screens.
After formatting, the same JSON from before looks like this:
{
"users": [
{
"id": 1,
"name": "Sarah Connor",
"email": "sarah@resistance.io",
"roles": ["admin", "developer"]
},
{
"id": 2,
"name": "John Smith",
"email": "john@company.com",
"roles": ["user"]
}
],
"meta": {
"total": 2,
"page": 1,
"per_page": 10
}
}Now that missing quote? It's obvious.
Step 3: Minify for Production
After you're done debugging, minify for production. Remove all the whitespace you added. This isn't just about aesthetics—minified JSON is smaller, which means faster API responses and less bandwidth usage.
I keep my JSON in pretty-print format during development and switch to minified when deploying. Many build tools and CDNs do this automatically, but it's good to know how to do it manually.
Real-World Example
Last month, I was debugging a webhook integration. The external service was sending JSON payloads, and something was causing our system to reject them. The payloads looked valid, but they were failing our parser.
I copied one of the failing payloads into a JSON formatter and immediately saw the issue: the external service was using single quotes instead of double quotes for strings. Technically invalid JSON, but most parsers are lenient. Ours wasn't.
If I'd looked at the raw payload first, I might have caught it faster, but the formatted version made it immediately obvious that the quotes were the problem.
Tools of the Trade
You don't need an IDE plugin for everything. Sometimes a quick web-based formatter is exactly what you need—especially when you're on a different machine or can't install software.
Our JSON formatter at BuildNextStack does all three: validate, pretty-print, and minify. It's client-side, so your JSON never leaves your browser. I use it constantly, especially for quick validation before copying JSON into code.
Common JSON Formatting Mistakes
Even experienced developers make these mistakes:
- Trailing commas: The last item in an array or object should never have a comma after it. Easy to miss when scanning.
- Comments: JSON doesn't support comments. If you need to document, use a separate schema document or switch to a format that supports comments like YAML.
- Single quotes: Strings must use double quotes. Always.
- Trailing whitespace: Invisible but can cause issues with some parsers.
- Unicode encoding: Special characters should be properly escaped or UTF-8 encoded.
Keyboard Shortcuts to Remember
Most modern code editors have built-in JSON formatting. VS Code formats JSON with Shift+Alt+F (Windows/Linux) or Shift+Option+F (Mac). If you're in a terminal, jq is incredibly powerful for piping and transforming JSON.
Final Thoughts
Formatting JSON isn't just about making things pretty—it's about making your work faster and more accurate. A well-formatted JSON file is easier to review, easier to debug, and easier to maintain.
The next time you get a wall of text that "should be JSON," take thirty seconds to format it first. Your future self will thank you.