RFC 6901 defines a string syntax for identifying one specific value inside a JSON document — a slash-delimited path like /components/schemas/Product/properties/price. It is the addressing layer underneath the fragment half of $ref, underneath JSON Patch, and underneath the pointer RFC 9457 uses to say which part of a request was wrong.
JSON Pointer
JSON Pointer is the small, boring, load-bearing piece of the reference story. It does exactly one thing: given a JSON document, it names one value inside it, using a string of slash-separated reference tokens.
- A path, not a query -
/paths/~1products/getidentifies a single location. It cannot filter, cannot match conditionally, and cannot return a set. That constraint is the feature. - Escaping is the sharp edge -
~becomes~0and/becomes~1, in that order, which is why a path segment containing a slash looks alarming the first time you see one. - The fragment half of
$ref- When a$refreads#/components/schemas/Product, the part after the#is a JSON Pointer. The URI comes from RFC 3986; the pointer comes from here. - Carried by other specs - JSON Patch uses it to say where to apply an operation, and Problem Details uses it to point at the offending member of a rejected request body.
I came at this from the direction of trying to name what we are actually doing when we reach across
JSON and YAML. There are expressions, references, queries and pointers, and they are not synonyms —
JSONPath and JMESPath select, $ref references, and
JSON Pointer points. Being sloppy about which one a tool implements is how you end up with a rule
that silently matches nothing.
Written up in: My Rabbit Warren of JSON Expressions, References, Queries, or Pointers
