What JSON looks like

jq exists to read and reshape JSON, so you need to recognise its few building blocks before anything else.

Programs constantly hand data to each other: a weather service sends today's forecast, a shop sends its product list. They need a shared way to write that data down as text. The most common one today is JSON (short for Object Notation, after the language it came from). It's that you can read yourself.

Here is a small JSON document describing a person:

{
  "name": "Ann",
  "age": 31,
  "admin": true,
  "phone": null,
  "tags": ["ops", "oncall"],
  "address": {"city": "Oslo", "zip": "0150"}
}

The curly braces hold an object: a set of named values, like a filled-in form. Each entry is a key-value pair: a name in double quotes (the key), a colon, then the value. Entries are separated by commas, and each one is often called a field.

Square brackets hold an array: an ordered list of values, separated by commas. ["ops", "oncall"] is an array of two strings. Positions in an array are counted from 0, so "ops" is at position (or index) 0 and "oncall" at index 1.

Every value is one of six kinds:

a string: text in double quotes, "Ann";
a number: 31 or -2.5;
a boolean: true or false, a plain yes or no;
null: a special value meaning "nothing here";
an object or an array.

Objects and arrays can sit inside each other as deep as needed. Above, address is an object inside an object, and an array can just as well hold objects. That nesting lets JSON describe real things, and it's why a tool for digging into it is so useful.

Spaces and between the parts don't matter, so the same document can be one long line, which is how programs usually send it. That's where jq comes in: a terminal program that reads JSON, lays it out readably and pulls out exactly the parts you ask for.

A few strict rules trip people up: keys and strings need double quotes, never single ones; there's no comma after the last entry; and comments aren't allowed.

Example

# The same person written on one line, as programs usually send it:
echo '{"name":"Ann","age":31,"admin":true,"phone":null,"tags":["ops","oncall"],"address":{"city":"Oslo"}}' > ann.json

jq . ann.json      # jq lays it out readably (more in the next lesson)
# {
#   "name": "Ann",
#   "age": 31,
#   "admin": true,
#   "phone": null,
#   "tags": [
#     "ops",
#     "oncall"
#   ],
#   "address": {
#     "city": "Oslo"
#   }
# }

Remember

{ } is an object of "key": value pairs; [ ] is an array (a list)
A value is a string, number, true/false, null, object or array
Array positions (indexes) start at 0

Watch out for

Writing JSON by hand with single quotes or a comma after the last entry; both make it invalid.

New words in this lesson (3)

JavaScript: The programming language that runs inside web pages in the browser. JSON's way of writing data comes from it.
plain text: Text with no hidden formatting, like a .txt file. Code, CSV, JSON and YAML files are all plain text.
newline: The invisible character that marks the end of a line of text (written \n in code). Windows traditionally uses two characters, \r\n.

Check yourself

In `{"tags": ["a", "b", "c"]}`, what is at index 1 of the tags array?
Which of these is valid JSON?

Official docs: www.json.org/json-en.html

Example

Remember

Watch out for

Check yourself

Builds on

Unlocks