Structured Data with JSON

CSV represents a flat table. A record can also contain a list or another record, as in Part 4. JSON is a text format that represents those nested relationships directly.

Python Values and JSON Text

Start with one small record:

record = {"ready": True, "note": None, "scores": [2, 5]}

The same information in JSON is:

{"ready": true, "note": null, "scores": [2, 5]}

JSON uses double quotes around strings, true and false for booleans, and null for the absence of a value. JSON is data, not Python source code. Use a parser to read it rather than trying to execute it.

Convert Between Values and Text

json.dumps(data) produces a JSON string. json.loads(text) parses a JSON string into Python values. Predict the types and final score before running this example:

The text is one string, even though it describes several values. Parsing constructs the dictionary and list that the program can access. A JSON document can also describe a list or a simple value at its outermost level; the result is not always a dictionary.

Trace these conversions before adding files:

Write and Load One Document

For an open file, use json.dump(data, file) and json.load(file). The versions ending in s work with strings; the versions without it work with files.

This complete example saves two session records and reads them back during the same Run. Predict whether the loaded minutes need int(...) as they did with CSV.

indent=2 formats the output for people; it does not change the represented data. Use string keys in saved dictionaries. JSON object keys are strings, so numeric Python keys should not be expected to remain numeric after a round trip.

Write the whole collection once. Several consecutive dump calls do not produce one valid JSON document. To save several records, put them in a list and save that list.

Try sessions = [] in the editor. Remove the final assertion about the first item, because an empty list has no item at index zero. The equality check should still pass.

Now put the file operations into two functions. This task assumes valid session records; the next chapter adds validation.

Restored Data Has Its Own Objects

Loading creates new dictionaries and lists. It does not reconnect the loaded records to the original in-memory objects.

Predict both lists before running the example. This is different from the shallow copies in Part 4.

JSON preserves the supported values and their structure, not the shared-object relationships of the original program.

An empty list also has a representation: []. A file containing those two characters is valid JSON. A file with no characters is not a JSON document and cannot be loaded as an empty list.

Related CSV Files or One Nested JSON Document?

The same information can have more than one representation. Suppose we want word pairs and their practice attempts.

One CSV file can hold the vocabulary:

id,finnish,english
1,yksi,one
2,kaksi,two

A second CSV file can hold attempts, referring to a pair by its identifier:

word_id,direction,response,correct
1,fi-en,one,1
2,fi-en,thu,0
1,en-fi,yksi,1

To connect them, first read both files, then find each attempt’s word pair. The dictionaries below are what the CSV readers would produce. Predict which Finnish word is printed for each attempt.

Change the second attempt’s identifier to "99". The lookup fails because there is no matching word. A file reader can parse both files successfully while the relationship between them is invalid. A complete loader must check that identifiers are unique and references exist before using them.

A JSON document can instead keep each word with its attempts:

[
  {
    "finnish": "yksi",
    "english": "one",
    "attempts": [
      {"direction": "fi-en", "response": "one", "correct": true},
      {"direction": "en-fi", "response": "yksi", "correct": true}
    ]
  }
]

Here the nesting expresses which word the attempts belong to. There is no second-file lookup for that relationship. Adding another attempt normally means loading, updating, and rewriting the document; appending a separate JSON object would not preserve this one-document format.

Keep Historical Questions Understandable

Word Practice uses the third design. Its history records include the displayed word, expected translation, actual response, direction, and correctness. They can still be read after a word is removed from the vocabulary.

This repetition is deliberate: the row records what was asked at the time. Looking up only today’s translation could change the apparent meaning of an earlier answer. The initial game does not need identifiers; a later version could add stable identifiers while retaining historical question details.

CSV is convenient for this game’s two flat tables. JSON would be useful for exporting a complete vocabulary-and-history collection in one nested document. The file format and the decision to keep information in one or several files are related choices, but neither dictates the other.

Check Your Understanding

1. What differs between a Python dictionary and a JSON string describing it?
2. Which pair of operations uses open files, and which pair uses strings?
3. Why is [] different from an empty file?
4. Does loading a saved list preserve references to the original in-memory records?
5. What must a program check when an attempt refers to a word by identifier?
6. When would you choose linked CSV tables, and when a nested JSON document? Give one use and one responsibility for each design.