APIs and Data Exchange
JSON (JavaScript Object Notation) was inspired by JavaScript but influenced by Python's dictionary and list syntax, making it structurally similar to Python data structures.
A Familiar Data Format
JSON stands for JavaScript Object Notation. It was inspired by JavaScript, but its design was also influenced by Python's way of representing data, especially dictionaries and lists. That is why JSON often looks immediately familiar to someone who already knows Python.
Objects and Dictionaries
A JSON object is a collection of key-value pairs written with curly braces. A Python dictionary uses the same key-value idea and also uses curly braces. The central mapping is therefore JSON object to Python dictionary. One important difference is that JSON keys must always be strings.
Reading an Object as a Dictionary
Interpret the generated JSON object {"name": "Ari", "level": 3} as a Python data structure.
Identify the outer structure: The curly braces and key-value pairs identify a JSON object.
Map the container: A JSON object maps to a Python dictionary.
Map the entries: The key "name" is paired with the value "Ari", and the key "level" is paired with the value 3. The keys are strings.
The corresponding Python structure is a dictionary containing the key-value pairs name to Ari and level to 3.
Arrays and Lists
A JSON array is an ordered collection written with square brackets. A Python list is also an ordered collection written with square brackets. Both can contain values of multiple types, so the direct structural mapping is JSON array to Python list.
Preserving Array Order
Interpret the generated JSON array ["first", 42, false] as a Python data structure.
Identify the outer structure: The square brackets identify a JSON array.
Map the container: A JSON array maps to a Python list.
Preserve positions: The string is first, the number is second, and the Boolean value is third. The order is part of the structure.
The corresponding Python structure is a list with the same three positions and corresponding values.
Value Type Mappings
| JSON value type | Python equivalent | Structural role |
|---|---|---|
| String | String | Text value; JSON object keys are strings |
| Number | Number | Numeric value |
| Boolean | Boolean | True or false value |
| Null | None | No value representation |
| Object | Dictionary | Key-value pairs in curly braces |
| Array | List | Ordered values in square brackets |
Common JSON categories and their familiar Python counterparts
The most useful mapping is structural: an object becomes a dictionary, and an array becomes a list. The values inside those containers retain their corresponding categories. JSON and Python can also represent mixtures of value types inside an ordered collection, and those collections can be placed inside objects.
Nested Data Structures
JSON objects can contain arrays, and arrays can contain objects. This nesting can continue in different combinations. Python represents the same overall arrangement with dictionaries and lists nested inside one another. To understand a nested value, identify the outer container first, then repeat the mapping for each inner container.
Mapping One Nested Level at a Time
Interpret the generated structure {"items": [{"name": "Ari"}, {"name": "Bo"}]} as Python data.
Map the outer object: The outer curly braces identify a JSON object, so the outer Python structure is a dictionary.
Map the value of items: The value paired with the key items is a JSON array, so that value becomes a Python list.
Map each array element: Each element in the array is another JSON object, so each element becomes a Python dictionary.
The structure becomes a Python dictionary containing a list of dictionaries.
Data Exchange Flow
In a typical data-exchange situation, a Python program may receive JSON data from a web API or read it from a file. The JSON format carries objects, arrays, and values. Because its structure resembles Python dictionaries and lists, the data can be represented in Python using those familiar structures and then manipulated with Python data-handling techniques.
When examining exchanged data, first identify whether the outermost structure is an object or an array. Then map each nested object to a dictionary and each nested array to a list. This outside-in approach reduces the cognitive load of interpreting a new JSON structure.
Common Mapping Mistakes
Treating a JSON object as a Python list
Objects are collections of key-value pairs and map to Python dictionaries.
Fix:
Use the key-value relationship to identify an object-dictionary mapping.Treating a JSON array as an unordered group
Arrays are ordered collections, just as Python lists are ordered collections.
Fix:
Preserve each value's position when mapping an array to a list.Assuming JSON and Python syntax are completely identical
JSON resembles Python dictionaries and lists, but the formats are not identical.
Fix:
Use the structural mapping while checking the specific representation of each value.Stopping at the outer container in nested data
Nested JSON structures require mapping each inner object and array as well.
Fix:
Trace the structure from the outside inward, mapping every nested container.
Practice Mapping
For the generated JSON structure {"title": "Guide", "tags": ["python", "json"]}, identify the Python container corresponding to the outer structure, the container corresponding to tags, and the order of the two tag values.
Hints
- Start with the curly braces.
- Then inspect the value paired with tags.
- Keep the two tag values in their displayed order.
What do you think happens?
Before checking the answer, predict the Python structure represented by {"members": [{"name": "Ari"}, {"name": "Bo"}]}.
Reveal answer
Answer: A dictionary containing a list of dictionaries
The outer object maps to a dictionary. Its members value is an array, which maps to a list. Each array element is an object, which maps to a dictionary.
Key Takeaways
- JSON means JavaScript Object Notation. It was inspired by JavaScript and influenced by Python's dictionary and list syntax.
- A JSON object uses key-value pairs in curly braces and maps to a Python dictionary; JSON object keys must be strings.
- A JSON array uses square brackets, preserves order, and maps to a Python list.
- JSON objects and arrays can be nested, producing nested Python dictionaries and lists.
- JSON's similarity to Python reduces the cognitive load of receiving and manipulating data from web APIs or files.
Key Takeaways
- JSON is a data notation inspired by JavaScript and shaped in part by Python dictionaries and lists.
- JSON objects correspond structurally to Python dictionaries, while JSON arrays correspond to Python lists.
- The order of values in an array is preserved when it is represented as a Python list.
- Nested JSON objects and arrays become nested dictionaries and lists in Python.
- Recognizing the outer container and then tracing inward is a reliable way to interpret exchanged JSON data.