Search code examples
jsonjson-patchjsonpointer

Purpose of tilde in JSON Pointer


The JSON Pointer spec states:

the characters '~' (%x7E) and '/' (%x2F) have special meanings in JSON Pointer

It is clear what '/' is used for, but I see no indication of what purpose the tilde serves (only mention that it needs to be escaped and how).


Solution

  • In JSON Pointer, you need to use ~1 to encode that you want to have / as part of the property name in the path. Because of that, ~ gets the special meaning as an indicator of the escape sequence an no longer expresses a real tilde. The real tilde is expressed as an escape sequence ~0.

    In other words (quote from JSON Pointer spec):

    Evaluation of each reference token begins by decoding any escaped character sequence. This is performed by first transforming any occurrence of the sequence '~1' to '/', and then transforming any occurrence of the sequence '~0' to '~'. By performing the substitutions in this order, an implementation avoids the error of turning '~01' first into '~1' and then into '/', which would be incorrect (the string '~01' correctly becomes '~1' after transformation).

    It might be interesting to take a look at JSON Patch tests here: https://github.com/json-patch/json-patch-tests/blob/master/spec_tests.json#L200 (search for ~)