JSON and Data Shapes
Read a response without mistaking its shape for its meaning. · Technical Fluency · Lesson 20 · 3 min
JSON and Data Shapes · 3 min
Situation
“The field is there, so why isn’t it displayed?”
A customer profile response includes a plan field, but some users see no plan name. The field may be null, nested differently, or missing for certain account types.
Looking at one happy-path example is not enough to understand the contract. A PM should be comfortable asking what the other valid shapes look like.
Read the shape
Objects name things; arrays collect things.
{
"id": "u_42",
"active": true,
"plan": {"name": "Team", "seats": 5},
"roles": ["member", "billing"],
"last_login": null
}Curly braces contain an object of key-value pairs. Square brackets contain an array. Values can be strings, numbers, booleans, objects, arrays, or null. Here plan is a nested object and roles is a list.
Interpret
Similar-looking values behave differently.
The number 5 is not the string "5". An empty roles array means the list has no entries. A missing key and an explicit null may have different meanings in the API contract.
Ask whether null means unknown, not applicable, or not yet recorded. JSON gives you the structure; the product and API documentation supply the meaning.
Failure case
The sample hides an edge case.
A design shows one role label. The real response allows several roles. Displaying only the first could conceal billing access or misrepresent permissions.
Likewise, a price field without currency or unit can be dangerous. Does 1500 mean cents, whole units, or another scale? The value alone cannot answer.
PM question
Which valid cases must the interface handle?
Request examples for empty, missing, multiple, and unexpected values. Ask what the UI should show for each case, including long text and unfamiliar enum values.
Do not patch a display problem by inventing a default with business meaning. “Unknown” is often more honest than showing a fabricated plan or amount.
Remember this
Read structure, then ask about semantics.
Identify the object, list, nesting, and type. Then clarify units, optionality, and edge cases before deciding how the information should appear.