JSON Pointer Explained (RFC 6901) with Examples
Understand JSON Pointer, the RFC 6901 standard for addressing a value in a JSON document: slash-separated paths, array indexes, escaping ~ and /, the whole-document pointer, and how it powers JSON Patch.
JSON Pointer is the quiet standard that addresses a single value inside a JSON document with a simple slash-separated path. It is far less famous than JSONPath, but it is everywhere it counts: JSON Patch, JSON Schema errors, and OpenAPI all use it. This guide explains JSON Pointer syntax, its escaping rules, and how it differs from the query languages it is often confused with.
What is JSON Pointer?
JSON Pointer, defined by RFC 6901, is a string syntax for identifying one specific value within a JSON document. Unlike a query language, it does not search or filter — it names an exact location, like a file path into the document. That precision is exactly what standards need when they have to point at a field unambiguously, which is why it underpins JSON Patch and JSON Schema validation errors.
The slash-separated syntax
A JSON Pointer is a sequence of reference tokens, each prefixed by a forward slash. To reach the city in {"user": {"address": {"city": "Paris"}}}, the pointer is /user/address/city. Each slash descends one level. The pointer starts at the document root, and an empty string pointer refers to the whole document itself.
Document: { "user": { "address": { "city": "Paris" } } }
Pointer: /user/address/city → "Paris"
Pointer: "" → the whole documentAddressing array elements
Array elements are addressed by their zero-based index as a token. In {"items": ["a", "b", "c"]}, the pointer /items/0 selects "a" and /items/2 selects "c". A special token, the single dash (/items/-), refers to the position just past the end of an array — used by JSON Patch to append a new element.
{ "items": ["a", "b", "c"] }
/items/0 → "a"
/items/- → the position just past the end (used to append)Escaping ~ and /
Because the slash separates tokens, a key that actually contains a slash needs escaping, and so does the escape character itself. The rules are precise: a literal tilde is written as ~0, and a literal forward slash within a key is written as ~1. So a key named a/b is referenced as a~1b, and a key named m~n as m~0n. Getting this backwards is the most common JSON Pointer bug.
key "a/b" → /a~1b
key "m~n" → /m~0nJSON Pointer versus JSONPath
The two are often confused but solve different problems. JSON Pointer (RFC 6901) addresses exactly one location and cannot wildcard, filter, or search — it is deterministic and simple. JSONPath (RFC 9535) is a full query language that can select many nodes, match conditions, and recurse through a document. Use JSON Pointer when you need to name a single value precisely (as standards do); use JSONPath when you need to query and extract sets of values.
Where JSON Pointer is used
You will meet JSON Pointer most often inside JSON Patch, where every operation names its target location with a pointer like /user/name. JSON Schema validators report errors using pointers so you know exactly which field failed, and OpenAPI and JSON Reference use the related $ref pointer to link definitions. A JSON Patch generator produces these pointers automatically when it diffs two documents, and a JSON Path tool helps when you need richer querying instead.
Frequently asked questions
What is JSON Pointer?
JSON Pointer (RFC 6901) is a string syntax that identifies a single specific value in a JSON document using slash-separated tokens, like /user/address/city. It names an exact location rather than searching, which is why standards like JSON Patch rely on it.
How do I write a JSON Pointer for an array element?
Use the zero-based index as a token: /items/0 is the first element and /items/2 is the third. The special dash token, /items/-, refers to the position after the last element, used for appending in JSON Patch.
How do I escape special characters in a JSON Pointer?
Within a key, write a literal tilde as ~0 and a literal forward slash as ~1. So a key named a/b becomes a~1b. Apply the tilde escape first to avoid double-escaping mistakes.
What is the difference between JSON Pointer and JSONPath?
JSON Pointer addresses exactly one location and cannot filter or wildcard; it is deterministic and simple. JSONPath is a full query language that selects many nodes and supports conditions and recursion. Use Pointer to name a single value, JSONPath to query sets.
Where is JSON Pointer used?
In JSON Patch (to target each operation's location), in JSON Schema validation errors (to identify the failing field), and in JSON Reference and OpenAPI via $ref. It is the standard way to point at a precise spot in a document.
Related tools
Try these tools
JSON Patch Generator
Generate RFC 6902 JSON Patch or RFC 7396 merge patch between two JSON documents.
JSON Path Extractor
Query JSON with dot paths and bracket indices — extract values at any key path.
JSON Pick & Omit Keys
Select or remove top-level keys from a JSON object — whitelist or blacklist fields.
JSON Formatter & Beautifier
Format, prettify, and beautify messy JSON with configurable indentation and key sorting.