How is the tilde escaping in the JSON Patch RFC supposed to operate?

Question

Referencing https://www.rfc-editor.org/rfc/rfc6902#appendix-A.14:

A.14. ~ Escape Ordering

An example target JSON document:

{
  "/": 9,
  "~1": 10
}

A JSON Patch document:

[
  {"op": "test", "path": "/~01", "value": 10}
]

The resulting JSON document:

{
  "/": 9,
  "~1": 10
}

I'm writing an implementation of this RFC, and I'm stuck on this. What is this trying to achieve, and how is it supposed to work?

Assuming the answer to the first part is "Allowing json key names containing /s to be referenced," how would you do that?

Answer 1

The ~ character is a keyword in JSON pointer. Hence, we need to "encode" it as ~0. To quote jsonpatch.com,

If you need to refer to a key with ~ or / in its name, you must escape the characters with ~0 and ~1 respectively. For example, to get "baz" from { "foo/bar~": "baz" } you’d use the pointer /foo~1bar~0

So essentially,

[
  {"op": "test", "path": "/~01", "value": 10}
]

when decoded yields

[
  {"op": "test", "path": "/~1", "value": 10}
]

Answer 2

~0 expands to ~ so /~01 expands to /~1

I guess they mean that you shouldn't "double expand" so that expanded /~1 should not be expanded again to // and thus must not match the documents "/" key (which would happen if you double expanded). Neither should you expand literals in the source document so the "~1" key is literally that and not equivalent to the expanded "/". But I repeat that's my guess about the intention of this example, the real intention may be different.

The example is indeed really bad, in particular since it's using a "test" operation and doesn't specify the result of that operation. Other examples like the next one at A.15 at least says its test operation must fail, A.14 doesn't tell you if the operation should succeed or not. I assume they meant the operation should succeed, so that implies /~01 should match the "~1" key. That's probably all about that example.

If I were to write an implementation I'd probably not worry too much about this example and just look at what other implementations do - to check if I'm compatible with them. It's also a good idea to look for test suites of other projects, for example I found one from http://jsonpatch.com/ at https://github.com/json-patch/json-patch-tests