JSON Pointer explained with real escaping examples: ~0, ~1, arrays, and root
A practical JSON Pointer guide that makes escaping, arrays, and root paths readable instead of magical.
Tip
Lint or format before comparing data, then check that cleanup did not change the fields, order, or values that matter.
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.
That makes it a good fit for a focused tool: resolve one pointer against one document and show every step clearly.
Summary
Definition: 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.
Pitfall: The escape rules are easy to misread. ~1 means a literal slash in a property name, not a path separator.
Start with the mental model: one token at a time
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/nametargets thenamefield of the first element initems./a~1btargets a key literally nameda/b./m~0ntargets a key literally namedm~n.
Why pointer confusion spills into patch failures
JSON Patch uses JSON Pointer for its path and often from values. That means a misunderstood escape sequence becomes a failed patch operation later. This is a perfect example of why a pointer resolver belongs next to a patch tester rather than inside a generic JSON formatter.
Quick example
Use this when a property name contains a slash or tilde and a patch path stops working.
What to 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" }]
}
Practical check
- Resolve the pointer against a formatted document before embedding it in a patch.
- Decode
~0and~1mentally before blaming the path. - Treat the empty string as the whole document, not as a missing value.
FAQ
Does JSON Pointer return multiple matches like JSONPath?
No. JSON Pointer addresses one exact location at most.
Are slashes inside key names impossible to reference?
No. They are referenced with the ~1 escape.
Developer workflow
Use this guide as a debugging pass before you paste structured data into an API, config file, or migration script.
- Keep one raw copy of the payload before any formatter touches it.
- Lint or format first, then compare important fields and ordering before converting.
- Save the final clean payload separately from notes, comments, and temporary examples.
1. raw payload
2. lint/format without changing meaning
3. compare fields and ordering
4. convert only after validation passes