JSON Pointer Tildes: Reading Escaped Tokens Correctly

On this page
AI-generated illustration; not taken on location · Illustration comparing a single escaped token with two nested tokens, showing how ~1 and ~0 decode inside a JSON Pointer.
AI-generated illustration; not taken on location · In JSON Pointer tokens, ~1 stands for a slash and ~0 stands for a tilde, and the escapes decode only after the pointer has been split.AI-generated illustration

What the Two Escapes Represent

A JSON Pointer addresses a value inside a document as a sequence of tokens separated by slashes. Because the slash is the separator, a property name that itself contains a slash would be unreadable — so the format defines two escapes, and only two: ~1 stands for a slash, and ~0 stands for a tilde.

const doc = { "a/b": 1, "a": { "b": 2 } };

// "/a~1b"  → token "a/b"  → 1   (one property, escaped)
// "/a/b"   → tokens "a","b" → 2 (two properties, nested)

The order of the escapes is not decoration. Decoding ~0 before ~1 corrupts input like ~01, which should decode to /1 but would decode to ~1 and then again to /. Every correct implementation performs the substitution in one pass, tilde-first, or uses a single regex that consumes both pairs at once.

const decode = t => t.replace(/~1/g, '/').replace(/~0/g, '~');
decode('~01');   // '/1' — correct order is ~1 then ~0? No:
// replace(~1) runs first here and finds nothing; then ~0 gives '~1'. WRONG.

That snippet is the classic bug, written out deliberately. The correct single-pass form is:

const decode = t => t.replace(/~([01])/g, (_, c) => c === '1' ? '/' : '~');
decode('~01'); // '/1'
decode('~10'); // '~'

Split First, Decode Second

The escapes exist because tokens are delimited before they are interpreted. That ordering is the whole mental model: take the pointer string, split it on /, and only then decode each piece. Doing it in the other order — decoding the whole pointer and then splitting — merges a~1b and a/b into the same text, and the distinction the format exists to preserve is gone.

const tokens = pointer.split('/').map(decode);
// leading empty string before the first '/' marks the root-relative form

Two boundary details complete the picture. The empty pointer "" addresses the whole document. A pointer starting with / yields a leading empty token that marks the root-relative form and is discarded, not decoded.

Tracing an API Error to an Escaped Field

Structured API errors increasingly quote pointers as the location of a validation failure. Reading one under time pressure is where the escapes earn their keep:

{
  "type": "https://example.test/problems/schema",
  "detail": "value rejected at /properties/a~1b",
  "instance": "/problems/demo-2"
}

The pointer /properties/a~1b names one property: properties, then the key a/b. The escaped form is not a display quirk to clean up — it is the address. Searching the schema for a property literally named a~1b will fail; searching for a/b finds it.

const [root, ...rest] = '/properties/a~1b'.split('/').map(decode);
// root === '' (discarded), rest === ['properties', 'a/b']
schema.properties['a/b']; // the rejected subschema

The Escape Rules Are Short Enough to Memorize

Worth restating in full, because implementations get them wrong in small ways that surface rarely:

  • ~1 decodes to /, ~0 decodes to ~, in a single pass.
  • Nothing else escapes. A literal %, space or unicode character is untouched at the pointer layer.
  • The tilde is the only escape initiator; a pointer containing ~ not followed by 0 or 1 is malformed and should be rejected, not leniently parsed.
  • Encoding applies the replacements in reverse order — tilde first — for exactly the same pass-related reason as decoding.

Two properties follow from this brevity. Pointers are safe to compare as strings after canonical encoding, which is why patch documents use them for equality checks. And pointers never contain ambiguity once decoded: the mapping between encoded and decoded forms is a bijection, unlike percent-encoding where history produced several conventions.

// bijection check, worth keeping as a unit test
const round = s => encode(decode(s));
['a/b','a~b','~01','~10','x~1~0y'].every(k => round(k) === k); // true

Read Each Token Against the Value It Lands On

A pointer is evaluated left to right, and each token’s meaning depends on the value reached so far. On an object, a token is a decoded property name. On an array, a token must be a decimal index — 0, 1, 2 — and the format explicitly forbids +, leading zeros and non-digits there. On any other value, evaluation fails.

const doc = { list: [{ id: 'x' }, { id: 'y' }] };
// '/list/1/id' → tokens 'list','1','id' → 'y'
// '/list/01/id' → invalid: leading zero in an array index

Reading tokens against their context also explains the honest failure mode of a partial match. The pointer /list/3 against a two-element array does not “almost work”; it fails at the third token, and the failure message should say which token and which value.

Finding the First Token That Fails

When a pointer does not resolve, the useful diagnostic reports the deepest token that succeeded. Walking tokens against the document makes that point visible:

