Nesting: Objects Inside Objects
Look back at the station specimen: "location": {"lat": 47.21, "lon": 8.55}. The value of location is itself an object — an object inside an object, like a folder inside a folder. This is nesting, and it is how JSON says "this fact has parts." Reading a path to a buried field is the one skill that makes any response, of any size, navigable.
Why Data Nests
Latitude and longitude are two parts of one fact — a place. Grouping them under one label is tidier than scattering location_lat and location_lon across the object, and APIs nest wherever facts have natural structure: an address with street and city inside it, a rider with a stats block, a ride with start and end points. Deep nesting is not complexity showing off; it is organization. Five tidy hops read easier than fifty flat fields with underscores doing the grouping's job badly.
Reading a Path
Spoken aloud, a buried field is a chain of labels: "the station's location's lat." Written down — in documentation, in conversation between colleagues — it is a dotted path: location.lat. Every nested value has exactly one such path, and the path is its full name. One clarification that saves confusion: the dots are how humans talk about JSON. The data itself contains only the nesting — braces inside braces — never the dotted names.
Arrays Join the Chain
When a list sits in the path, position joins the labels. The stations list is an array, so "the third station's name" is: position 2, then label name — written stations[2].name. Why 2 for the third? Positions count from zero — first is 0, second is 1 — a convention inherited from programming that JSON tooling follows everywhere. Mixed chains read one hop at a time, outside in: array, position, label, label. Never all at once, always one hop.
The Docs Draw the Map in Advance
Here is where this skill doubles its value. API documentation describes every response's shape before you ever send the request — a schema: the fields, their types, their nesting, written as exactly the paths you just learned to read. When Chapter 6 opens a reference page and shows location.lat — number, you will be reading the response's floor plan in advance. Nesting is why schemas exist, and path-reading is the skill that makes them useful.
- "Deep nesting means complicated data." It means organized data — facts grouped where they belong. The alternative is fifty flat fields with underscore names doing the grouping badly.
- "I read JSON top to bottom, like prose." You read it like a map: find your path, follow it hop by hop, ignore everything else. The next page turns that into a full strategy.
- "Dotted paths like location.lat appear in the data." Dots are how humans and docs talk about JSON. The data holds only the nesting itself — braces inside braces.
- "The third element is [3]." Positions count from zero: first is [0], third is [2]. Every tool follows this convention, and it trips everyone exactly once.
- "What is the path to the field I need?" is the single question behind extracting anything from any response — the Thursday report's daily work, in its purest form.
- Schemas in documentation are this page's skill applied in advance. Learn to read paths on data now, and Chapter 6's reference pages become floor plans instead of walls.
Knowledge Check
Why do APIs nest data instead of keeping every field flat?
- To make responses smaller and faster to send over the network
- Because some facts have parts, and grouping the parts under one label is tidier
- To hide advanced fields from beginners while keeping them available
- Because the JSON format requires at least two levels of structure in every response
In the path stations[2].name, what does each hop do?
- Take the second station from the list, then read its name label
- Take the third station (positions count from zero), then read its name label
- Take the first two stations, then list both of their names together
- Search all of the stations for one named 2 and return its name label
What is a schema, as the documentation uses the word?
- A sample response copied from a real request, shown for reference
- The list of query parameters that an endpoint is willing to accept
- The response's shape written down in advance: its fields, types, and nesting
- The rules describing who is allowed to request each individual field
You got correct