TToolbox
/a/b

JSON Pointer Query

Resolve RFC 6901 paths against JSON

About this tool

JSON Pointer (IETF RFC 6901) is the standard syntax for identifying specific single values within a nested JSON document via forward-slash string paths (e.g., `/users/0/address/city`). While JSONPath handles complex wildcard queries, RFC 6901 is engineered for deterministic scalar targeting, serving as the foundational syntax for RFC 6902 JSON Patch operations and OpenAPI `$ref` schemas. This tool delivers client-side RFC 6901 pointer evaluation, escape sequence resolution, and payload extraction.

How to Use This Tool (Step-by-Step)

1

Paste Target JSON Document

Paste your complex JSON document, API response, or OpenAPI manifest into the target workspace.

2

Enter RFC 6901 Pointer Path

Type your slash-delimited pointer path (e.g., `/data/items/2/title`), employing `~1` for literal slashes and `~0` for tildes.

3

Evaluate Node & Copy Result

The resolved value or isolated JSON subtree renders instantaneously. Copy the output snippet with a single click.

RFC 6901 Escaping Compliance

Fully decodes RFC 6901 escape sequences: translates `~1` into literal `/` and `~0` into literal `~` tokens seamlessly.

OpenAPI $ref Fragment Support

Supports URI Fragment format (`#/components/schemas/User`), allowing API architects to inspect OpenAPI component references.

100% Client-Side Air-Gapped

Pointer tree traversals execute strictly inside local browser memory. Sensitive production configuration JSON is never logged.

JSON Pointer Gotchas & RFC 6901 Tips

  • •Pointers must start with a leading slash: Except for the empty string (representing root), all valid pointers MUST begin with `/`.
  • •Do not confuse JSON Pointer with JSONPath: JSONPath handles wildcards (`$..*`); JSON Pointer is deterministic and supports no query predicates.
  • •URI Fragment mode requires `#` prefix: When embedded in URLs or OpenAPI, use `#/path` and percent-encode non-ASCII characters per RFC 3986.
  • •Array indices must be canonical decimal: `01` is invalid under RFC 6901 (leading zeros are not permitted); write `1`. Some lenient parsers accept `01`, but strict implementations reject it.
  • •`-` only makes sense in Patch: `/items/-` addresses the fictional position past the end, used by RFC 6902 `add`. Reading through it always fails because no value exists there.
  • •Pointers are case-sensitive with no fuzzy matching: `/Components/Schemas/User` and `/components/schemas/User` are different paths. OpenAPI keys are conventionally lowercase.

Code & Transformation Examples

RFC 6901 JSON Pointer Resolution Benchmark

Sample JSON Document
{
  "name": "在线工具箱",
  "tools": [
    { "id": "json-format", "tags": ["dev", "fast"] },
    { "id": "base64", "tags": ["encode"] }
  ],
  "a/b": "特殊键名包含斜杠",
  "m~n": "特殊键名包含波浪号"
}
Pointer Path Evaluation
• 空字符串 ""          : 指向整个根 JSON 文档本身
• /name                : "在线工具箱"
• /tools/0/id          : "json-format" (数组索引从 0 开始)
• /tools/0/tags/1      : "fast" (提取数组中第二个子元素)
• /a~1b                : "特殊键名包含斜杠" (用 ~1 转义斜杠)
• /m~0n                : "特殊键名包含波浪号" (用 ~0 转义波浪号)

* The special `/-` token addresses the fictional index immediately following the last array element for append patches.

JavaScript RFC 6901 Implementation Snippet

JSON Pointer Resolver
function getByPointer(doc, pointer) {
  if (pointer === '') return doc;
  if (!pointer.startsWith('/')) throw new Error('指针必须以 / 开头');
  const tokens = pointer.slice(1).split('/').map(t => {
    // RFC 6901 解码: 先将 ~1 还原为 /,再将 ~0 还原为 ~
    return t.replace(/~1/g, '/').replace(/~0/g, '~');
  });
  return tokens.reduce((acc, k) => acc[k], doc);
}
Execution
const data = { user: { profile: { age: 28 } } };
console.log(getByPointer(data, "/user/profile/age")); // 28