function trace(doc, pointer) {
  let cur = doc;
  const parts = pointer.split('/').slice(1);
  for (const [i, raw] of parts.entries()) {
    const tok = decode(raw);
    if (Array.isArray(cur)) {
      if (!/^(0|[1-9][0-9]*)$/.test(tok)) return { fail: i, tok, at: cur };
      cur = cur[Number(tok)];
    } else if (cur && typeof cur === 'object') {
      if (!(tok in cur)) return { fail: i, tok, at: Object.keys(cur) };
      cur = cur[tok];
    } else return { fail: i, tok, at: typeof cur };
  }
  return { value: cur };
}
trace({a:{b:1}}, '/a/c/d'); // { fail: 1, tok: 'c', at: ['b'] }

The report failed at token 1, 'c', available keys ['b'] is actionable in a way that undefined never is. When an API quotes a pointer you cannot resolve, this is the check that separates “the API is wrong” from “the document shape changed.”

Arrays, - and the Edge Cases Worth Knowing

Arrays carry two special cases. The token - is defined to mean “the element after the last current one” — a valid concept only when writing (as in JSON Patch add operations) and always an error when reading. Tools that accept - during evaluation are silently promising something the format does not deliver, and the mismatch appears as an undefined lookup instead of a clean failure.

// reading with '-' must fail:
trace(doc, '/list/-/id'); // expect: fail at token 1, '-' is write-only

The second case is dense numeric indices. /list/12 on an array of length 3 fails not because the token is malformed — it is a well-formed index — but because the value does not exist. Distinguishing “malformed token” from “missing value” in your error messages costs one regex and saves a support thread.

Object keys that look like array indices are legal and common: {"0": "zero"} is addressed by /0 as a property name, on an object, where the index rules never apply. The context rule from the previous section handles this automatically as long as evaluation always checks the container type before interpreting the token.

URI Fragments and JSON Strings Are Different Layers

JSON Pointers often travel inside URI fragments — the #/a/b form seen in JSON Schema and OpenAPI documents. That adds one more encoding layer, and conflating the layers produces a distinct bug family:

  • The URI layer percent-encodes characters illegal in a fragment, such as a raw % or space.
  • The pointer layer escapes / and ~ with the tilde forms.
  • The JSON layer, if the pointer travels inside a JSON string, may additionally escape the quote or backslash characters it contains.
const uri = 'https://example.test/schema#/properties/a~1b';
const pointer = decodeURIComponent(uri.split('#')[1]); // '/properties/a~1b'
const keys = pointer.split('/').slice(1).map(decode);  // ['properties','a/b']

Each layer decodes once, in the order the data was wrapped. Two percent-decode passes “to be safe” are the URI equivalent of the double-encoding bug, and they corrupt any pointer that legitimately contains a percent sign.

Reading Pointers in the Wild: JSON Patch and OpenAPI

Two specifications put pointers in front of developers daily, and both reward the same reading discipline. JSON Patch documents carry a path member on every operation; a patch fails mid-application when a path stops resolving, and the operations before the failure have already applied unless the consumer buffered them. Reading the failing pointer with the trace technique above turns “patch failed” into “the remove at token 3 referenced a key the previous patch step renamed.”

[
  {"op": "replace", "path": "/user/name", "value": "ada"},
  {"op": "remove", "path": "/user/name~1backup"}
]

OpenAPI documents use fragment pointers to reference schemas across files: $ref: "definitions.yaml#/components/schemas/User~1address". Here the pointer crosses a file boundary, so resolution order is: load the referenced document, percent-decode the fragment once, then evaluate the pointer. Two files referencing each other is where circular references and decode-order mistakes surface together, and the fix is almost always “decode once, at the layer that received the data.”

Neither specification needs a library to be read correctly — the escape rules are small enough to verify by eye, and the trace function above is shorter than most error messages it replaces. What both reward is refusing to treat the pointer as an opaque string: it is an address with a grammar, and the grammar is checkable in seconds.

Building a Pointer From Real Property Names

Writing a pointer is the reverse operation, and it has the same ordering rule: escape each token, then join with slashes. Property names come from the document, not from intuition, and a name containing a tilde needs its own escape even when it contains no slash.

const encode = s => s.replace(/~/g, '~0').replace(/\//g, '~1');
const pointer = ['', ...keys.map(encode)].join('/');
// keys ['properties','a~b'] → '/properties/a~0b'

Round-tripping is the acceptance test for any pointer helper: encode, split, decode, and confirm the keys survive character for character. The inspector on this site keeps the raw pointer visible next to the resolved path, so a mismatch between what you wrote and what the document contains is visible without a debugger. Everything runs locally in the browser — the pointer and the document never leave the machine.

Once the split-then-decode order is habit, the tilde pair stops looking like syntax noise and starts working as what it is: a two-symbol scheme that makes any property name addressable, including the ones with slashes in them.

Leave a Reply

Your email address will not be published. Required fields are marked *