2026-09-13 · 8 min read
- json
- json-pointer
- api-design
JSON Pointer is a compact syntax for identifying a value inside a JSON document. The empty string identifies the whole document; otherwise, each slash introduces one reference token.
A pointer can be embedded in JSON strings, URI fragments, schema references, patch operations, and diagnostics. Each container has its own escaping rules, so reliable implementations keep those layers separate.
Encode reference tokens before containers
Within a reference token, encode a literal tilde as ~0 and a literal slash as ~1. Decode those substitutions according to the standard so text such as ~01 does not become a slash through repeated processing.
- Treat property names as exact, case-sensitive strings.
- Distinguish an empty token from the empty pointer.
- Reject malformed escape sequences under a documented policy.
- Apply JSON and percent encoding only at their outer layers.
Define object and array traversal
For objects, a token names a property even when it consists only of digits. For arrays, implementations must validate the accepted index grammar, bounds, leading-zero policy, and operation-specific append token.
A pointer does not create missing parents. APIs that support creation, defaults, or tolerant lookup should describe those behaviors separately from pointer resolution.
Evaluate patch paths sequentially
JSON Patch applies operations in order, and each successful operation changes the document used by the next one. Array insertion, removal, move, and copy can therefore change later positions.
- Validate from and path independently.
- Make test failures stop the patch atomically when required.
- Protect authorization at the resolved business field, not the path text alone.
- Limit pointer depth and total patch work.
Maintain layered fixtures
Use Flashman's JSON formatter for synthetic documents, URL tool for fragment forms, diff for patch outcomes, case converter for naming checks, and hash for public fixture identity.
Test empty keys, slash and tilde keys, percent signs, Unicode, numeric object keys, arrays, missing parents, sequential edits, JSON string escaping, URI fragments, duplicate decoding, depth limits, and every producer-consumer pair.