JSON data

Data with a shape

A CSV file is a flat table of rows and columns. Some data does not fit a table. A station has opening hours, and the hours have a start and an end. JSON is a text format for data with such a shape. Web services send JSON, programs keep their settings in JSON, and language models read and write JSON.

{
  "name": "Harbor Gate",
  "docks": 16,
  "active": true,
  "hours": {"from": "05:00", "to": "23:00"},
  "tags": ["harbor", "ferry"],
  "closed_since": null
}

JSON looks like Python. The table shows what each part becomes when Python reads it.

JSON	Python
an object in braces { }	a dictionary
a list in brackets [ ]	a list
text in double quotation marks	a string
a number	an int or a float
true and false	True and False
null	None

Numbers stay numbers. You do not convert them. This is an important difference from CSV.

Read JSON

The function json.load reads a file.

import json

with open("station.json", encoding="utf-8") as file:
    station = json.load(file)

print(station["docks"] + 1)       # 17
print(station["hours"]["from"])   # 05:00
print(station["tags"][0])         # harbor

You get a value inside a value step by step: first the key hours, and then the key from.

json.loads does the same for a text that you already have. The s at the end means "string".

point = json.loads('{"x": 2, "y": 5}')
print(point["y"])   # 5

Write JSON

json.dumps makes JSON text from a Python value. indent=2 puts each value on its own line.

text = json.dumps({"name": "Old Mill", "active": True}, indent=2)
print(text)

{
  "name": "Old Mill",
  "active": true
}

One value on each line

Logs and large sets of data often use a simpler form. Each line of the file is one complete JSON value. The name of this form is JSON Lines, and the file name often ends in .jsonl. json.load cannot read such a file, because the whole file is not one JSON value. Read it line by line.

events = []
with open("events.jsonl", encoding="utf-8") as file:
    for line in file:
        if line.strip() != "":
            events.append(json.loads(line))

The test sets of AI apps often use this form.

Your turn

This lesson has two data files. stations.json is one JSON object. repairs.jsonl has one repair on each line, and one line is empty. Do the tasks in order.