Skip to content

JSON

Understanding the JSON Format: A Developer's Guide

5 min read

Understanding the JSON Format: A Developer's Guide

If you have spent more than a few days learning about web development, programming, or APIs, you have undoubtedly encountered JSON. It is the absolute backbone of modern internet communication. Whenever a mobile app fetches the weather, a browser loads your social media feed, or a smart home device reports the temperature, that data is almost certainly being transmitted in JSON format.

But what exactly is JSON? Why did it become so incredibly popular? And most importantly, how do you read, write, and manipulate it without breaking your applications?

In this comprehensive guide, we will explore the origins of JSON, break down its exact syntax rules, look at its supported data types, and explain why it completely replaced older formats like XML.

What is JSON?

JSON stands for JavaScript Object Notation.

At its core, JSON is a lightweight, text-based data interchange format. It is designed to be easy for humans to read and write, and easy for machines to parse and generate.

Despite its name containing "JavaScript," JSON is completely language-independent. It was initially derived from JavaScript, but today, every major programming language (Python, Java, C#, Go, Ruby, PHP) has built-in code to parse and generate JSON data.

The primary purpose of JSON is to transmit data between a server and a web application (for example, sending user profile data from a backend database to a frontend React application).

The Syntax Rules of JSON

JSON is famously strict. A single missing comma or a misplaced quotation mark will result in a parsing error (the dreaded SyntaxError: Unexpected token). Understanding the rules is critical.

A JSON file is fundamentally built on two structures:

  1. Objects: A collection of key-value pairs enclosed in curly braces {}.
  2. Arrays: An ordered list of values enclosed in square brackets [].

Here is an example of a complete, valid JSON document representing a user profile:

{
  "id": 1045,
  "username": "tech_guru_99",
  "isActive": true,
  "email": null,
  "roles": ["admin", "editor"],
  "profile": {
    "firstName": "Alice",
    "lastName": "Smith",
    "age": 28
  }
}

Let's break down the golden rules of writing valid JSON:

1. Data is in Name/Value Pairs

A name/value pair (also called a key-value pair) consists of a field name (in double quotes), followed by a colon, followed by a value. "username": "tech_guru_99"

2. Keys MUST be in Double Quotes

In JavaScript, you can write an object key without quotes (e.g., username: "tech_guru_99"). In JSON, this is illegal. Every single key must be wrapped in double quotes "". Single quotes '' are also strictly forbidden.

3. Data is Separated by Commas

Every pair in an object, and every value in an array, must be separated by a comma. However, trailing commas are not allowed. You cannot place a comma after the final item in a list or object.

Invalid JSON (Trailing Comma):

{
  "name": "Alice",
  "age": 28,
}

4. No Comments Allowed

Unlike YAML or standard code files, JSON does not support comments (// or /* */). If you try to add a comment to a standard JSON file, the parser will fail. JSON is meant strictly for data, not metadata or annotations.

Supported Data Types

JSON only supports six fundamental data types. You cannot put a function, a date object, or an undefined value directly into JSON.

  1. String: Text enclosed in double quotes.
    • "city": "New York"
  2. Number: An integer or a floating-point number (no quotes).
    • "age": 30, "pi": 3.14159
  3. Boolean: true or false (no quotes, entirely lowercase).
    • "isSubscribed": true
  4. Array: An ordered list of values enclosed in square brackets.
    • "colors": ["red", "green", "blue"]
  5. Object: A nested key-value mapping enclosed in curly braces.
    • "address": { "street": "Main St" }
  6. Null: Represents an empty or missing value (lowercase).
    • "middleName": null

Note on Dates: Because JSON does not have a native Date type, dates are usually converted to standard ISO 8601 strings (e.g., "2026-09-19T14:30:00Z") or numerical Unix timestamps before being stored in JSON.

JSON vs. XML: The Turning Point of the Web

To truly appreciate JSON, you have to look at what came before it: XML (eXtensible Markup Language).

In the early 2000s, XML was the standard for data transfer. Let's look at how our earlier user profile would be written in XML:

<user>
  <id>1045</id>
  <username>tech_guru_99</username>
  <isActive>true</isActive>
  <email></email>
  <roles>
    <role>admin</role>
    <role>editor</role>
  </roles>
  <profile>
    <firstName>Alice</firstName>
    <lastName>Smith</lastName>
    <age>28</age>
  </profile>
</user>

Why JSON Won

  1. Less Verbose: XML requires opening and closing tags for every single piece of data (<username>...</username>). This makes the file size significantly larger, which means it takes longer to transmit over a network. JSON strips away this visual noise.
  2. Faster Parsing: Browsers have to traverse XML as a Document Object Model (DOM), which is computationally expensive. JSON can be parsed natively by the JavaScript engine in a fraction of a millisecond using JSON.parse().
  3. Arrays: XML does not have a native concept of arrays. You just repeat tags (like the <role> tags above). JSON's [] syntax maps perfectly to arrays in almost every programming language.

Working with JSON in JavaScript

Because JSON is derived from JavaScript, working with it in JS is incredibly simple thanks to the built-in JSON object, which provides two primary methods.

1. JSON.parse()

This method takes a raw JSON string (usually received from an API) and converts it into a usable JavaScript object.

const jsonString = '{"name": "Alice", "age": 28}';
const userObject = JSON.parse(jsonString);

console.log(userObject.name); // Output: Alice

2. JSON.stringify()

This method does the exact opposite. It takes a JavaScript object and converts it into a JSON string so it can be sent over the network or saved to a file.

const myObj = {
  name: "Bob",
  skills: ["HTML", "CSS", "JS"]
};

const outgoingJSON = JSON.stringify(myObj);
// Output: '{"name":"Bob","skills":["HTML","CSS","JS"]}'

Conclusion

JSON is a triumph of simplicity. By establishing a minimal, strict set of rules, it provided the entire software industry with a universal language for data.

Whether you are configuring a Node.js project (via package.json), fetching data from a third-party API, or building a complex microservices architecture, JSON is the glue holding it all together. By mastering its syntax rules, understanding its supported data types, and knowing how to parse and stringify it in your language of choice, you lay the foundation for almost all modern web and backend development.

Buy me a coffee