JSON for beginners: reading the reply an API sends back

JSON is plain text with a strict tidy layout. Most APIs use it to send answers back. Once you see the pattern, a reply that looks like noise becomes a list of labelled facts.

What JSON is

¹ MDN defines it as "JavaScript Object Notation (JSON) is a standard text-based format for representing structured data".² Wikipedia adds that it "uses human-readable text to store and transmit data objects consisting of name–value pairs and arrays".

Two words matter there: name and value. Everything else is built from them.

The basic shape

Here's a small made-up reply about an order.

{
  "order": "first",
  "paid": true,
  "items": ["pens", "paper"],
  "delivery": {
    "city": "Leeds"
  }
}

This is an invented example, not a real service's reply. Read it one piece at a time.

• Curly brackets wrap a group of labelled things.
• A name, a colon, then a value. "paid": true means the label is paid and the answer is true.
• Square brackets wrap a list. The items are separated by commas.
• Brackets inside brackets mean a group within a group. Here, the delivery group holds a city.

What a value can be

¹ MDN lists the simple kinds: string literals, number literals, true, false and null. A string is text in quotation marks. A number has none. True and false are yes or no. Null means nothing is there.

Bigger values can be a group of names and values, or a list.

The rules that trip people up

JSON is strict. A small slip stops a computer from reading it, so a few rules are worth knowing if you ever edit some by hand.

• ¹ Every name needs double quotation marks around it.
• ¹ "Objects and arrays cannot contain trailing commas ." No comma after the last item.
• ¹ "Comments are not allowed in JSON." You can't add a note inside it.

If a tool says your JSON is invalid, check these three first.

Why APIs use it

¹ MDN says JSON is "commonly used for transmitting data in web applications".² Wikipedia calls it a "language-independent data format". So a service written in one language can answer an app written in another, and both still understand the reply.

Reading an AI reply

When software calls an AI model's API, the maker decides what the reply looks like. Open the maker's documentation to see whether it's JSON and which name holds the model's text. The names differ between makers.

If you ever show a reply to someone else, remove anything private first. Replies can contain customer names or account details. Keep secrets and customer data out of an AI tool when you ask it to explain a reply, unless your business's own policy allows it. Swap real details for made-up ones.

A habit that helps

Read from the outside in. Find the first name. Find its value. If the value opens another bracket, step inside and repeat. You'll rarely need anything more than that. For how the reply gets to you, see requests and responses. For the number that comes with it, see error codes.