* Always decode `~1` before `~0`; reversing the order produces catastrophic decoding bugs.

Following a $ref Chain in a Real OpenAPI Document

OpenAPI 3.0 Excerpt
{
  "paths": {
    "/users/{id}": {
      "get": {
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/User" }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "User": {
        "type": "object",
        "properties": {
          "id":    { "type": "integer" },
          "email": { "type": "string", "format": "email" },
          "tags":  { "type": "array", "items": { "type": "string" } }
        }
      }
    }
  }
}
Pointer Resolution
# 从 $ref 的值直接展开目标 schema(去掉开头的 #)
#/components/schemas/User
  → { "type": "object", "properties": { ... } }

# 继续下钻到具体字段的类型
#/components/schemas/User/properties/email/format
  → "email"

# 注意路径里 /users/{id} 这个键名本身含斜杠,必须转义
#/paths/~1users~1{id}/get/responses/200/content/application~1json/schema
  → { "$ref": "#/components/schemas/User" }

# 直接读到数组项的 schema
#/components/schemas/User/properties/tags/items/type
  → "string"

* Every `/` inside a key becomes `~1`. This is the most common trap in OpenAPI documents, since both path keys (`/users/{id}`) and media type keys (`application/json`) contain slashes.

Kubernetes and Cloud Config: Pointers for Writing, Not Just Reading

kubectl patch and JSON Patch Operations
# 用 JSON Patch 修改 Deployment 里容器镜像的 tag
kubectl patch deployment web --type='json' -p='[
  { "op": "replace",
    "path": "/spec/template/spec/containers/0/image",
    "value": "nginx:1.27-alpine" }
]'

# 追加一个环境变量(注意 /- 表示数组末尾之后)
kubectl patch deployment web --type='json' -p='[
  { "op": "add",
    "path": "/spec/template/spec/containers/0/env/-",
    "value": { "name": "LOG_LEVEL", "value": "debug" } }
]'
Path Semantics Decomposed
• /spec/template/spec/containers/0
    0 是数组下标,指向第一个容器(不是容器名)

• /image          → 该容器当前的镜像字符串

• /env/-          末尾追加语义,只有 RFC 6902 的 add 能用
                  换成读取会失败,因为那个位置不存在

• 若容器名含斜杠或特殊字符(少见但存在)
  仍需按 KEY 而非 NAME 定位,或改用 strategic merge patch

* Kubernetes strategic merge patch is a separate mechanism that does not follow RFC 6901. Only `--type='json'` uses standard JSON Patch, whose path rules match this article.

Frequently Asked Questions

Q: Why does RFC 6901 use ~1 and ~0 for escaping instead of backslashes?

A: Backslashes are reserved and unsafe in URL paths. Tildes (`~`) are unreserved URL characters under RFC 3986, minimizing double-escaping.

Q: What happens if a path points to a non-existent property?

A: Resolving against non-existent keys throws a resolution exception. The tool visually highlights the exact broken path segment.

Q: Do array indexes support negative numbers like -1?

A: No. RFC 6901 array indices must be non-negative integers (`0`, `1`). The `-` character specifically designates the fictitious index past the end.

Q: When should I use JSON Pointer versus JSONPath?

A: Ask whether you need one deterministic location or a set of matching locations. JSON Pointer addresses exactly one node and contains no wildcards or predicates, which makes it predictable and safe to persist — OpenAPI `$ref`, JSON Patch paths, and Kubernetes field paths all require it. JSONPath does the opposite: `$.store.book[*].author` returns every matching author, which suits querying and reporting, but it is not an IETF standard and implementations differ, so it is a poor choice for a stored reference. Rule of thumb: use Pointer for machine-readable references, Path for human-facing queries.

Q: Why does my pointer work in the browser but fail server-side?

