JSON path notation explained with real examples

JSON is the most common data format for APIs and web services. Once you start working with it regularly — whether you're building integrations, writing JavaScript, or debugging API responses — you'll constantly need to reach into a JSON structure and extract a specific value. JSON path notation is the language for describing exactly where a value lives inside that structure.

Dot notation

Dot notation is the most readable way to describe a path through a JSON object. You use a period (.) to separate each level of nesting. Starting from the root object, you chain key names together to drill down to the value you want.

For example, to access the city inside an address inside a user object, you would write user.address.city. Each dot moves one level deeper into the structure. Dot notation is clean and easy to read, which is why it's the default choice for simple key names with no special characters or spaces.

Bracket notation

Bracket notation uses square brackets and quoted key names: obj["key"]["nested"]. It is functionally identical to dot notation for simple keys, but it becomes essential when key names contain spaces, hyphens, or other special characters that would break dot notation syntax.

For example, a key named first-name cannot be accessed with dot notation (obj.first-name would be interpreted as subtraction). Bracket notation handles it cleanly: obj["first-name"]. Bracket notation is also useful when the key name is stored in a variable, since you can write obj[variableName].

Accessing arrays

JSON arrays are accessed using numeric indices inside square brackets. Array indices start at 0, so the first item is [0], the second is [1], and so on. You can chain array access with dot or bracket notation to reach nested values inside array items.

For example, arr[0] gives you the first item in an array, and arr[2].name gives you the name property of the third item. This pattern is extremely common when working with API responses that return lists of objects.

Real-world examples

Consider this JSON object representing a user profile:

Here are the paths to access different values from this object:

Common mistakes

• Forgetting that array indices start at 0 — tags[1] is the second item, not the first. This is a frequent source of off-by-one errors.
• Using dot notation with special characters — key names containing spaces, hyphens, or dots must use bracket notation: obj["my-key"] not obj.my-key.
• Ignoring case sensitivity — JSON keys are case-sensitive. user.Name and user.name are different paths and will return different results.
• Assuming a value exists — if any key along the path doesn't exist, you'll get undefined or a null reference error. Always validate data from external APIs before accessing deeply nested paths.

Dot vs bracket — which to use?

Use dot notation as your default. It's shorter, cleaner, and easier to read at a glance. Switch to bracket notation when:

• The key name contains special characters or spaces.
• You're accessing a key dynamically using a variable.
• You're writing code that needs to be unambiguous about key names that look like reserved words.

Both notations can be freely mixed in the same path expression. user.address["postal-code"] is perfectly valid — dot notation for the simple keys, bracket notation where the hyphen would cause a syntax error.