JSON Formatting: Best Practices for Clean Data

March 16, 2026 · 6 min read

JSON (JavaScript Object Notation) is the most widely used data interchange format on the web. Its simplicity and readability make it the go-to choice for APIs, configuration files, and data storage. However, poorly formatted JSON can be difficult to read, debug, and maintain. This guide covers JSON formatting best practices, common pitfalls, and tools to keep your data clean and valid.

JSON Syntax Basics

JSON is built on two universal data structures: objects (collections of key-value pairs) and arrays (ordered lists of values). Here are the fundamental syntax rules:

Data Types

• String: Text enclosed in double quotes: "hello world"
• Number: Integer or floating-point: 42, 3.14, -17, 2.5e10
• Boolean: true or false (lowercase only)
• Null: null (lowercase only)
• Object: Curly braces with key-value pairs: {"key": "value"}
• Array: Square brackets with values: [1, 2, 3]

Object Syntax

{
  "name": "Alice",
  "age": 30,
  "isActive": true,
  "address": {
    "city": "San Francisco",
    "zip": "94102"
  },
  "hobbies": ["reading", "hiking", "coding"]
}

Keys must always be strings enclosed in double quotes. Values can be any valid JSON data type. Key-value pairs are separated by commas, with no trailing comma after the last pair.

Formatting Rules

Indentation

Consistent indentation is crucial for readability. The two most common styles are:

• 2 spaces: Compact and preferred in JavaScript/Node.js ecosystems
• 4 spaces: More spacious, common in Python and Java projects

Tabs are technically valid but spaces are preferred for JSON because they render consistently across editors and environments. Pick one style and use it consistently across your project.

Key Naming Conventions

• camelCase: "firstName" — Most common in JavaScript APIs
• snake_case: "first_name" — Common in Python and Ruby APIs
• kebab-case: "first-name" — Used in some REST APIs and configuration files

Choose one convention for your entire API or project. Mixing naming conventions creates confusion and maintenance issues.

Ordering

While JSON objects are technically unordered, consistent key ordering improves readability and diff comparison:

• Put identifiers (id, name, type) first
• Group related fields together
• Put metadata (timestamps, version) last
• Alphabetical ordering works well for configuration files

Common JSON Errors

These are the most frequent mistakes that cause JSON parsing failures:

Trailing Commas

// INVALID - trailing comma after last element
{
  "name": "Alice",
  "age": 30,    ← Remove this comma
}

// VALID
{
  "name": "Alice",
  "age": 30
}

Single Quotes

// INVALID - single quotes
{'name': 'Alice'}

// VALID - double quotes only
{"name": "Alice"}

Unquoted Keys

// INVALID - unquoted key
{name: "Alice"}

// VALID - quoted key
{"name": "Alice"}

Comments

Standard JSON does not support comments. If you need comments in configuration, consider using JSONC (JSON with Comments), JSON5, or YAML instead. Some tools like VS Code support JSONC for settings files.

Other Common Issues

• Undefined values: JSON does not have undefined; use null instead
• NaN and Infinity: Not valid in JSON; represent them as strings or null
• Multiline strings: Not supported; use \n for newlines within strings
• Hex numbers: Not valid; use decimal notation only

JSON Validation

Always validate JSON before using it in production. Validation catches syntax errors early and prevents runtime failures:

Browser Console

try {
  JSON.parse(jsonString);
  console.log("Valid JSON");
} catch (e) {
  console.error("Invalid JSON:", e.message);
}

Command Line

# Using Python
python3 -m json.tool file.json

# Using jq
jq . file.json

# Using Node.js
node -e "JSON.parse(require('fs').readFileSync('file.json'))"

Use our JSON Formatter for instant browser-based validation with clear error messages and line numbers. For data conversion, try our CSV to JSON converter.

Minification vs Pretty-Print

Minification

Minified JSON removes all whitespace, reducing file size for network transfer:

{"name":"Alice","age":30,"hobbies":["reading","hiking"]}

Use minification for API responses, production configuration, and any JSON transmitted over the network. Typical size reduction is 15-30%.

Pretty-Print

Pretty-printed JSON adds indentation and newlines for human readability:

{
  "name": "Alice",
  "age": 30,
  "hobbies": [
    "reading",
    "hiking"
  ]
}

Use pretty-print for development, debugging, configuration files, documentation, and code review.

In JavaScript

// Pretty-print with 2-space indent
JSON.stringify(data, null, 2);

// Minify
JSON.stringify(data);

Key Takeaways

• Use double quotes for all keys and string values — single quotes are not valid JSON
• No trailing commas, comments, undefined, NaN, or Infinity in standard JSON
• Choose consistent indentation (2 or 4 spaces) and key naming conventions
• Validate JSON before production use to catch syntax errors early
• Minify for network transfer, pretty-print for development and debugging