2026-09-13 · 6 min read · Rahul Chitturi
- json
- json-pointer
- debugging
JSON Pointer identifies a location by joining reference tokens with slashes. A token containing a literal slash uses ~1, while a literal tilde uses ~0. Applying URL decoding, JSON string unescaping, and pointer decoding in the wrong order can select another value or make a valid path disappear.
The same pointer syntax appears in JSON Patch, OpenAPI references, schema diagnostics, and API error objects, but the surrounding transport may add another representation layer.
Write down every representation layer
Start with the intended object key, derive its pointer token, then place that pointer in JSON or a URI fragment only after the pointer is correct. Preserve each intermediate value in a harmless fixture so no decoder runs twice.
- Decode ~1 to slash and ~0 to tilde in the defined order.
- Treat an empty pointer as the complete document.
- Distinguish the empty key token in / from the root.
- Do not treat object keys that look numeric as array indexes.
Check arrays against the correct document version
Array indexes are positional. Earlier JSON Patch operations can move or remove elements, changing the meaning of a later pointer. Evaluate each operation against the document produced by its predecessor and handle the special append token only where the operation permits it.
Return bounded diagnostics that identify the failed operation and token without copying sensitive values into logs.
Reproduce with local fixtures
Use the JSON formatter for synthetic documents, URL tool for fragment encoding, diff for before-and-after trees, and case converter to expose accidental key normalization.
Test empty keys, slashes, tildes, percent signs, Unicode, numeric object keys, arrays, missing parents, escaped JSON strings, URI fragments, repeated decoding, and sequential patch operations.