How to Read JSON Paths: A Beginner’s Guide

The first time someone hands you a real API response, it looks fine. A few keys. Some strings. Maybe an array. You copy the value you need, you move on.

Then the response grows. Users get addresses. Addresses get coordinates. Orders get line items, line items get discounts, discounts get metadata. Now you’re staring at four screens of nested braces, counting brackets on your fingers, trying to figure out how to pull one email address out of the mess.

That’s the moment you need to know how to read JSON paths.

A JSON path is a short string that tells you exactly where a value lives inside a JSON document. Once you can read one, deeply nested JSON stops being scary. You look at a value, you write down the path, and now you can pluck it out in any language.

This guide walks through the syntax, the two ways to write a path, and a real API example. By the end, you’ll be able to read any JSON path someone throws at you — and write your own.

What a JSON path actually is

Think of a JSON document like a filing cabinet.

• The whole cabinet is the root. In JSON path syntax, the root is written as $.
• Every drawer, folder, and piece of paper inside is a key or a value.
• A JSON path is the route you take from the outside of the cabinet to a specific piece of paper.

Here’s a small example:

{
  "user": {
    "name": "Ada",
    "city": "London"
  }
}

The path to Ada’s name is:

$.user.name

Read it out loud: “start at the root, go into user, then into name.” That’s the whole trick. Every JSON path is just a set of directions from $ down to a value.

The three symbols you actually need

There are a lot of JSON path operators, but you can read 90% of paths you’ll ever see with three things:

1. $ — the root of the document. Every path starts here.
2. . — go into a key by name.
3. [n] — go into an array position, starting at zero.

That’s it. Let’s see all three together:

{
  "user": {
    "name": "Ada",
    "emails": ["ada@example.com", "ada@work.io"]
  }
}

• $.user → the whole user object
• $.user.name → "Ada"
• $.user.emails → the whole array
• $.user.emails[0] → "ada@example.com"
• $.user.emails[1] → "ada@work.io"

Once your eye gets used to that pattern, reading nested JSON gets much faster. You stop reading the whole document and start reading paths.

Dot notation vs bracket notation

There are two flavors of JSON path notation, and beginners get tripped up by this constantly.

Dot notation is the clean one:

$.user.address.city

Bracket notation is the verbose one:

$['user']['address']['city']

Both point to the exact same value. So why have two?

Because some keys break dot notation. If a key has a dash, a space, or starts with a number, dot notation can’t handle it:

$.x-request-id     ❌ (parser reads this as $.x minus request minus id)
$['x-request-id']  ✅
$.first name       ❌ (space kills it)
$['first name']    ✅

Rule of thumb: use dot notation when your keys are plain words. Switch to brackets the moment a key has anything weird in it, or when you’re grabbing something from an array.

A real example: reading a JSON path from an API response

Let’s use something that looks like a real API. Here’s what a typical order lookup might return:

{
  "order": {
    "id": 10234,
    "status": "paid",
    "customer": {
      "name": "Jamie Chen",
      "email": "jamie@example.com",
      "address": {
        "street": "12 Baker Street",
        "city": "London",
        "postcode": "NW1 6XE"
      }
    },
    "items": [
      { "sku": "MUG-001", "qty": 2, "price": 12.50 },
      { "sku": "TEE-042", "qty": 1, "price": 24.00 }
    ]
  }
}

Now try reading these paths without scrolling back up:

• $.order.status — what’s the status? paid
• $.order.customer.name — who’s the customer? Jamie Chen
• $.order.customer.address.city — where do we ship? London
• $.order.items[0].sku — first item’s SKU? MUG-001
• $.order.items[1].price — second item’s price? 24.00

If you got those, you’re done. Reading a JSON path is a skill you can pick up in ten minutes and use for the rest of your career.

The tricky part isn’t the syntax. It’s the counting. Once your JSON gets past three or four levels deep, holding it all in your head gets rough. And that’s where a tool saves you.

The lazy way: let a tool find the path for you

Even people who write JSON paths every day don’t hand-count brackets. They paste the JSON somewhere, click the value they want, and copy the path.

That’s the whole reason we built JSON Path Finder. Paste any JSON. Click any value. The exact path appears — already copied to your clipboard.

Here’s the workflow, which takes about five seconds:

1. Copy your API response.
2. Paste it into JSON Path Finder.
3. Click the value you actually need.
4. Path appears at the top. Paste it into your code.

No signup, no upload, no waiting for a page to load. Everything runs in your browser, and it handles big responses without freezing — the v2.0.0 rewrite dropped the file size by around 450 kB, so it’s fast even on huge payloads.

If you spend a lot of time in Chrome DevTools looking at API responses, there’s also a JSON Path Finder Chrome Extension that lets you do the same thing directly on any JSON response in your browser.

A few things to watch out for

Now that you can read a path, here are the traps that catch new developers.

Arrays start at zero. items[0] is the first item, not the second. This trips people up more often than you’d think, especially when they’re translating a spec from a non-programmer.

A missing path is silent. If you write $.user.address.zip and the JSON has no zip, most tools just return nothing — no error, no warning. Always double-check your path against the actual response, not what you think the response looks like.

Dashes are the number one killer. Any time you’re grabbing something like x-request-id, content-type, or stripe-signature, you need bracket notation.

Root is the whole document, not the first key. $ is the outermost {. If you write $.user and the JSON starts with { "data": { "user": ... } }, your path is wrong — you need $.data.user.