Understanding JSON: A Complete Guide to Reading and Writing JSON Files

When you are in development or often change some configuration, you likely will come to the situation to read and/or write JSON code.

JSON has become a core format for data exchange across web services (especially when working with APIs) or configuration files for applications and tools, making it a must-know.

What is JSON? Understanding JavaScript Object Notation #

JSON stands for JavaScript object notation: It is a file format where you can describe objects.

Basically you can think of key value pairs, e.g. “My name is Oliver” (key would be name, value would be Oliver).

How to Write JSON: A Beginner’s Guide #

JSON objects always start with { and end with }. So the easiest JSON file you could write, would just contain {} which is an empty object.

Let’s say you want to describe a user as an JSON object, given the “My name is Oliver” example from above, your JSON could look like this:

1
2
3

{
    "name": "Oliver"
}

Data Types Explained: From Strings to Objects #

As you can see in the example above, key and value are wrapped by ". For key, you always will wrap it with ", for value it depends on the type. Like in YML, multiple data types are supported.

A JSON object can have multiple values, in this case they are seperated by ,:

1
2
3
4

{
    "name":      "Oliver",
    "year_born": 1990
}

Whitespaces are ignored #

In the example JSON above, I used spaces and linebreaks for better presentation. In fact, JSON doesn’t care about spaces. So this code here would be the same: {"name":"Oliver","year_born":1990}

JSON array #

Instead of a object you can also define an array directly. That means this JSON would be valid as well:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10

[
    {
        "name":      "Oliver",
        "year_born": 1990
    },
    {
        "name":      "Peter",
        "year_born": 1988
    }
]

This JSON is now a list of users, each having name and year_born property.

How to Create and Work with JSON Files in Any Editor #

After knowing how JSON is structured, it is quiet easy to read and write. JSON files are normal text files that you can open and edit with every editor you like. But instead of txt you use json as a file extension:

1. Create my-first-object.json
2. Open it in your text editor, or your favorit IDE
3. Add your JSON code as shown above, modifiy it to your needs
4. Save the file

Validate JSON files #

While you can work on JSON files with any text editor, using an IDE has benefits.

IDEs do understand the syntax of JSON files and can help you with syntax highlighting in case you do something wrong.

Common mistakes #

Here’s some examples I face every now and then when working with JSON files.

Forget the , #

Some day you will forget to separate multiple values by ,:

1
2
3
4

{
    "name":      "Oliver"
    "year_born": 1990
}

This can cause issues.

, after last array item #

Especially when editing JSON, you probabl will have , after last array item:

1
2
3
4
5
6
7

{
    "year_born": [
        1,
        2,
        3
    ]
}

This can cause issues.