Data Formats & Debugging

JSON Pointer Explained

Read and write JSON Pointer paths, including escaped slashes, tilde characters, array indexes and the document root, with worked examples.

Encrypt Online Editorial TeamPublished April 20, 20263 min read

Encrypt Online guide cover on a apricot background with the headline "JSON Pointer". JSON braces enclose one sparse stepped path terminating at a single filled point. It represents following property and array-index steps to one exact value in the document. It contains no mouse cursor or search lens.

JSON Pointer looks harder than it is because the escaping rules are unfamiliar at first glance. Once you see a few real examples, the syntax becomes very mechanical.

A focused resolver should apply one JSON Pointer to one document and show each resolution step.

In brief

What it is: JSON Pointer is a string syntax for identifying one exact location inside a JSON document.

Why it matters: It powers exact targeting in places like JSON Patch and configuration systems that need a single unambiguous path.

Worth knowing: In a JSON Pointer token, ~1 represents a literal slash inside a property name and / separates path tokens.

Read JSON Pointer Tokens in Sequence

A pointer is read as a sequence of reference tokens separated by /. Each token names one step down the JSON structure. Objects use property names. Arrays use indexes. The empty string points to the whole document. That is the whole model before escaping enters the picture.

The syntax feels odd mainly because / already means “next token,” so a literal slash inside a property name has to be escaped.

The two escapes that matter

RFC 6901 only defines two escape sequences for reference tokens. ~0 becomes a literal tilde and ~1 becomes a literal slash. That means you decode the token before you look it up in the object. Once you internalize those two substitutions, the rest of the syntax becomes much calmer.

Arrays are simpler: the token is the zero-based index. The hard part is usually knowing whether you are still in an object or already inside an array.

"" points at the whole document.
/items/0/name targets the name field of the first element in items.
/a~1b targets a key literally named a/b.
/m~0n targets a key literally named m~n.

Why pointer confusion spills into patch failures

JSON Patch uses JSON Pointer for its path and from values. That means a misunderstood escape sequence becomes a failed patch operation later. Use the pointer resolver to check the target value before testing the patch.

See it in a small example

Notice: The correct pointers are /a~1b, /m~0n, and /items/0/name. Read the tokens after unescaping them.

{
  "a/b": 1,
  "m~n": 2,
  "items": [{ "name": "alpha" }]
}

What to verify

Resolve the pointer against a formatted document before embedding it in a patch.
Decode ~0 and ~1 mentally before blaming the path.
Treat the empty string as the whole document, not as a missing value.