A: The usual culprit is unescaping order: RFC 6901 requires decoding `~1` to `/` before `~0` to `~`. Reverse the order and the key `a~1b` is first treated as `a/b` and then split again, corrupting the path. The second cause is leading zeros — a lenient browser implementation may accept `/items/01` while strict implementations in Go or Rust reject it outright. The third is a leading `#`: that belongs to the URI Fragment form and is only meaningful in a URL context; pass it to a plain pointer parser and the `#` is treated as part of the path, so the lookup fails.

Q: Can a pointer address a null value, and can it distinguish null from a missing key?

A: It can address `null`, but the returned value alone cannot tell the two apart. Under RFC 6901, evaluating a non-existent path is an error, while evaluating a path whose value is `null` legitimately returns `null`. Many JavaScript implementations blur this by returning `null` or `undefined` for both, since the two are easy to conflate. To distinguish them in production, check key existence separately — with `Object.prototype.hasOwnProperty`, for instance — or use a resolver that throws on failure instead of returning `null`.

Q: What are the steps to write a correct pointer when a key contains `~` or `/`?

A: Encoding has exactly one direction and a fixed order: replace `~` with `~0` first, then `/` with `~1`. The order is not interchangeable. For example the key `a/b` encodes to `/a~1b`; the key `m~n` encodes to `/m~0n`; and the key `~/` encodes to `/m~0~1` — tilde first becomes `~0`, then the slash becomes `~1`, yielding `~0~1`. Note that a two-character key produces a four-character encoding. Decoding runs strictly in reverse: `~1` to `/` first, then `~0` to `~`.

Q: How do I use a pointer to reach a schema field inside an OpenAPI document?

A: An OpenAPI document is itself JSON, so pointer syntax is identical — only the entry point is `#/` rather than `/`. A concrete case: to reach the type of the `name` field under the `Pet` schema the pointer is `#/components/schemas/Pet/properties/name/type`. Finding every place that references `Pet` is not something a pointer can do, since that requires search rather than addressing; but the reverse move — following a `$ref` — is exactly what pointers are for. The `#/components/schemas/Pet` inside `$ref: '#/components/schemas/Pet'` is a pointer, and stripping the leading `#` lets you paste it straight into this tool to expand the target. OpenAPI 2.0 (Swagger) used `#/definitions/Pet` while 3.x uses `#/components/schemas/Pet`, a frequent source of breakage when migrating between versions.

Q: Do JSON Patch paths differ from ordinary pointers?

A: The path syntax is identical — both are RFC 6901 pointers — but RFC 6902 assigns extra meaning to `-`. Inside a JSON Patch, `/items/-` denotes the position just past the end of the array, so `{"op": "add", "path": "/items/-", "value": ...}` appends an element. Outside Patch operations `-` carries no meaning and reading through it always fails. One further difference from read-only use: Patch `remove` and `replace` target positions that must already exist, so a wrong path does not quietly skip — the whole patch operation fails and is rolled back.

Q: How can I verify where a long pointer actually lands?

A: Advance segment by segment, confirming each one, rather than pasting the whole string and inspecting only the final result. Consider `#/paths/~1users~1{id}/get/responses/200/content/application~1json/schema` — it reads like noise, but decomposes cleanly: `paths` is a top-level key; `~1users~1{id}` decodes back to `/users/{id}`, which is precisely the case where a key contains slashes and therefore needs escaping; `get`, `responses`, `200`, and `content` are plain keys; `application~1json` decodes to `application/json`; and `schema` is the target. This tool shows the node name and type at each level, and a wrong path halts visibly at the segment that broke, which localizes problems far better than staring at the final output.

Q: Does this tool upload my JSON to a server?

A: No. Pointer resolution runs entirely in browser memory with no network request and nothing written externally. That matters when debugging production API responses or configuration files containing credentials — you can paste a real `kubeconfig`, cloud provider credential JSON, or internal API payload without redacting it first.

Related Tools

All processing happens locally in your browser. Your data is never uploaded to a server.
/