What Is JSON? A Beginner Guide to Syntax, Writing, and Common Errors

If you work with apps or APIs, you will run into JSON almost immediately. It shows up in configuration files, web API responses, and data storage. This article explains, for first-time learners, what JSON really is, how to write it, the pitfalls to avoid, and how to handle it in practice.

What Is JSON

JSON (JavaScript Object Notation) is a lightweight format for representing data as text. As the name suggests, it grew out of JavaScript notation, but today it is a common language used regardless of programming language. Python, PHP, Go, and nearly every language can read and write JSON.

JSON is popular for three reasons:

• Readable by humans and machines: it is plain text, so people can grasp it in an editor and programs can parse it easily.
• Language independent: it is not tied to any one language, making it ideal for exchanging data between systems.
• Expresses structure: it naturally represents nested hierarchies and lists, not just simple values.

For example, information about a user is written like this:

{"name": "Taro", "age": 30, "active": true}

Pairing a "key" with a "value" is the foundation of JSON. Compared with XML it requires less text, and unlike CSV it can express hierarchy, which is why it is the de facto standard in modern web development.

Core Syntax: Objects and Arrays

JSON structure is built from just two containers: objects and arrays. Understand these two and you can read any JSON, no matter how complex.

Objects (curly braces)

An object is wrapped in { } and lists key-value pairs. Keys must be strings wrapped in double quotes, and pairs are separated by commas.

{"id": 1, "title": "Beginner Guide", "published": true}

The crucial point is that keys must be wrapped in "double quotes". Single quotes or no quotes are not allowed in JSON. This is a major difference from JavaScript object notation and a common source of confusion for beginners.

Arrays (square brackets)

An array is wrapped in [ ] and lists values in order. Use it when you want a list of similar values.

["apple", "orange", "grape"]

Objects and arrays can be nested freely. A "list of multiple users," for instance, is an array whose elements are objects.

[{"name": "Sato", "age": 25}, {"name": "Suzuki", "age": 40}]

Real API responses nest these many layers deep. As the hierarchy grows it becomes hard to follow by eye, which is where a formatting tool helps.

Data Types You Can Use

A JSON value can only be one of six types. That small set is exactly what keeps JSON simple and easy to handle.

Note that numbers and booleans are not quoted. "30" is a string while 30 is a number, and the two are treated differently. Also, JavaScript's undefined, functions, and date types do not exist in JSON; dates are usually written as strings (for example "2026-06-28"). Remember, too, that comments (// or /* */) are not allowed.

Common Syntax Errors

JSON is strict about syntax, and even a tiny mistake causes a "cannot parse" error. Here are the traps beginners hit most often.

• Trailing comma: leaving a comma after the last element. {"a": 1, "b": 2,} is an error; the last element takes no comma.
• Unquoted keys: {name: "Taro"} is invalid; it must be {"name": "Taro"}.
• Single quotes: {'name': 'A'} is invalid; only double quotes are valid in JSON.
• Mismatched brackets: when the number of { } or [ ] does not match, which happens more as nesting deepens.
• Comments: JSON does not support them. You may want them in config files, but standard JSON treats them as a syntax error.

These errors are hard to spot by eye alone. Paste your data into the JSON Formatter and it instantly validates the syntax and tells you where the error occurs. At the same time it pretty-prints with indentation so you can verify the nesting at a glance. Everything runs in your browser, so even sensitive data you paste is never sent anywhere.

When to Format, Validate, Convert, and Compare

The tasks you need most often when working with JSON are predictable. Knowing the right tool for each greatly improves your efficiency.

Formatting and validation

JSON returned from an API often arrives minified, on a single line with no breaks. Formatting turns it back into something humans can read. The JSON Formatter not only adds line breaks and indentation but can also minify by stripping unneeded whitespace. It checks syntax too, so it is perfect for "paste it and confirm it is valid."

Converting to YAML

In the world of config files, the more human-friendly YAML format is also common. JSON and YAML express almost the same structures, so they convert back and forth. With the JSON to YAML Converter you can turn JSON received from an API into a YAML config file, or convert YAML back to JSON, in an instant, saving time spent wrestling with notation differences.

Comparing differences

You often need to see which values changed between a before and after version. Comparing two JSON documents by eye is tedious, but the JSON Diff highlights only what was added, removed, or changed. It is invaluable for comparing API responses and reviewing config changes.

Practical Writing Tips

Finally, here are practical points that help when writing and handling JSON.

1. Use a consistent naming convention: settling on either camelCase (userName) or snake_case (user_name) makes later processing easier.
2. Encode in UTF-8: saving as UTF-8 prevents garbled text, even with non-English characters.
3. Use browser-only tools for sensitive data: when JSON contains passwords or personal data, choose tools that never send data externally.
4. Format large JSON first to grasp the structure: visualizing the hierarchy before reading the contents speeds up understanding.
5. Consider JSONC or another format when you need comments: standard JSON disallows comments, so YAML and similar formats are options for configs that need annotation.

JSON has little to memorize yet an extremely wide range of uses. Master objects and arrays, the six data types, and basic rules like no trailing comma, and you will read and write APIs and config files with confidence. Start by pasting some JSON into the JSON Formatter and simply looking at its structure.