Parsing JSON in Python
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.
Try it: Parsing JSON into Python
How json.loads() reads JSON text token by token and builds Python dicts, lists, strings, numbers, True/False and None, how an access path like data["users"][0]["name"] walks that structure, and what json.dumps() writes back.
How it works
- The scanner reads the next token: a brace or bracket, a string in double quotes, a number, true / false / null, or a ',' / ':' delimiter.
- '{' starts a Python dict and '[' a list; both are pushed on a parse stack until their closing '}' or ']'.
- Inside a dict every key must be a double-quoted string followed by ':' and a value; items are separated by ','.
- Anything else stops the parse with JSONDecodeError, reporting the message, line, column and character position.
- The access path is applied one subscript at a time: dicts take keys (KeyError if missing), lists take integer indexes (IndexError if out of range).
- json.dumps() turns the Python objects back into JSON text (True → true, None → null), optionally indented.
Default run (43 steps): json.loads() receives 105 characters of text. The scanner starts at char 0 and reads one token at a time. … json.dumps(data, indent=2) turns the Python objects back into JSON text (171 characters): True → true, None → null, and strings get double quotes.
Simplified: Written from scratch to match CPython 3.12's json module (messages and positions checked against it); input is limited to 400 characters and 24 nesting levels, and the access path accepts only ["key"] and [index] subscripts. Python 3.13 reports a trailing comma in an object with a different message.
Loading the simulation…
From Text to Data
When Python receives JSON from a web API or reads it from a file, the JSON begins as data written in a text format. Parsing turns that JSON into Python data structures that can be worked with directly. The important transformation is not merely reading characters: a JSON object becomes a Python dictionary, and a JSON array becomes a Python list.
JSON Origins and Structure
JSON stands for JavaScript Object Notation. It was inspired by JavaScript, but its design was influenced by Python as well. In particular, Python's dictionaries and lists helped shape the way JSON represents data. That is why JSON often feels familiar to someone who already knows Python.
The resemblance is structural. JSON objects use curly braces and key-value pairs, like Python dictionaries. JSON arrays use square brackets and ordered values, like Python lists. This similarity makes JSON easier to work with in Python and reduces the amount of new structure a Python learner has to understand.
| JSON structure | Python structure | Shared idea |
|---|---|---|
| JSON object | Python dictionary | Key-value pairs inside curly braces |
| JSON array | Python list | Ordered values inside square brackets |
The two main structural mappings covered in this article
Objects, Arrays, and Nesting
Tracing a Nested Structure
Consider a JSON object containing a name value and an array of two interests. What Python structures should result after parsing?
- 1Identify the outer structure
The outer JSON structure is an object, so it maps to a Python dictionary.
- 2Identify the nested structure
The interests value is an array, so that nested part maps to a Python list.
- 3Preserve the arrangement
The dictionary keeps the key-value relationship, while the list keeps the order of the two array values.
The parsed result is a Python dictionary containing a Python list. JSON objects can contain arrays, and arrays can contain objects, so nesting can continue in either direction.
Nesting is one of the most useful parts of the mapping. An object can contain an array, an array can contain an object, and these structures can continue to be nested. After parsing, the same overall arrangement is represented with dictionaries and lists inside one another.
Structural Data Types
A JSON object is a collection of key-value pairs written with curly braces. It maps to a Python dictionary. JSON object keys must always be strings.
A JSON array is an ordered collection of values written with square brackets. It maps to a Python list, and the values can be of multiple types.
| JSON value structure | Python equivalent | Important property |
|---|---|---|
| Object | Dictionary | Key-value pairs; JSON keys are strings |
| Array | List | Values remain ordered |
Structural JSON types and the Python structures they map to
Mistakes Beginners Make
Common mistake Treating every parsed JSON value as a Python dictionary
What it looks likeA JSON array at the outermost level is expected to become a dictionary.
Why it failsJSON arrays map to Python lists, not dictionaries.
Do this insteadIdentify whether the outer structure is an object or an array before deciding which Python structure represents it.
Common mistake Assuming that JSON object keys can use any kind of key
What it looks likeA JSON object uses a non-string value as its key.
Why it failsJSON object keys must always be strings.
Do this insteadTreat JSON object keys as strings when reasoning about the resulting Python dictionary.
Common mistake Ignoring order in an array
What it looks likeThe first and second values in a JSON array are treated as interchangeable.
Why it failsJSON arrays are ordered collections, and they map to ordered Python lists.
Do this insteadPreserve the position of each array value when following the parsed result.
Common mistake Assuming nesting changes the basic mapping
What it looks likeAn array inside an object is treated as an unfamiliar special structure.
Why it failsJSON objects can contain arrays, and arrays can contain objects.
Do this insteadApply the same mapping at each level: object to dictionary and array to list.
Practice the Mapping
A JSON structure has an outer array. Its first value is an object, and that object contains another array. Describe the Python structure after parsing, including the Python type corresponding to each level.
Hints
- Start with the outermost structure.
- Map each object to a dictionary and each array to a list.
- Describe the structures from the outside inward.
What do you think happens?
What Python structure should represent a JSON object whose value is an array?
Reveal answer
A Python dictionary containing a list
The outer JSON object maps to a Python dictionary, and its nested JSON array maps to a Python list.
Key Takeaways
- 1JSON means JavaScript Object Notation. It was inspired by JavaScript and influenced by Python's dictionary and list syntax.
- 2A JSON object uses key-value pairs in curly braces and maps to a Python dictionary.
- 3A JSON array uses square brackets for an ordered collection and maps to a Python list.
- 4Nested JSON objects and arrays become nested Python dictionaries and lists.
- 5JSON's similarity to Python structures makes parsed data more familiar and easier to manipulate in Python.
At a glance
- Parsing JSON changes JSON text into usable Python data structures.
- JSON objects map to Python dictionaries, while JSON arrays map to Python lists.
- JSON preserves nested relationships between objects and arrays during this structural mapping.
- JSON's design was inspired by JavaScript and influenced by Python's dictionaries and lists.
- Recognizing the outer structure and then tracing nested structures is the key skill.