JSON Dot Notation Explained — How It Works and How to Convert Both Ways

JSON dot notation is a way of writing a nested path as a single string: user.address.city means "inside the user object, inside the address object, the city field." It is not a JSON syntax feature — it is a convention used by JSONPath, lodash, Python pandas, template engines, and flat config files to refer to deeply nested values without writing chained brackets.

This guide covers what dot notation means, where you actually see it, how it differs from bracket notation, and how to convert nested JSON into dot-notation keys (or back) using a free browser tool.

What JSON Dot Notation Is (and Is Not)

Dot notation is a path expression. A JSON object like this:

{
  "user": {
    "name": "Alice",
    "address": { "city": "NY" }
  }
}

...can be referenced with paths like user.name and user.address.city. Each dot separates a step down into the object tree.

Two things dot notation is not:

1. It is not part of the JSON spec. Valid JSON does not allow dots in key syntax. You cannot write {"user.name": "Alice"} and expect a JSON parser to treat it as nested — it is just a key that happens to have a dot character in its name.

2. It is not universally standardized. JSONPath uses dots. Lodash uses dots. Many template engines use dots. But the exact rules for escaping, array indexes, and special characters vary between libraries. Check your target library's docs for edge cases.

Dot Notation vs Bracket Notation

Both notations refer to the same paths; they differ in syntax and in what characters they can represent.

Dot notation: user.address.city

Bracket notation: user["address"]["city"] or in JSONPath $.user['address']['city']

Dot notation is shorter and easier to read, which is why most config files and template engines use it. Bracket notation is more powerful — it can reference keys with spaces (user["full name"]), keys with dots in them (["version.1.0"]), and numeric array indexes (items[0]).

In JavaScript, dot notation and bracket notation produce identical results for simple property access: obj.user.name and obj["user"]["name"] return the same value. You only need bracket notation when the key contains characters that would break dot syntax.

In JSONPath, both work, and tools like jq use a similar pattern with .user.address.city for paths.

Sell Custom Apparel — We Handle Printing & Free Shipping

Where JSON Dot Notation Actually Shows Up

JSONPath queries. $.users[0].email uses dots to walk a JSON tree. Used by tools like jq, jsonpath-plus, and most API testing platforms.

Lodash get/set. _.get(obj, "user.address.city") looks up a nested value by path string. Same with _.set() for mutation.

Pandas DataFrames. pd.json_normalize() produces column names in dot notation by default — {"user":{"name":"Alice"}} becomes a column named user.name.

Template engines. Handlebars, Mustache, and Jinja use dot paths to access nested context values: {{user.name}}.

Flat config files. Spring application.properties, many .env-style formats, and Kubernetes ConfigMaps use dot-notation keys to represent what is conceptually a nested structure: database.connection.timeout=30.

CSV exports of nested JSON. When you flatten nested data into a spreadsheet, the column headers typically become dot-notation paths. See our guide on converting nested JSON to CSV with dot notation.

How to Convert Between Nested JSON and Dot Notation

You usually need to convert in one of two directions:

Nested JSON → dot-notation keys (flatten). Paste your nested JSON into the JSON Flattener, click Flatten, and copy the result. Every leaf value gets a dot-path key.

Dot-notation keys → nested JSON (unflatten). Paste the flat object, click Unflatten, and the tool rebuilds the nested structure. Full walkthrough in the unflatten guide.

Both conversions run in your browser — nothing is uploaded. For a typical API payload (a few KB), the conversion finishes in milliseconds.

If your dot notation uses a different separator (some systems use slashes for JSON Pointer-style paths, or underscores to avoid collisions), change the delimiter field before running the conversion.

How Arrays Work in JSON Dot Notation

Arrays are where dot notation gets inconsistent across libraries. Three common conventions:

Numeric index after a dot: users.0.name, users.1.name. Used by lodash, pandas, and our JSON Flattener when arrays are expanded.

Bracket index: users[0].name. Used by JSONPath and most programming languages.

Leaf preservation: The array is kept as a single value, not expanded into indexed paths. {"users":[...]} flattens to {"users":[...]}. This is what our JSON Flattener does by default — it makes CSV export cleaner.

If you need array indexes expanded into dot-notation paths (for example, to feed into pandas directly), a code library is your best bet. For the common workflow of "flatten for spreadsheet export, then open in Excel," leaf preservation is what you want.

Frequently Asked Questions

Is dot notation part of the JSON standard?

No. The JSON spec (RFC 8259) defines the syntax for JSON itself and does not specify path expressions. Dot notation is a convention used by tools built on top of JSON — JSONPath, lodash, template engines, config file formats. A key with a dot in it is just a key with a dot; JSON parsers do not interpret it as nested.

When should I use dot notation vs bracket notation?

Use dot notation when your keys are plain alphanumeric strings and readability matters. Use bracket notation when keys contain spaces, dots, or special characters, or when you need numeric array indexes. Most production code mixes both — dots for simple paths, brackets for edge cases.

Can dot notation handle keys with spaces?

Not directly. A path like user.full name is ambiguous — is "name" a separate property or part of "full name"? Bracket notation handles this cleanly: user["full name"]. If you need dot notation with unusual keys, pick a different delimiter that never appears in your key names.

How do I represent an array index in dot notation?

It depends on the library. Lodash accepts both users.0.name and users[0].name. JSONPath requires brackets: $.users[0].name. Pandas uses dots: users.0.name. Check your target library. Our JSON Flattener preserves arrays as leaf values by default, which avoids the ambiguity for CSV and spreadsheet use cases.