Settings
Fast Delivery
Payment Types
Marketplace Product
Intro to JSON
2026-08-05 | By Maker.io Staff
Programs, especially web applications, need to exchange data, and doing that reliably requires a common format that all systems understand. JSON is one of the most widely used formats for transmitting information between services and storing structured data in files. Read on to learn the basics of JSON, common conventions, and what to avoid.
Serialization Languages and JSON
JavaScript Object Notation (JSON) is most notably used for exchanging data between applications, for example, through web APIs. However, JSON is also commonly used for storing serialized application data locally, for example, in simple files or NoSQL databases. JSON is a so-called serialization language, similar to XML and YAML. These languages are standardized ways of representing structured data so that different systems can reliably store and parse it. Unlike binary data formats, human-readable serialization formats are designed to allow people to also read, understand, and edit the data directly.
When compared to YAML, which prioritizes readability, JSON is a more machine-friendly way of representing structured data. JSON uses a simpler structure and enforces stricter rules, which removes many ambiguities and makes it easier for machines to parse. This often results in a more compact representation and smaller file size compared to YAML or XML, which benefits more streamlined hardware. However, some people may find data stored in the JSON format harder to read.
Conceptual Building Blocks in JSON
JSON defines three basic types of building blocks to store information: values, arrays, and objects. Values represent single primitive values in the form of strings, numbers, booleans, or null values. They are the simplest possible unit of data that can be stored, and they have no internal structure or nesting. For example:
"This is a text" 120 true null
Strings must be enclosed in double quotes, and special characters must be escaped in JSON data. JSON doesn’t support block strings or unquoted string literals.
Arrays are ordered lists of values that can contain simple values, other lists, and more complex objects. Mixing types in the same list is allowed, though this is uncommon in practice as it can cause confusion.
JSON lists start and end with square brackets, and the list elements are separated by commas. For example:
["apple", null, "banana", 24, "cherry"]
Lists can also contain other lists, for example:
[ ["red", "green", "blue"], ["circle", "square", "triangle"], ["small", "medium", "large"] ]
JSON blocks are sometimes indented using spaces or tabs to improve readability. However, that is not necessary for valid JSON code, and is typically automatically done by editors or browsers. JSON data, exchanged between machines, is often just a single long line of text.
JSON objects are collections of key-value pairs, where keys must be enclosed in double quotes and the values are simple primitives, arrays, or other objects. Curly braces mark the start and end of blocks:
{
"name": "Alex",
"age": 34,
"active": true,
"tags": ["reader", "gamer", "builder"],
"address": {
"city": "Riverton",
"country": "Westhaven"
}
}
The blocks are unordered sets of key-value pairs. However, most parsers respect ordering and return the keys in the same sequence they appear in the JSON code. Furthermore, keys should be unique. Most parsers will not throw an error when they encounter a duplicate key. Instead, they overwrite the value using the latest instance in the file. Still, it’s considered good practice to keep keys unique within each block.
Lastly, most JSON files have a root-level object that contains all other key-value pairs. The root-level object is usually specified by lone curly braces in the first and last line. However, this is by convention and not enforced by the specification.
Representing Multiple Instances
JSON can store multiple instances of the same object in a single file using lists of objects. The following example demonstrates how to store multiple user instances in one file:
[
{
"name": "Alex",
"age": 34,
"active": true
},
{
"name": "Mira",
"age": 29,
"active": false
},
{
"name": "Jonah",
"age": 41,
"active": true
}
]
Note that this example does not define a root object. Instead, it contains a single list with three unnamed objects. The objects are separated by commas, just like any other value in a list would be, and there are no trailing commas in JSON. The objects can be accessed via their indices, and each of them has three keys: name, age, and active. This also demonstrates that keys don’t have to be unique in the entire file, only within a block.
JSON Good Practices and Common Mistakes
Brackets and blocks should always be matched carefully in JSON files to avoid parsing issues. Indentations can help improve readability. However, they are not strictly required, and it’s often better to omit them in files that primarily have to be machine-readable to keep the resulting files small.
Strings must always be enclosed in double quotes, and special characters must be escaped. JSON does not support block strings or unquoted string literals.
This image explains the individual structures commonly seen in standard JSON files.
Key names should be descriptive, self-explanatory, and not overly long. JSON does not support trailing commas or comments. Although not strictly required, it’s a common convention to have a single root-level object in the file that nests everything else.
Summary
JSON is a serialization language commonly used when exchanging data between applications. JSON prioritizes simpler parsing and smaller files by enforcing stricter rules, even if readability suffers.
Three types of nodes exist in JSON: values, arrays, and objects. Values are the smallest node type, and they represent primitive data. Arrays are comma-separated, ordered collections of data, and objects are unordered key-value sets of data. The three types can be nested to build more complex structures.
Strings in JSON must always be escaped and enclosed by double quotes. JSON does not support multi-line text, comments, or trailing commas. Hierarchy is defined using brackets, which must be carefully matched to avoid parsing errors.
Key names should be chosen so that they are unambiguous and unique within a block. Although not strictly required, it’s a common convention to have a single root-level object in the file that nests everything else.
