What Is JSON? Syntax Basics and Formatting Best Practices

What Is JSON?

JSON (JavaScript Object Notation) is a lightweight text format for structuring and describing data. Although it originated from JavaScript's object notation syntax, it has become a language-independent, universal data interchange format used across the industry.

From REST API responses and configuration files to database storage, JSON appears in virtually every aspect of web development. Its simplicity and readability are the reasons it has replaced XML as the de facto standard.

Syntax Basics and Data Types

JSON supports exactly six data types:

Data Type	Description	Example
String	Enclosed in double quotes	"Hello"
Number	Integer or floating-point	42, 3.14
Boolean	true or false	true
null	Empty value	null
Object	Key-value pairs	{"key": "value"}
Array	Ordered list of values	[1, 2, 3]

Object Syntax

Objects are enclosed in curly braces {}, with key-value pairs separated by colons. Multiple pairs are separated by commas.

{
  "name": "John Doe",
  "age": 30,
  "isActive": true,
  "email": "john@example.com"
}

An important rule: keys must always be enclosed in double quotes. Single quotes or unquoted keys are invalid JSON.

Array Syntax

Arrays are enclosed in square brackets [], with values separated by commas. Different data types can be mixed within an array.

{
  "fruits": ["apple", "orange", "grape"],
  "mixed": [1, "hello", true, null]
}

Nested Structures

Objects and arrays can be freely nested, allowing you to represent complex data structures.

{
  "company": "Example Corp",
  "employees": [
    {
      "name": "Alice",
      "department": "Engineering",
      "skills": ["JavaScript", "Python"]
    },
    {
      "name": "Bob",
      "department": "Design",
      "skills": ["Figma", "CSS"]
    }
  ]
}

Common Errors and How to Fix Them

JSON syntax errors are frequently encountered during development. Let's look at the main causes and solutions.

1. Trailing Commas

While trailing commas are allowed in JavaScript, they cause syntax errors in JSON.

// Invalid JSON
{
  "name": "John",
  "age": 30,
}

// Valid JSON
{
  "name": "John",
  "age": 30
}

2. Using Single Quotes

Only double quotes are valid in JSON.

// Invalid JSON
{'name': 'John'}

// Valid JSON
{"name": "John"}

3. Adding Comments

The JSON specification does not include a comment syntax. Including // or /* */ will cause a parse error. If you need comments in configuration files, consider using JSON5 or JSONC instead.

4. Leading Zeros in Numbers

Numbers other than 0 are invalid if they have leading zeros.

// Invalid JSON
{"code": 0123}

// Valid JSON
{"code": 123}

Formatting Best Practices

Follow these best practices to improve readability and maintainability.

Consistent Indentation

When JSON files are meant to be read by humans, use 2-space or 4-space indentation. Consistency across your team is key.

{
  "settings": {
    "theme": "dark",
    "fontSize": 14,
    "autoSave": true
  }
}

Key Naming Conventions

In API design, maintain a consistent key naming convention. camelCase or snake_case are the most common choices.

{
  "userName": "john",
  "createdAt": "2026-03-08T10:00:00Z"
}

Choosing the Right Data Types

Avoid storing numbers as strings. Use the appropriate data type.

// Avoid this pattern
{"price": "1000", "isAvailable": "true"}

// Recommended pattern
{"price": 1000, "isAvailable": true}

Common Use Cases for JSON

JSON is indispensable in modern web development. Here are the most common use cases:

• REST APIs: The most widely used format for client-server data communication
• Configuration files: Used by development tools such as package.json, tsconfig.json
• Data storage: Adopted as the document format in NoSQL databases like MongoDB
• Logging: Output as structured logs in JSON format for processing by analysis tools

Comparison with Other Data Formats

Feature	JSON	YAML	XML	CSV
Readability	High	Very high	Moderate	High (tabular)
Data types	6 types	Rich	None	None
Comments	No	Yes	Yes	No
File size	Small	Small	Large	Very small
Nesting	Supported	Supported	Supported	Not supported

Choosing the right format depends on the use case. YAML is popular for configuration files where comments are useful, CSV works well for tabular data, and JSON is the standard for API responses.

Conclusion

JSON has established itself as the standard data interchange format for web development thanks to its simple syntax and broad compatibility. By mastering the basic syntax and avoiding common errors, you can develop more efficiently. Using dedicated JSON formatting and validation tools can significantly improve your workflow.