odoc

doc/index.html

···
     "k\"l": 6,
     " ": 7,
     "m~n": 8
-  }|};;</x-ocaml></div><p>This document is carefully constructed to exercise various edge cases!</p><h3 id="the-root-pointer"><a href="#the-root-pointer" class="anchor"></a>The Root Pointer</h3><div class="x-ocaml-wrapper"><x-ocaml>get root rfc_example ;;</x-ocaml></div><p>The empty pointer (<code>root</code>) returns the whole document.</p><h3 id="object-member-access"><a href="#object-member-access" class="anchor"></a>Object Member Access</h3><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/foo") rfc_example ;;</x-ocaml></div><p><code>/foo</code> accesses the member named <code>foo</code>, which is an array.</p><h3 id="array-index-access"><a href="#array-index-access" class="anchor"></a>Array Index Access</h3><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/foo/0") rfc_example ;;
+  }|};;</x-ocaml></div><p>This document is carefully constructed to exercise various edge cases!</p><h3 id="the-root-pointer"><a href="#the-root-pointer" class="anchor"></a>The Root Pointer</h3><div class="x-ocaml-wrapper"><x-ocaml>get root rfc_example ;;</x-ocaml></div><p>The empty pointer (<code>Json_pointer.root</code>) returns the whole document.</p><h3 id="object-member-access"><a href="#object-member-access" class="anchor"></a>Object Member Access</h3><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/foo") rfc_example ;;</x-ocaml></div><p><code>/foo</code> accesses the member named <code>foo</code>, which is an array.</p><h3 id="array-index-access"><a href="#array-index-access" class="anchor"></a>Array Index Access</h3><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/foo/0") rfc_example ;;
 get (of_string_nav "/foo/1") rfc_example ;;</x-ocaml></div><p><code>/foo/0</code> first goes to <code>foo</code>, then accesses index 0 of the array.</p><h3 id="empty-string-as-key"><a href="#empty-string-as-key" class="anchor"></a>Empty String as Key</h3><p>JSON allows empty strings as object keys:</p><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/") rfc_example ;;</x-ocaml></div><p>The pointer <code>/</code> has one token: the empty string. This accesses the member with an empty name.</p><h3 id="keys-with-special-characters"><a href="#keys-with-special-characters" class="anchor"></a>Keys with Special Characters</h3><p>The RFC example includes keys with <code>/</code> and <code>~</code> characters:</p><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/a~1b") rfc_example ;;</x-ocaml></div><p>The token <code>a~1b</code> refers to the key <code>a/b</code>. We'll explain this escaping <a href="#escaping">below</a>.</p><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/m~0n") rfc_example ;;</x-ocaml></div><p>The token <code>m~0n</code> refers to the key <code>m~n</code>.</p><p><b>Important</b>: When using the OCaml library programmatically, you don't need to worry about escaping. The <code>Mem</code> variant holds the literal key name:</p><div class="x-ocaml-wrapper"><x-ocaml>let slash_ptr = make [mem "a/b"];;
 to_string slash_ptr;;
 get slash_ptr rfc_example ;;</x-ocaml></div><p>The library escapes it when converting to string.</p><h3 id="other-special-characters-(no-escaping-needed)"><a href="#other-special-characters-(no-escaping-needed)" class="anchor"></a>Other Special Characters (No Escaping Needed)</h3><p>Most characters don't need escaping in JSON Pointer strings:</p><div class="x-ocaml-wrapper"><x-ocaml>get (of_string_nav "/c%d") rfc_example ;;
···
 val find : nav t -&gt; Jsont.json -&gt; Jsont.json option</pre><h3 id="array-index-rules"><a href="#array-index-rules" class="anchor"></a>Array Index Rules</h3><p><a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a> has specific rules for array indices. <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-4">Section 4</a> states:</p><p><i>characters comprised of digits <code>...</code> that represent an unsigned base-10 integer value, making the new referenced value the array element with the zero-based index identified by the token</i></p><p>And importantly:</p><p><i>note that leading zeros are not allowed</i></p><div class="x-ocaml-wrapper"><x-ocaml>of_string_nav "/foo/0";;</x-ocaml></div><p>Zero itself is fine.</p><div class="x-ocaml-wrapper"><x-ocaml>of_string_nav "/foo/01";;</x-ocaml></div><p>But <code>01</code> has a leading zero, so it's NOT treated as an array index - it becomes a member name instead. This protects against accidental octal interpretation.</p><h2 id="the-end-of-array-marker:---and-type-safety"><a href="#the-end-of-array-marker:---and-type-safety" class="anchor"></a>The End-of-Array Marker: <code>-</code> and Type Safety</h2><p><a href="https://datatracker.ietf.org/doc/html/rfc6901#section-4">RFC 6901, Section 4</a> introduces a special token:</p><p><i>exactly the single character "-", making the new referenced value the (nonexistent) member after the last array element.</i></p><p>This <code>-</code> marker is unique to JSON Pointer (JSON Path has no equivalent). It's primarily useful for JSON Patch operations (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>) to append elements to arrays.</p><h3 id="navigation-vs-append-pointers"><a href="#navigation-vs-append-pointers" class="anchor"></a>Navigation vs Append Pointers</h3><p>The <code>json-pointer</code> library uses <b>phantom types</b> to encode the difference between pointers that can be used for navigation and pointers that target the "append position":</p><pre>type nav     (* A pointer to an existing element *)
 type append  (* A pointer ending with "-" (append position) *)
 type 'a t    (* Pointer with phantom type parameter *)
-type any     (* Existential: wraps either nav or append *)</pre><p>When you parse a pointer with <code>of_string</code>, you get an <code>any</code> pointer that can be used directly with mutation operations:</p><div class="x-ocaml-wrapper"><x-ocaml>of_string "/foo/0";;
-of_string "/foo/-";;</x-ocaml></div><p>The <code>-</code> creates an append pointer. The <code>any</code> type wraps either kind, making it ergonomic to use with operations like <code>set</code> and <code>add</code>.</p><h3 id="why-two-pointer-types?"><a href="#why-two-pointer-types?" class="anchor"></a>Why Two Pointer Types?</h3><p>The RFC explains that <code>-</code> refers to a <em>nonexistent</em> position:</p><p><i>Note that the use of the "-" character to index an array will always result in such an error condition because by definition it refers to a nonexistent array element.</i></p><p>So you <b>cannot use <code>get</code> or <code>find</code></b> with an append pointer - it makes no sense to retrieve a value from a position that doesn't exist! The library enforces this:</p><ul><li>Use <code>of_string_nav</code> when you need to call <code>get</code> or <code>find</code></li><li>Use <code>of_string</code> (returns <code>any</code>) for mutation operations</li></ul><p>Mutation operations like <code>add</code> accept <code>any</code> directly:</p><div class="x-ocaml-wrapper"><x-ocaml>let arr_obj = parse_json {|{"foo":["a","b"]}|};;
-add (of_string "/foo/-") arr_obj ~value:(Jsont.Json.string "c");;</x-ocaml></div><p>For retrieval operations, use <code>of_string_nav</code> which ensures the pointer doesn't contain <code>-</code>:</p><div class="x-ocaml-wrapper"><x-ocaml>of_string_nav "/foo/0";;
-of_string_nav "/foo/-";;</x-ocaml></div><h3 id="creating-append-pointers-programmatically"><a href="#creating-append-pointers-programmatically" class="anchor"></a>Creating Append Pointers Programmatically</h3><p>You can convert a navigation pointer to an append pointer using <code>at_end</code>:</p><div class="x-ocaml-wrapper"><x-ocaml>let nav_ptr = of_string_nav "/foo";;
+type any     (* Existential: wraps either nav or append *)</pre><p>When you parse a pointer with <code>Json_pointer.of_string</code>, you get an <code>Json_pointer.any</code> pointer that can be used directly with mutation operations:</p><div class="x-ocaml-wrapper"><x-ocaml>of_string "/foo/0";;
+of_string "/foo/-";;</x-ocaml></div><p>The <code>-</code> creates an append pointer. The <code>Json_pointer.any</code> type wraps either kind, making it ergonomic to use with operations like <code>Json_pointer.set</code> and <code>Json_pointer.add</code>.</p><h3 id="why-two-pointer-types?"><a href="#why-two-pointer-types?" class="anchor"></a>Why Two Pointer Types?</h3><p>The RFC explains that <code>-</code> refers to a <em>nonexistent</em> position:</p><p><i>Note that the use of the "-" character to index an array will always result in such an error condition because by definition it refers to a nonexistent array element.</i></p><p>So you <b>cannot use <code>get</code> or <code>find</code></b> with an append pointer - it makes no sense to retrieve a value from a position that doesn't exist! The library enforces this:</p><ul><li>Use <code>Json_pointer.of_string_nav</code> when you need to call <code>Json_pointer.get</code> or <code>Json_pointer.find</code></li><li>Use <code>Json_pointer.of_string</code> (returns <code>Json_pointer.any</code>) for mutation operations</li></ul><p>Mutation operations like <code>Json_pointer.add</code> accept <code>Json_pointer.any</code> directly:</p><div class="x-ocaml-wrapper"><x-ocaml>let arr_obj = parse_json {|{"foo":["a","b"]}|};;
+add (of_string "/foo/-") arr_obj ~value:(Jsont.Json.string "c");;</x-ocaml></div><p>For retrieval operations, use <code>Json_pointer.of_string_nav</code> which ensures the pointer doesn't contain <code>-</code>:</p><div class="x-ocaml-wrapper"><x-ocaml>of_string_nav "/foo/0";;
+of_string_nav "/foo/-";;</x-ocaml></div><h3 id="creating-append-pointers-programmatically"><a href="#creating-append-pointers-programmatically" class="anchor"></a>Creating Append Pointers Programmatically</h3><p>You can convert a navigation pointer to an append pointer using <code>Json_pointer.at_end</code>:</p><div class="x-ocaml-wrapper"><x-ocaml>let nav_ptr = of_string_nav "/foo";;
 let app_ptr = at_end nav_ptr;;
-to_string app_ptr;;</x-ocaml></div><h2 id="mutation-operations"><a href="#mutation-operations" class="anchor"></a>Mutation Operations</h2><p>While <a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a> defines JSON Pointer for read-only access, <a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a> (JSON Patch) uses JSON Pointer for modifications. The <code>json-pointer</code> library provides these operations.</p><h3 id="add"><a href="#add" class="anchor"></a>Add</h3><p>The <code>add</code> operation inserts a value at a location. It accepts <code>any</code> pointers, so you can use <code>of_string</code> directly:</p><div class="x-ocaml-wrapper"><x-ocaml>let obj = parse_json {|{"foo":"bar"}|};;
-add (of_string "/baz") obj ~value:(Jsont.Json.string "qux");;</x-ocaml></div><p>For arrays, <code>add</code> inserts BEFORE the specified index:</p><div class="x-ocaml-wrapper"><x-ocaml>let arr_obj = parse_json {|{"foo":["a","b"]}|};;
-add (of_string "/foo/1") arr_obj ~value:(Jsont.Json.string "X");;</x-ocaml></div><p>This is where the <code>-</code> marker shines - it appends to the end:</p><div class="x-ocaml-wrapper"><x-ocaml>add (of_string "/foo/-") arr_obj ~value:(Jsont.Json.string "c");;</x-ocaml></div><p>You can also use <code>at_end</code> to create an append pointer programmatically:</p><div class="x-ocaml-wrapper"><x-ocaml>add (any (at_end (of_string_nav "/foo"))) arr_obj ~value:(Jsont.Json.string "c");;</x-ocaml></div><h3 id="ergonomic-mutation-with-any"><a href="#ergonomic-mutation-with-any" class="anchor"></a>Ergonomic Mutation with <code>any</code></h3><p>Since <code>add</code>, <code>set</code>, <code>move</code>, and <code>copy</code> accept <code>any</code> pointers, you can use <code>of_string</code> directly without any pattern matching. This makes JSON Patch implementations straightforward:</p><div class="x-ocaml-wrapper"><x-ocaml>let items = parse_json {|{"items":["x"]}|};;
+to_string app_ptr;;</x-ocaml></div><h2 id="mutation-operations"><a href="#mutation-operations" class="anchor"></a>Mutation Operations</h2><p>While <a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a> defines JSON Pointer for read-only access, <a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a> (JSON Patch) uses JSON Pointer for modifications. The <code>json-pointer</code> library provides these operations.</p><h3 id="add"><a href="#add" class="anchor"></a>Add</h3><p>The <code>Json_pointer.add</code> operation inserts a value at a location. It accepts <code>Json_pointer.any</code> pointers, so you can use <code>Json_pointer.of_string</code> directly:</p><div class="x-ocaml-wrapper"><x-ocaml>let obj = parse_json {|{"foo":"bar"}|};;
+add (of_string "/baz") obj ~value:(Jsont.Json.string "qux");;</x-ocaml></div><p>For arrays, <code>Json_pointer.add</code> inserts BEFORE the specified index:</p><div class="x-ocaml-wrapper"><x-ocaml>let arr_obj = parse_json {|{"foo":["a","b"]}|};;
+add (of_string "/foo/1") arr_obj ~value:(Jsont.Json.string "X");;</x-ocaml></div><p>This is where the <code>-</code> marker shines - it appends to the end:</p><div class="x-ocaml-wrapper"><x-ocaml>add (of_string "/foo/-") arr_obj ~value:(Jsont.Json.string "c");;</x-ocaml></div><p>You can also use <code>Json_pointer.at_end</code> to create an append pointer programmatically:</p><div class="x-ocaml-wrapper"><x-ocaml>add (any (at_end (of_string_nav "/foo"))) arr_obj ~value:(Jsont.Json.string "c");;</x-ocaml></div><h3 id="ergonomic-mutation-with-any"><a href="#ergonomic-mutation-with-any" class="anchor"></a>Ergonomic Mutation with <code>any</code></h3><p>Since <code>Json_pointer.add</code>, <code>Json_pointer.set</code>, <code>Json_pointer.move</code>, and <code>Json_pointer.copy</code> accept <code>Json_pointer.any</code> pointers, you can use <code>Json_pointer.of_string</code> directly without any pattern matching. This makes JSON Patch implementations straightforward:</p><div class="x-ocaml-wrapper"><x-ocaml>let items = parse_json {|{"items":["x"]}|};;
 add (of_string "/items/0") items ~value:(Jsont.Json.string "y");;
-add (of_string "/items/-") items ~value:(Jsont.Json.string "z");;</x-ocaml></div><p>The same pointer works whether it targets an existing position or the append marker - no conditional logic needed.</p><h3 id="remove"><a href="#remove" class="anchor"></a>Remove</h3><p>The <code>remove</code> operation deletes a value. It only accepts <code>nav t</code> because you can only remove something that exists:</p><div class="x-ocaml-wrapper"><x-ocaml>let two_fields = parse_json {|{"foo":"bar","baz":"qux"}|};;
+add (of_string "/items/-") items ~value:(Jsont.Json.string "z");;</x-ocaml></div><p>The same pointer works whether it targets an existing position or the append marker - no conditional logic needed.</p><h3 id="remove"><a href="#remove" class="anchor"></a>Remove</h3><p>The <code>Json_pointer.remove</code> operation deletes a value. It only accepts <code>nav t</code> because you can only remove something that exists:</p><div class="x-ocaml-wrapper"><x-ocaml>let two_fields = parse_json {|{"foo":"bar","baz":"qux"}|};;
 remove (of_string_nav "/baz") two_fields ;;</x-ocaml></div><p>For arrays, it removes and shifts:</p><div class="x-ocaml-wrapper"><x-ocaml>let three_elem = parse_json {|{"foo":["a","b","c"]}|};;
-remove (of_string_nav "/foo/1") three_elem ;;</x-ocaml></div><h3 id="replace"><a href="#replace" class="anchor"></a>Replace</h3><p>The <code>replace</code> operation updates an existing value:</p><div class="x-ocaml-wrapper"><x-ocaml>replace (of_string_nav "/foo") obj ~value:(Jsont.Json.string "baz")
-  ;;</x-ocaml></div><p>Unlike <code>add</code>, <code>replace</code> requires the target to already exist (hence <code>nav t</code>). Attempting to replace a nonexistent path raises an error.</p><h3 id="move"><a href="#move" class="anchor"></a>Move</h3><p>The <code>move</code> operation relocates a value. The source (<code>from</code>) must be a <code>nav t</code> (you can only move something that exists), but the destination (<code>path</code>) accepts <code>any</code>:</p><div class="x-ocaml-wrapper"><x-ocaml>let nested = parse_json {|{"foo":{"bar":"baz"},"qux":{}}|};;
-move ~from:(of_string_nav "/foo/bar") ~path:(of_string "/qux/thud") nested;;</x-ocaml></div><h3 id="copy"><a href="#copy" class="anchor"></a>Copy</h3><p>The <code>copy</code> operation duplicates a value (same typing as <code>move</code>):</p><div class="x-ocaml-wrapper"><x-ocaml>let to_copy = parse_json {|{"foo":{"bar":"baz"}}|};;
-copy ~from:(of_string_nav "/foo/bar") ~path:(of_string "/foo/qux") to_copy;;</x-ocaml></div><h3 id="test"><a href="#test" class="anchor"></a>Test</h3><p>The <code>test</code> operation verifies a value (useful in JSON Patch):</p><div class="x-ocaml-wrapper"><x-ocaml>test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "bar");;
+remove (of_string_nav "/foo/1") three_elem ;;</x-ocaml></div><h3 id="replace"><a href="#replace" class="anchor"></a>Replace</h3><p>The <code>Json_pointer.replace</code> operation updates an existing value:</p><div class="x-ocaml-wrapper"><x-ocaml>replace (of_string_nav "/foo") obj ~value:(Jsont.Json.string "baz")
+  ;;</x-ocaml></div><p>Unlike <code>Json_pointer.add</code>, <code>Json_pointer.replace</code> requires the target to already exist (hence <code>nav t</code>). Attempting to replace a nonexistent path raises an error.</p><h3 id="move"><a href="#move" class="anchor"></a>Move</h3><p>The <code>Json_pointer.move</code> operation relocates a value. The source (<code>from</code>) must be a <code>nav t</code> (you can only move something that exists), but the destination (<code>path</code>) accepts <code>Json_pointer.any</code>:</p><div class="x-ocaml-wrapper"><x-ocaml>let nested = parse_json {|{"foo":{"bar":"baz"},"qux":{}}|};;
+move ~from:(of_string_nav "/foo/bar") ~path:(of_string "/qux/thud") nested;;</x-ocaml></div><h3 id="copy"><a href="#copy" class="anchor"></a>Copy</h3><p>The <code>Json_pointer.copy</code> operation duplicates a value (same typing as <code>Json_pointer.move</code>):</p><div class="x-ocaml-wrapper"><x-ocaml>let to_copy = parse_json {|{"foo":{"bar":"baz"}}|};;
+copy ~from:(of_string_nav "/foo/bar") ~path:(of_string "/foo/qux") to_copy;;</x-ocaml></div><h3 id="test"><a href="#test" class="anchor"></a>Test</h3><p>The <code>Json_pointer.test</code> operation verifies a value (useful in JSON Patch):</p><div class="x-ocaml-wrapper"><x-ocaml>test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "bar");;
 test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "wrong");;</x-ocaml></div><h2 id="escaping"><a href="#escaping" class="anchor"></a>Escaping Special Characters</h2><p><a href="https://datatracker.ietf.org/doc/html/rfc6901#section-3">RFC 6901, Section 3</a> explains the escaping rules:</p><p><i>Because the characters '~' (%x7E) and '/' (%x2F) have special meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be encoded as '~1' when these characters appear in a reference token.</i></p><p>Why these specific characters?</p><ul><li><code>/</code> separates tokens, so it must be escaped inside a token</li><li><code>~</code> is the escape character itself, so it must also be escaped</li></ul><p>The escape sequences are:</p><ul><li><code>~0</code> represents <code>~</code> (tilde)</li><li><code>~1</code> represents <code>/</code> (forward slash)</li></ul><h3 id="the-library-handles-escaping-automatically"><a href="#the-library-handles-escaping-automatically" class="anchor"></a>The Library Handles Escaping Automatically</h3><p><b>Important</b>: When using <code>json-pointer</code> programmatically, you rarely need to think about escaping. The <code>Mem</code> variant stores unescaped strings, and escaping happens automatically during serialization:</p><div class="x-ocaml-wrapper"><x-ocaml>let p = make [mem "a/b"];;
 to_string p;;
-of_string_nav "/a~1b";;</x-ocaml></div><h3 id="escaping-in-action"><a href="#escaping-in-action" class="anchor"></a>Escaping in Action</h3><p>The <code>Token</code> module exposes the escaping functions:</p><div class="x-ocaml-wrapper"><x-ocaml>Token.escape "hello";;
+of_string_nav "/a~1b";;</x-ocaml></div><h3 id="escaping-in-action"><a href="#escaping-in-action" class="anchor"></a>Escaping in Action</h3><p>The <code>Json_pointer.Token</code> module exposes the escaping functions:</p><div class="x-ocaml-wrapper"><x-ocaml>Token.escape "hello";;
 Token.escape "a/b";;
 Token.escape "a~b";;
 Token.escape "~/";;</x-ocaml></div><h3 id="unescaping"><a href="#unescaping" class="anchor"></a>Unescaping</h3><p>And the reverse process:</p><div class="x-ocaml-wrapper"><x-ocaml>Token.unescape "a~1b";;
···
 to_uri_fragment (of_string_nav "/a~1b");;
 to_uri_fragment (of_string_nav "/c%d");;
 to_uri_fragment (of_string_nav "/ ");;</x-ocaml></div><p>The <code>%</code> character must be percent-encoded as <code>%25</code> in URIs, and spaces become <code>%20</code>.</p><p>Here's the RFC example showing the URI fragment forms:</p><ul><li><code>""</code> -&gt; <code>#</code> -&gt; whole document</li><li><code>"/foo"</code> -&gt; <code>#/foo</code> -&gt; <code>["bar", "baz"]</code></li><li><code>"/foo/0"</code> -&gt; <code>#/foo/0</code> -&gt; <code>"bar"</code></li><li><code>"/"</code> -&gt; <code>#/</code> -&gt; <code>0</code></li><li><code>"/a~1b"</code> -&gt; <code>#/a~1b</code> -&gt; <code>1</code></li><li><code>"/c%d"</code> -&gt; <code>#/c%25d</code> -&gt; <code>2</code></li><li><code>"/ "</code> -&gt; <code>#/%20</code> -&gt; <code>7</code></li><li><code>"/m~0n"</code> -&gt; <code>#/m~0n</code> -&gt; <code>8</code></li></ul><h2 id="building-pointers-programmatically"><a href="#building-pointers-programmatically" class="anchor"></a>Building Pointers Programmatically</h2><p>Instead of parsing strings, you can build pointers from indices:</p><div class="x-ocaml-wrapper"><x-ocaml>let port_ptr = make [mem "database"; mem "port"];;
-to_string port_ptr;;</x-ocaml></div><p>For array access, use the <code>nth</code> helper:</p><div class="x-ocaml-wrapper"><x-ocaml>let first_feature_ptr = make [mem "features"; nth 0];;
-to_string first_feature_ptr;;</x-ocaml></div><h3 id="pointer-navigation"><a href="#pointer-navigation" class="anchor"></a>Pointer Navigation</h3><p>You can build pointers incrementally using the <code>/</code> operator (or <code>append_index</code>):</p><div class="x-ocaml-wrapper"><x-ocaml>let db_ptr = of_string_nav "/database";;
+to_string port_ptr;;</x-ocaml></div><p>For array access, use the <code>Json_pointer.nth</code> helper:</p><div class="x-ocaml-wrapper"><x-ocaml>let first_feature_ptr = make [mem "features"; nth 0];;
+to_string first_feature_ptr;;</x-ocaml></div><h3 id="pointer-navigation"><a href="#pointer-navigation" class="anchor"></a>Pointer Navigation</h3><p>You can build pointers incrementally using the <code>/</code> operator (or <code>Json_pointer.append_index</code>):</p><div class="x-ocaml-wrapper"><x-ocaml>let db_ptr = of_string_nav "/database";;
 let creds_ptr = db_ptr / mem "credentials";;
 let user_ptr = creds_ptr / mem "username";;
 to_string user_ptr;;</x-ocaml></div><p>Or concatenate two pointers:</p><div class="x-ocaml-wrapper"><x-ocaml>let base = of_string_nav "/api/v1";;
···
       "credentials": {"username": "admin", "password": "secret"}
     },
     "features": ["auth", "logging", "metrics"]
-  }|};;</x-ocaml></div><h3 id="typed-access-with-path"><a href="#typed-access-with-path" class="anchor"></a>Typed Access with <code>path</code></h3><p>The <code>path</code> combinator combines pointer navigation with typed decoding:</p><div class="x-ocaml-wrapper"><x-ocaml>let nav = of_string_nav "/database/host";;
+  }|};;</x-ocaml></div><h3 id="typed-access-with-path"><a href="#typed-access-with-path" class="anchor"></a>Typed Access with <code>path</code></h3><p>The <code>Json_pointer.path</code> combinator combines pointer navigation with typed decoding:</p><div class="x-ocaml-wrapper"><x-ocaml>let nav = of_string_nav "/database/host";;
 let db_host =
     Jsont.Json.decode
       (path nav Jsont.string)
···
     Jsont.Json.decode
       (path (of_string_nav "/database/port") Jsont.int)
       config_json
-    |&gt; Result.get_ok;;</x-ocaml></div><p>The typed approach catches mismatches at decode time with clear errors.</p><h3 id="updates-with-polymorphic-pointers"><a href="#updates-with-polymorphic-pointers" class="anchor"></a>Updates with Polymorphic Pointers</h3><p>The <code>set</code> and <code>add</code> functions accept <code>any</code> pointers, which means you can use the result of <code>of_string</code> directly without pattern matching:</p><div class="x-ocaml-wrapper"><x-ocaml>let tasks = parse_json {|{"tasks":["buy milk"]}|};;
+    |&gt; Result.get_ok;;</x-ocaml></div><p>The typed approach catches mismatches at decode time with clear errors.</p><h3 id="updates-with-polymorphic-pointers"><a href="#updates-with-polymorphic-pointers" class="anchor"></a>Updates with Polymorphic Pointers</h3><p>The <code>Json_pointer.set</code> and <code>Json_pointer.add</code> functions accept <code>Json_pointer.any</code> pointers, which means you can use the result of <code>Json_pointer.of_string</code> directly without pattern matching:</p><div class="x-ocaml-wrapper"><x-ocaml>let tasks = parse_json {|{"tasks":["buy milk"]}|};;
 set (of_string "/tasks/0") tasks ~value:(Jsont.Json.string "buy eggs");;
-set (of_string "/tasks/-") tasks ~value:(Jsont.Json.string "call mom");;</x-ocaml></div><p>This is useful for implementing JSON Patch (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>) where operations like <code>"add"</code> can target either existing positions or the append marker. If you need to distinguish between pointer types at runtime, use <code>of_string_kind</code> which returns a polymorphic variant:</p><div class="x-ocaml-wrapper"><x-ocaml>of_string_kind "/tasks/0";;
+set (of_string "/tasks/-") tasks ~value:(Jsont.Json.string "call mom");;</x-ocaml></div><p>This is useful for implementing JSON Patch (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>) where operations like <code>"add"</code> can target either existing positions or the append marker. If you need to distinguish between pointer types at runtime, use <code>Json_pointer.of_string_kind</code> which returns a polymorphic variant:</p><div class="x-ocaml-wrapper"><x-ocaml>of_string_kind "/tasks/0";;
 of_string_kind "/tasks/-";;</x-ocaml></div><h2 id="summary"><a href="#summary" class="anchor"></a>Summary</h2><p>JSON Pointer (<a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a>) provides a simple but powerful way to address values within JSON documents:</p><ol><li><b>Syntax</b>: Pointers are strings of <code>/</code>-separated reference tokens</li><li><b>Escaping</b>: Use <code>~0</code> for <code>~</code> and <code>~1</code> for <code>/</code> in tokens (handled automatically by the library)</li><li><b>Evaluation</b>: Tokens navigate through objects (by key) and arrays (by index)</li><li><b>URI Encoding</b>: Pointers can be percent-encoded for use in URIs</li><li><b>Mutations</b>: Combined with JSON Patch (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>), pointers enable structured updates</li><li><b>Type Safety</b>: Phantom types (<code>nav t</code> vs <code>append t</code>) prevent misuse of append pointers with retrieval operations, while the <code>any</code> existential type allows ergonomic use with mutation operations</li></ol><p>The <code>json-pointer</code> library implements all of this with type-safe OCaml interfaces, integration with the <code>jsont</code> codec system, and proper error handling for malformed pointers and missing values.</p><h3 id="key-points-on-json-pointer-vs-json-path"><a href="#key-points-on-json-pointer-vs-json-path" class="anchor"></a>Key Points on JSON Pointer vs JSON Path</h3><ul><li><b>JSON Pointer</b> addresses a <em>single</em> location (like a file path)</li><li><b>JSON Path</b> queries for <em>multiple</em> values (like a search)</li><li>The <code>-</code> token is unique to JSON Pointer - it means "append position" for arrays</li><li>The library uses phantom types to enforce that <code>-</code> (append) pointers cannot be used with <code>get</code>/<code>find</code></li></ul></div>
 </body></html>

doc/tutorial.html

···
 val rfc_example : Jsont.json =
   {&quot;foo&quot;:[&quot;bar&quot;,&quot;baz&quot;],&quot;&quot;:0,&quot;a/b&quot;:1,&quot;c%d&quot;:2,&quot;e^f&quot;:3,&quot;g|h&quot;:4,&quot;i\\j&quot;:5,&quot;k\&quot;l&quot;:6,&quot; &quot;:7,&quot;m~n&quot;:8}</code></pre><p>This document is carefully constructed to exercise various edge cases!</p><h3 id="the-root-pointer"><a href="#the-root-pointer" class="anchor"></a>The Root Pointer</h3><pre class="language-ocaml"><code># get root rfc_example ;;
 - : Jsont.json =
-{&quot;foo&quot;:[&quot;bar&quot;,&quot;baz&quot;],&quot;&quot;:0,&quot;a/b&quot;:1,&quot;c%d&quot;:2,&quot;e^f&quot;:3,&quot;g|h&quot;:4,&quot;i\\j&quot;:5,&quot;k\&quot;l&quot;:6,&quot; &quot;:7,&quot;m~n&quot;:8}</code></pre><p>The empty pointer (<code>root</code>) returns the whole document.</p><h3 id="object-member-access"><a href="#object-member-access" class="anchor"></a>Object Member Access</h3><pre class="language-ocaml"><code># get (of_string_nav &quot;/foo&quot;) rfc_example ;;
+{&quot;foo&quot;:[&quot;bar&quot;,&quot;baz&quot;],&quot;&quot;:0,&quot;a/b&quot;:1,&quot;c%d&quot;:2,&quot;e^f&quot;:3,&quot;g|h&quot;:4,&quot;i\\j&quot;:5,&quot;k\&quot;l&quot;:6,&quot; &quot;:7,&quot;m~n&quot;:8}</code></pre><p>The empty pointer (<code>Json_pointer.root</code>) returns the whole document.</p><h3 id="object-member-access"><a href="#object-member-access" class="anchor"></a>Object Member Access</h3><pre class="language-ocaml"><code># get (of_string_nav &quot;/foo&quot;) rfc_example ;;
 - : Jsont.json = [&quot;bar&quot;,&quot;baz&quot;]</code></pre><p><code>/foo</code> accesses the member named <code>foo</code>, which is an array.</p><h3 id="array-index-access"><a href="#array-index-access" class="anchor"></a>Array Index Access</h3><pre class="language-ocaml"><code># get (of_string_nav &quot;/foo/0&quot;) rfc_example ;;
 - : Jsont.json = &quot;bar&quot;
 # get (of_string_nav &quot;/foo/1&quot;) rfc_example ;;
···
 - : nav t = [Mem &quot;foo&quot;; Mem &quot;01&quot;]</code></pre><p>But <code>01</code> has a leading zero, so it's NOT treated as an array index - it becomes a member name instead. This protects against accidental octal interpretation.</p><h2 id="the-end-of-array-marker:---and-type-safety"><a href="#the-end-of-array-marker:---and-type-safety" class="anchor"></a>The End-of-Array Marker: <code>-</code> and Type Safety</h2><p><a href="https://datatracker.ietf.org/doc/html/rfc6901#section-4">RFC 6901, Section 4</a> introduces a special token:</p><p><i>exactly the single character &quot;-&quot;, making the new referenced value the (nonexistent) member after the last array element.</i></p><p>This <code>-</code> marker is unique to JSON Pointer (JSON Path has no equivalent). It's primarily useful for JSON Patch operations (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>) to append elements to arrays.</p><h3 id="navigation-vs-append-pointers"><a href="#navigation-vs-append-pointers" class="anchor"></a>Navigation vs Append Pointers</h3><p>The <code>json-pointer</code> library uses <b>phantom types</b> to encode the difference between pointers that can be used for navigation and pointers that target the &quot;append position&quot;:</p><pre>type nav     (* A pointer to an existing element *)
 type append  (* A pointer ending with &quot;-&quot; (append position) *)
 type 'a t    (* Pointer with phantom type parameter *)
-type any     (* Existential: wraps either nav or append *)</pre><p>When you parse a pointer with <code>of_string</code>, you get an <code>any</code> pointer that can be used directly with mutation operations:</p><pre class="language-ocaml"><code># of_string &quot;/foo/0&quot;;;
+type any     (* Existential: wraps either nav or append *)</pre><p>When you parse a pointer with <code>Json_pointer.of_string</code>, you get an <code>Json_pointer.any</code> pointer that can be used directly with mutation operations:</p><pre class="language-ocaml"><code># of_string &quot;/foo/0&quot;;;
 - : any = Any &lt;abstr&gt;
 # of_string &quot;/foo/-&quot;;;
-- : any = Any &lt;abstr&gt;</code></pre><p>The <code>-</code> creates an append pointer. The <code>any</code> type wraps either kind, making it ergonomic to use with operations like <code>set</code> and <code>add</code>.</p><h3 id="why-two-pointer-types?"><a href="#why-two-pointer-types?" class="anchor"></a>Why Two Pointer Types?</h3><p>The RFC explains that <code>-</code> refers to a <em>nonexistent</em> position:</p><p><i>Note that the use of the &quot;-&quot; character to index an array will always result in such an error condition because by definition it refers to a nonexistent array element.</i></p><p>So you <b>cannot use <code>get</code> or <code>find</code></b> with an append pointer - it makes no sense to retrieve a value from a position that doesn't exist! The library enforces this:</p><ul><li>Use <code>of_string_nav</code> when you need to call <code>get</code> or <code>find</code></li><li>Use <code>of_string</code> (returns <code>any</code>) for mutation operations</li></ul><p>Mutation operations like <code>add</code> accept <code>any</code> directly:</p><pre class="language-ocaml"><code># let arr_obj = parse_json {|{&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;]}|};;
+- : any = Any &lt;abstr&gt;</code></pre><p>The <code>-</code> creates an append pointer. The <code>Json_pointer.any</code> type wraps either kind, making it ergonomic to use with operations like <code>Json_pointer.set</code> and <code>Json_pointer.add</code>.</p><h3 id="why-two-pointer-types?"><a href="#why-two-pointer-types?" class="anchor"></a>Why Two Pointer Types?</h3><p>The RFC explains that <code>-</code> refers to a <em>nonexistent</em> position:</p><p><i>Note that the use of the &quot;-&quot; character to index an array will always result in such an error condition because by definition it refers to a nonexistent array element.</i></p><p>So you <b>cannot use <code>get</code> or <code>find</code></b> with an append pointer - it makes no sense to retrieve a value from a position that doesn't exist! The library enforces this:</p><ul><li>Use <code>Json_pointer.of_string_nav</code> when you need to call <code>Json_pointer.get</code> or <code>Json_pointer.find</code></li><li>Use <code>Json_pointer.of_string</code> (returns <code>Json_pointer.any</code>) for mutation operations</li></ul><p>Mutation operations like <code>Json_pointer.add</code> accept <code>Json_pointer.any</code> directly:</p><pre class="language-ocaml"><code># let arr_obj = parse_json {|{&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;]}|};;
 val arr_obj : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;]}
 # add (of_string &quot;/foo/-&quot;) arr_obj ~value:(Jsont.Json.string &quot;c&quot;);;
-- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}</code></pre><p>For retrieval operations, use <code>of_string_nav</code> which ensures the pointer doesn't contain <code>-</code>:</p><pre class="language-ocaml"><code># of_string_nav &quot;/foo/0&quot;;;
+- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}</code></pre><p>For retrieval operations, use <code>Json_pointer.of_string_nav</code> which ensures the pointer doesn't contain <code>-</code>:</p><pre class="language-ocaml"><code># of_string_nav &quot;/foo/0&quot;;;
 - : nav t = [Mem &quot;foo&quot;; Nth 0]
 # of_string_nav &quot;/foo/-&quot;;;
 Exception:
-Jsont.Error Invalid JSON Pointer: '-' not allowed in navigation pointer.</code></pre><h3 id="creating-append-pointers-programmatically"><a href="#creating-append-pointers-programmatically" class="anchor"></a>Creating Append Pointers Programmatically</h3><p>You can convert a navigation pointer to an append pointer using <code>at_end</code>:</p><pre class="language-ocaml"><code># let nav_ptr = of_string_nav &quot;/foo&quot;;;
+Jsont.Error Invalid JSON Pointer: '-' not allowed in navigation pointer.</code></pre><h3 id="creating-append-pointers-programmatically"><a href="#creating-append-pointers-programmatically" class="anchor"></a>Creating Append Pointers Programmatically</h3><p>You can convert a navigation pointer to an append pointer using <code>Json_pointer.at_end</code>:</p><pre class="language-ocaml"><code># let nav_ptr = of_string_nav &quot;/foo&quot;;;
 val nav_ptr : nav t = [Mem &quot;foo&quot;]
 # let app_ptr = at_end nav_ptr;;
 val app_ptr : append t = [Mem &quot;foo&quot;] /-
 # to_string app_ptr;;
-- : string = &quot;/foo/-&quot;</code></pre><h2 id="mutation-operations"><a href="#mutation-operations" class="anchor"></a>Mutation Operations</h2><p>While <a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a> defines JSON Pointer for read-only access, <a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a> (JSON Patch) uses JSON Pointer for modifications. The <code>json-pointer</code> library provides these operations.</p><h3 id="add"><a href="#add" class="anchor"></a>Add</h3><p>The <code>add</code> operation inserts a value at a location. It accepts <code>any</code> pointers, so you can use <code>of_string</code> directly:</p><pre class="language-ocaml"><code># let obj = parse_json {|{&quot;foo&quot;:&quot;bar&quot;}|};;
+- : string = &quot;/foo/-&quot;</code></pre><h2 id="mutation-operations"><a href="#mutation-operations" class="anchor"></a>Mutation Operations</h2><p>While <a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a> defines JSON Pointer for read-only access, <a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a> (JSON Patch) uses JSON Pointer for modifications. The <code>json-pointer</code> library provides these operations.</p><h3 id="add"><a href="#add" class="anchor"></a>Add</h3><p>The <code>Json_pointer.add</code> operation inserts a value at a location. It accepts <code>Json_pointer.any</code> pointers, so you can use <code>Json_pointer.of_string</code> directly:</p><pre class="language-ocaml"><code># let obj = parse_json {|{&quot;foo&quot;:&quot;bar&quot;}|};;
 val obj : Jsont.json = {&quot;foo&quot;:&quot;bar&quot;}
 # add (of_string &quot;/baz&quot;) obj ~value:(Jsont.Json.string &quot;qux&quot;);;
-- : Jsont.json = {&quot;foo&quot;:&quot;bar&quot;,&quot;baz&quot;:&quot;qux&quot;}</code></pre><p>For arrays, <code>add</code> inserts BEFORE the specified index:</p><pre class="language-ocaml"><code># let arr_obj = parse_json {|{&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;]}|};;
+- : Jsont.json = {&quot;foo&quot;:&quot;bar&quot;,&quot;baz&quot;:&quot;qux&quot;}</code></pre><p>For arrays, <code>Json_pointer.add</code> inserts BEFORE the specified index:</p><pre class="language-ocaml"><code># let arr_obj = parse_json {|{&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;]}|};;
 val arr_obj : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;]}
 # add (of_string &quot;/foo/1&quot;) arr_obj ~value:(Jsont.Json.string &quot;X&quot;);;
 - : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;X&quot;,&quot;b&quot;]}</code></pre><p>This is where the <code>-</code> marker shines - it appends to the end:</p><pre class="language-ocaml"><code># add (of_string &quot;/foo/-&quot;) arr_obj ~value:(Jsont.Json.string &quot;c&quot;);;
-- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}</code></pre><p>You can also use <code>at_end</code> to create an append pointer programmatically:</p><pre class="language-ocaml"><code># add (any (at_end (of_string_nav &quot;/foo&quot;))) arr_obj ~value:(Jsont.Json.string &quot;c&quot;);;
-- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}</code></pre><h3 id="ergonomic-mutation-with-any"><a href="#ergonomic-mutation-with-any" class="anchor"></a>Ergonomic Mutation with <code>any</code></h3><p>Since <code>add</code>, <code>set</code>, <code>move</code>, and <code>copy</code> accept <code>any</code> pointers, you can use <code>of_string</code> directly without any pattern matching. This makes JSON Patch implementations straightforward:</p><pre class="language-ocaml"><code># let items = parse_json {|{&quot;items&quot;:[&quot;x&quot;]}|};;
+- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}</code></pre><p>You can also use <code>Json_pointer.at_end</code> to create an append pointer programmatically:</p><pre class="language-ocaml"><code># add (any (at_end (of_string_nav &quot;/foo&quot;))) arr_obj ~value:(Jsont.Json.string &quot;c&quot;);;
+- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}</code></pre><h3 id="ergonomic-mutation-with-any"><a href="#ergonomic-mutation-with-any" class="anchor"></a>Ergonomic Mutation with <code>any</code></h3><p>Since <code>Json_pointer.add</code>, <code>Json_pointer.set</code>, <code>Json_pointer.move</code>, and <code>Json_pointer.copy</code> accept <code>Json_pointer.any</code> pointers, you can use <code>Json_pointer.of_string</code> directly without any pattern matching. This makes JSON Patch implementations straightforward:</p><pre class="language-ocaml"><code># let items = parse_json {|{&quot;items&quot;:[&quot;x&quot;]}|};;
 val items : Jsont.json = {&quot;items&quot;:[&quot;x&quot;]}
 # add (of_string &quot;/items/0&quot;) items ~value:(Jsont.Json.string &quot;y&quot;);;
 - : Jsont.json = {&quot;items&quot;:[&quot;y&quot;,&quot;x&quot;]}
 # add (of_string &quot;/items/-&quot;) items ~value:(Jsont.Json.string &quot;z&quot;);;
-- : Jsont.json = {&quot;items&quot;:[&quot;x&quot;,&quot;z&quot;]}</code></pre><p>The same pointer works whether it targets an existing position or the append marker - no conditional logic needed.</p><h3 id="remove"><a href="#remove" class="anchor"></a>Remove</h3><p>The <code>remove</code> operation deletes a value. It only accepts <code>nav t</code> because you can only remove something that exists:</p><pre class="language-ocaml"><code># let two_fields = parse_json {|{&quot;foo&quot;:&quot;bar&quot;,&quot;baz&quot;:&quot;qux&quot;}|};;
+- : Jsont.json = {&quot;items&quot;:[&quot;x&quot;,&quot;z&quot;]}</code></pre><p>The same pointer works whether it targets an existing position or the append marker - no conditional logic needed.</p><h3 id="remove"><a href="#remove" class="anchor"></a>Remove</h3><p>The <code>Json_pointer.remove</code> operation deletes a value. It only accepts <code>nav t</code> because you can only remove something that exists:</p><pre class="language-ocaml"><code># let two_fields = parse_json {|{&quot;foo&quot;:&quot;bar&quot;,&quot;baz&quot;:&quot;qux&quot;}|};;
 val two_fields : Jsont.json = {&quot;foo&quot;:&quot;bar&quot;,&quot;baz&quot;:&quot;qux&quot;}
 # remove (of_string_nav &quot;/baz&quot;) two_fields ;;
 - : Jsont.json = {&quot;foo&quot;:&quot;bar&quot;}</code></pre><p>For arrays, it removes and shifts:</p><pre class="language-ocaml"><code># let three_elem = parse_json {|{&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}|};;
 val three_elem : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;b&quot;,&quot;c&quot;]}
 # remove (of_string_nav &quot;/foo/1&quot;) three_elem ;;
-- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;c&quot;]}</code></pre><h3 id="replace"><a href="#replace" class="anchor"></a>Replace</h3><p>The <code>replace</code> operation updates an existing value:</p><pre class="language-ocaml"><code># replace (of_string_nav &quot;/foo&quot;) obj ~value:(Jsont.Json.string &quot;baz&quot;)
+- : Jsont.json = {&quot;foo&quot;:[&quot;a&quot;,&quot;c&quot;]}</code></pre><h3 id="replace"><a href="#replace" class="anchor"></a>Replace</h3><p>The <code>Json_pointer.replace</code> operation updates an existing value:</p><pre class="language-ocaml"><code># replace (of_string_nav &quot;/foo&quot;) obj ~value:(Jsont.Json.string &quot;baz&quot;)
   ;;
-- : Jsont.json = {&quot;foo&quot;:&quot;baz&quot;}</code></pre><p>Unlike <code>add</code>, <code>replace</code> requires the target to already exist (hence <code>nav t</code>). Attempting to replace a nonexistent path raises an error.</p><h3 id="move"><a href="#move" class="anchor"></a>Move</h3><p>The <code>move</code> operation relocates a value. The source (<code>from</code>) must be a <code>nav t</code> (you can only move something that exists), but the destination (<code>path</code>) accepts <code>any</code>:</p><pre class="language-ocaml"><code># let nested = parse_json {|{&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;},&quot;qux&quot;:{}}|};;
+- : Jsont.json = {&quot;foo&quot;:&quot;baz&quot;}</code></pre><p>Unlike <code>Json_pointer.add</code>, <code>Json_pointer.replace</code> requires the target to already exist (hence <code>nav t</code>). Attempting to replace a nonexistent path raises an error.</p><h3 id="move"><a href="#move" class="anchor"></a>Move</h3><p>The <code>Json_pointer.move</code> operation relocates a value. The source (<code>from</code>) must be a <code>nav t</code> (you can only move something that exists), but the destination (<code>path</code>) accepts <code>Json_pointer.any</code>:</p><pre class="language-ocaml"><code># let nested = parse_json {|{&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;},&quot;qux&quot;:{}}|};;
 val nested : Jsont.json = {&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;},&quot;qux&quot;:{}}
 # move ~from:(of_string_nav &quot;/foo/bar&quot;) ~path:(of_string &quot;/qux/thud&quot;) nested;;
-- : Jsont.json = {&quot;foo&quot;:{},&quot;qux&quot;:{&quot;thud&quot;:&quot;baz&quot;}}</code></pre><h3 id="copy"><a href="#copy" class="anchor"></a>Copy</h3><p>The <code>copy</code> operation duplicates a value (same typing as <code>move</code>):</p><pre class="language-ocaml"><code># let to_copy = parse_json {|{&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;}}|};;
+- : Jsont.json = {&quot;foo&quot;:{},&quot;qux&quot;:{&quot;thud&quot;:&quot;baz&quot;}}</code></pre><h3 id="copy"><a href="#copy" class="anchor"></a>Copy</h3><p>The <code>Json_pointer.copy</code> operation duplicates a value (same typing as <code>Json_pointer.move</code>):</p><pre class="language-ocaml"><code># let to_copy = parse_json {|{&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;}}|};;
 val to_copy : Jsont.json = {&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;}}
 # copy ~from:(of_string_nav &quot;/foo/bar&quot;) ~path:(of_string &quot;/foo/qux&quot;) to_copy;;
-- : Jsont.json = {&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;,&quot;qux&quot;:&quot;baz&quot;}}</code></pre><h3 id="test"><a href="#test" class="anchor"></a>Test</h3><p>The <code>test</code> operation verifies a value (useful in JSON Patch):</p><pre class="language-ocaml"><code># test (of_string_nav &quot;/foo&quot;) obj ~expected:(Jsont.Json.string &quot;bar&quot;);;
+- : Jsont.json = {&quot;foo&quot;:{&quot;bar&quot;:&quot;baz&quot;,&quot;qux&quot;:&quot;baz&quot;}}</code></pre><h3 id="test"><a href="#test" class="anchor"></a>Test</h3><p>The <code>Json_pointer.test</code> operation verifies a value (useful in JSON Patch):</p><pre class="language-ocaml"><code># test (of_string_nav &quot;/foo&quot;) obj ~expected:(Jsont.Json.string &quot;bar&quot;);;
 - : bool = true
 # test (of_string_nav &quot;/foo&quot;) obj ~expected:(Jsont.Json.string &quot;wrong&quot;);;
 - : bool = false</code></pre><h2 id="escaping"><a href="#escaping" class="anchor"></a>Escaping Special Characters</h2><p><a href="https://datatracker.ietf.org/doc/html/rfc6901#section-3">RFC 6901, Section 3</a> explains the escaping rules:</p><p><i>Because the characters '~' (%x7E) and '/' (%x2F) have special meanings in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be encoded as '~1' when these characters appear in a reference token.</i></p><p>Why these specific characters?</p><ul><li><code>/</code> separates tokens, so it must be escaped inside a token</li><li><code>~</code> is the escape character itself, so it must also be escaped</li></ul><p>The escape sequences are:</p><ul><li><code>~0</code> represents <code>~</code> (tilde)</li><li><code>~1</code> represents <code>/</code> (forward slash)</li></ul><h3 id="the-library-handles-escaping-automatically"><a href="#the-library-handles-escaping-automatically" class="anchor"></a>The Library Handles Escaping Automatically</h3><p><b>Important</b>: When using <code>json-pointer</code> programmatically, you rarely need to think about escaping. The <code>Mem</code> variant stores unescaped strings, and escaping happens automatically during serialization:</p><pre class="language-ocaml"><code># let p = make [mem &quot;a/b&quot;];;
···
 # to_string p;;
 - : string = &quot;/a~1b&quot;
 # of_string_nav &quot;/a~1b&quot;;;
-- : nav t = [Mem &quot;a/b&quot;]</code></pre><h3 id="escaping-in-action"><a href="#escaping-in-action" class="anchor"></a>Escaping in Action</h3><p>The <code>Token</code> module exposes the escaping functions:</p><pre class="language-ocaml"><code># Token.escape &quot;hello&quot;;;
+- : nav t = [Mem &quot;a/b&quot;]</code></pre><h3 id="escaping-in-action"><a href="#escaping-in-action" class="anchor"></a>Escaping in Action</h3><p>The <code>Json_pointer.Token</code> module exposes the escaping functions:</p><pre class="language-ocaml"><code># Token.escape &quot;hello&quot;;;
 - : string = &quot;hello&quot;
 # Token.escape &quot;a/b&quot;;;
 - : string = &quot;a~1b&quot;
···
 - : string = &quot;/%20&quot;</code></pre><p>The <code>%</code> character must be percent-encoded as <code>%25</code> in URIs, and spaces become <code>%20</code>.</p><p>Here's the RFC example showing the URI fragment forms:</p><ul><li><code>&quot;&quot;</code> -&gt; <code>#</code> -&gt; whole document</li><li><code>&quot;/foo&quot;</code> -&gt; <code>#/foo</code> -&gt; <code>[&quot;bar&quot;, &quot;baz&quot;]</code></li><li><code>&quot;/foo/0&quot;</code> -&gt; <code>#/foo/0</code> -&gt; <code>&quot;bar&quot;</code></li><li><code>&quot;/&quot;</code> -&gt; <code>#/</code> -&gt; <code>0</code></li><li><code>&quot;/a~1b&quot;</code> -&gt; <code>#/a~1b</code> -&gt; <code>1</code></li><li><code>&quot;/c%d&quot;</code> -&gt; <code>#/c%25d</code> -&gt; <code>2</code></li><li><code>&quot;/ &quot;</code> -&gt; <code>#/%20</code> -&gt; <code>7</code></li><li><code>&quot;/m~0n&quot;</code> -&gt; <code>#/m~0n</code> -&gt; <code>8</code></li></ul><h2 id="building-pointers-programmatically"><a href="#building-pointers-programmatically" class="anchor"></a>Building Pointers Programmatically</h2><p>Instead of parsing strings, you can build pointers from indices:</p><pre class="language-ocaml"><code># let port_ptr = make [mem &quot;database&quot;; mem &quot;port&quot;];;
 val port_ptr : nav t = [Mem &quot;database&quot;; Mem &quot;port&quot;]
 # to_string port_ptr;;
-- : string = &quot;/database/port&quot;</code></pre><p>For array access, use the <code>nth</code> helper:</p><pre class="language-ocaml"><code># let first_feature_ptr = make [mem &quot;features&quot;; nth 0];;
+- : string = &quot;/database/port&quot;</code></pre><p>For array access, use the <code>Json_pointer.nth</code> helper:</p><pre class="language-ocaml"><code># let first_feature_ptr = make [mem &quot;features&quot;; nth 0];;
 val first_feature_ptr : nav t = [Mem &quot;features&quot;; Nth 0]
 # to_string first_feature_ptr;;
-- : string = &quot;/features/0&quot;</code></pre><h3 id="pointer-navigation"><a href="#pointer-navigation" class="anchor"></a>Pointer Navigation</h3><p>You can build pointers incrementally using the <code>/</code> operator (or <code>append_index</code>):</p><pre class="language-ocaml"><code># let db_ptr = of_string_nav &quot;/database&quot;;;
+- : string = &quot;/features/0&quot;</code></pre><h3 id="pointer-navigation"><a href="#pointer-navigation" class="anchor"></a>Pointer Navigation</h3><p>You can build pointers incrementally using the <code>/</code> operator (or <code>Json_pointer.append_index</code>):</p><pre class="language-ocaml"><code># let db_ptr = of_string_nav &quot;/database&quot;;;
 val db_ptr : nav t = [Mem &quot;database&quot;]
 # let creds_ptr = db_ptr / mem &quot;credentials&quot;;;
 val creds_ptr : nav t = [Mem &quot;database&quot;; Mem &quot;credentials&quot;]
···
     &quot;features&quot;: [&quot;auth&quot;, &quot;logging&quot;, &quot;metrics&quot;]
   }|};;
 val config_json : Jsont.json =
-  {&quot;database&quot;:{&quot;host&quot;:&quot;localhost&quot;,&quot;port&quot;:5432,&quot;credentials&quot;:{&quot;username&quot;:&quot;admin&quot;,&quot;password&quot;:&quot;secret&quot;}},&quot;features&quot;:[&quot;auth&quot;,&quot;logging&quot;,&quot;metrics&quot;]}</code></pre><h3 id="typed-access-with-path"><a href="#typed-access-with-path" class="anchor"></a>Typed Access with <code>path</code></h3><p>The <code>path</code> combinator combines pointer navigation with typed decoding:</p><pre class="language-ocaml"><code># let nav = of_string_nav &quot;/database/host&quot;;;
+  {&quot;database&quot;:{&quot;host&quot;:&quot;localhost&quot;,&quot;port&quot;:5432,&quot;credentials&quot;:{&quot;username&quot;:&quot;admin&quot;,&quot;password&quot;:&quot;secret&quot;}},&quot;features&quot;:[&quot;auth&quot;,&quot;logging&quot;,&quot;metrics&quot;]}</code></pre><h3 id="typed-access-with-path"><a href="#typed-access-with-path" class="anchor"></a>Typed Access with <code>path</code></h3><p>The <code>Json_pointer.path</code> combinator combines pointer navigation with typed decoding:</p><pre class="language-ocaml"><code># let nav = of_string_nav &quot;/database/host&quot;;;
 val nav : nav t = [Mem &quot;database&quot;; Mem &quot;host&quot;]
 # let db_host =
     Jsont.Json.decode
···
       (path (of_string_nav &quot;/database/port&quot;) Jsont.int)
       config_json
     |&gt; Result.get_ok;;
-val typed_port : int = 5432</code></pre><p>The typed approach catches mismatches at decode time with clear errors.</p><h3 id="updates-with-polymorphic-pointers"><a href="#updates-with-polymorphic-pointers" class="anchor"></a>Updates with Polymorphic Pointers</h3><p>The <code>set</code> and <code>add</code> functions accept <code>any</code> pointers, which means you can use the result of <code>of_string</code> directly without pattern matching:</p><pre class="language-ocaml"><code># let tasks = parse_json {|{&quot;tasks&quot;:[&quot;buy milk&quot;]}|};;
+val typed_port : int = 5432</code></pre><p>The typed approach catches mismatches at decode time with clear errors.</p><h3 id="updates-with-polymorphic-pointers"><a href="#updates-with-polymorphic-pointers" class="anchor"></a>Updates with Polymorphic Pointers</h3><p>The <code>Json_pointer.set</code> and <code>Json_pointer.add</code> functions accept <code>Json_pointer.any</code> pointers, which means you can use the result of <code>Json_pointer.of_string</code> directly without pattern matching:</p><pre class="language-ocaml"><code># let tasks = parse_json {|{&quot;tasks&quot;:[&quot;buy milk&quot;]}|};;
 val tasks : Jsont.json = {&quot;tasks&quot;:[&quot;buy milk&quot;]}
 # set (of_string &quot;/tasks/0&quot;) tasks ~value:(Jsont.Json.string &quot;buy eggs&quot;);;
 - : Jsont.json = {&quot;tasks&quot;:[&quot;buy eggs&quot;]}
 # set (of_string &quot;/tasks/-&quot;) tasks ~value:(Jsont.Json.string &quot;call mom&quot;);;
-- : Jsont.json = {&quot;tasks&quot;:[&quot;buy milk&quot;,&quot;call mom&quot;]}</code></pre><p>This is useful for implementing JSON Patch (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>) where operations like <code>&quot;add&quot;</code> can target either existing positions or the append marker. If you need to distinguish between pointer types at runtime, use <code>of_string_kind</code> which returns a polymorphic variant:</p><pre class="language-ocaml"><code># of_string_kind &quot;/tasks/0&quot;;;
+- : Jsont.json = {&quot;tasks&quot;:[&quot;buy milk&quot;,&quot;call mom&quot;]}</code></pre><p>This is useful for implementing JSON Patch (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>) where operations like <code>&quot;add&quot;</code> can target either existing positions or the append marker. If you need to distinguish between pointer types at runtime, use <code>Json_pointer.of_string_kind</code> which returns a polymorphic variant:</p><pre class="language-ocaml"><code># of_string_kind &quot;/tasks/0&quot;;;
 - : [ `Append of append t | `Nav of nav t ] = `Nav [Mem &quot;tasks&quot;; Nth 0]
 # of_string_kind &quot;/tasks/-&quot;;;
 - : [ `Append of append t | `Nav of nav t ] = `Append [Mem &quot;tasks&quot;] /-</code></pre><h2 id="summary"><a href="#summary" class="anchor"></a>Summary</h2><p>JSON Pointer (<a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a>) provides a simple but powerful way to address values within JSON documents:</p><ol><li><b>Syntax</b>: Pointers are strings of <code>/</code>-separated reference tokens</li><li><b>Escaping</b>: Use <code>~0</code> for <code>~</code> and <code>~1</code> for <code>/</code> in tokens (handled automatically by the library)</li><li><b>Evaluation</b>: Tokens navigate through objects (by key) and arrays (by index)</li><li><b>URI Encoding</b>: Pointers can be percent-encoded for use in URIs</li><li><b>Mutations</b>: Combined with JSON Patch (<a href="https://datatracker.ietf.org/doc/html/rfc6902">RFC 6902</a>), pointers enable structured updates</li><li><b>Type Safety</b>: Phantom types (<code>nav t</code> vs <code>append t</code>) prevent misuse of append pointers with retrieval operations, while the <code>any</code> existential type allows ergonomic use with mutation operations</li></ol><p>The <code>json-pointer</code> library implements all of this with type-safe OCaml interfaces, integration with the <code>jsont</code> codec system, and proper error handling for malformed pointers and missing values.</p><h3 id="key-points-on-json-pointer-vs-json-path"><a href="#key-points-on-json-pointer-vs-json-path" class="anchor"></a>Key Points on JSON Pointer vs JSON Path</h3><ul><li><b>JSON Pointer</b> addresses a <em>single</em> location (like a file path)</li><li><b>JSON Path</b> queries for <em>multiple</em> values (like a search)</li><li>The <code>-</code> token is unique to JSON Pointer - it means &quot;append position&quot; for arrays</li><li>The library uses phantom types to enforce that <code>-</code> (append) pointers cannot be used with <code>get</code>/<code>find</code></li></ul></div></body></html>

doc/tutorial.mld

···
 {"foo":["bar","baz"],"":0,"a/b":1,"c%d":2,"e^f":3,"g|h":4,"i\\j":5,"k\"l":6," ":7,"m~n":8}
 ]}
 
-The empty pointer ({!root}) returns the whole document.
+The empty pointer ({!Json_pointer.root}) returns the whole document.
 
 {2 Object Member Access}
 
···
 type any     (* Existential: wraps either nav or append *)
 v}
 
-When you parse a pointer with {!of_string}, you get an {!any} pointer
+When you parse a pointer with {!Json_pointer.of_string}, you get an {!type:Json_pointer.any} pointer
 that can be used directly with mutation operations:
 
 {@ocaml[
···
 - : any = Any <abstr>
 ]}
 
-The [-] creates an append pointer. The {!any} type wraps either kind,
-making it ergonomic to use with operations like {!set} and {!add}.
+The [-] creates an append pointer. The {!type:Json_pointer.any} type wraps either kind,
+making it ergonomic to use with operations like {!Json_pointer.set} and {!Json_pointer.add}.
 
 {2 Why Two Pointer Types?}
 
···
 So you {b cannot use [get] or [find]} with an append pointer - it makes
 no sense to retrieve a value from a position that doesn't exist! The
 library enforces this:
-- Use {!of_string_nav} when you need to call {!get} or {!find}
-- Use {!of_string} (returns {!any}) for mutation operations
+- Use {!Json_pointer.of_string_nav} when you need to call {!Json_pointer.get} or {!Json_pointer.find}
+- Use {!Json_pointer.of_string} (returns {!type:Json_pointer.any}) for mutation operations
 
-Mutation operations like {!add} accept {!any} directly:
+Mutation operations like {!Json_pointer.add} accept {!type:Json_pointer.any} directly:
 
 {x@ocaml[
 # let arr_obj = parse_json {|{"foo":["a","b"]}|};;
···
 - : Jsont.json = {"foo":["a","b","c"]}
 ]x}
 
-For retrieval operations, use {!of_string_nav} which ensures the pointer
+For retrieval operations, use {!Json_pointer.of_string_nav} which ensures the pointer
 doesn't contain [-]:
 
 {@ocaml[
···
 
 {2 Creating Append Pointers Programmatically}
 
-You can convert a navigation pointer to an append pointer using {!at_end}:
+You can convert a navigation pointer to an append pointer using {!Json_pointer.at_end}:
 
 {@ocaml[
 # let nav_ptr = of_string_nav "/foo";;
···
 
 {2 Add}
 
-The {!add} operation inserts a value at a location. It accepts {!any}
-pointers, so you can use {!of_string} directly:
+The {!Json_pointer.add} operation inserts a value at a location. It accepts {!type:Json_pointer.any}
+pointers, so you can use {!Json_pointer.of_string} directly:
 
 {x@ocaml[
 # let obj = parse_json {|{"foo":"bar"}|};;
···
 - : Jsont.json = {"foo":"bar","baz":"qux"}
 ]x}
 
-For arrays, {!add} inserts BEFORE the specified index:
+For arrays, {!Json_pointer.add} inserts BEFORE the specified index:
 
 {x@ocaml[
 # let arr_obj = parse_json {|{"foo":["a","b"]}|};;
···
 - : Jsont.json = {"foo":["a","b","c"]}
 ]x}
 
-You can also use {!at_end} to create an append pointer programmatically:
+You can also use {!Json_pointer.at_end} to create an append pointer programmatically:
 
 {x@ocaml[
 # add (any (at_end (of_string_nav "/foo"))) arr_obj ~value:(Jsont.Json.string "c");;
···
 
 {2 Ergonomic Mutation with [any]}
 
-Since {!add}, {!set}, {!move}, and {!copy} accept {!any} pointers, you can
-use {!of_string} directly without any pattern matching. This makes JSON
+Since {!Json_pointer.add}, {!Json_pointer.set}, {!Json_pointer.move}, and {!Json_pointer.copy} accept {!type:Json_pointer.any} pointers, you can
+use {!Json_pointer.of_string} directly without any pattern matching. This makes JSON
 Patch implementations straightforward:
 
 {x@ocaml[
···
 
 {2 Remove}
 
-The {!remove} operation deletes a value. It only accepts [nav t] because
+The {!Json_pointer.remove} operation deletes a value. It only accepts [nav t] because
 you can only remove something that exists:
 
 {x@ocaml[
···
 
 {2 Replace}
 
-The {!replace} operation updates an existing value:
+The {!Json_pointer.replace} operation updates an existing value:
 
 {@ocaml[
 # replace (of_string_nav "/foo") obj ~value:(Jsont.Json.string "baz")
···
 - : Jsont.json = {"foo":"baz"}
 ]}
 
-Unlike {!add}, {!replace} requires the target to already exist (hence [nav t]).
+Unlike {!Json_pointer.add}, {!Json_pointer.replace} requires the target to already exist (hence [nav t]).
 Attempting to replace a nonexistent path raises an error.
 
 {2 Move}
 
-The {!move} operation relocates a value. The source ([from]) must be a [nav t]
+The {!Json_pointer.move} operation relocates a value. The source ([from]) must be a [nav t]
 (you can only move something that exists), but the destination ([path])
-accepts {!any}:
+accepts {!type:Json_pointer.any}:
 
 {x@ocaml[
 # let nested = parse_json {|{"foo":{"bar":"baz"},"qux":{}}|};;
···
 
 {2 Copy}
 
-The {!copy} operation duplicates a value (same typing as {!move}):
+The {!Json_pointer.copy} operation duplicates a value (same typing as {!Json_pointer.move}):
 
 {x@ocaml[
 # let to_copy = parse_json {|{"foo":{"bar":"baz"}}|};;
···
 
 {2 Test}
 
-The {!test} operation verifies a value (useful in JSON Patch):
+The {!Json_pointer.test} operation verifies a value (useful in JSON Patch):
 
 {@ocaml[
 # test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "bar");;
···
 
 {2 Escaping in Action}
 
-The {!Token} module exposes the escaping functions:
+The {!Json_pointer.Token} module exposes the escaping functions:
 
 {@ocaml[
 # Token.escape "hello";;
···
 - : string = "/database/port"
 ]}
 
-For array access, use the {!nth} helper:
+For array access, use the {!Json_pointer.nth} helper:
 
 {@ocaml[
 # let first_feature_ptr = make [mem "features"; nth 0];;
···
 
 {2 Pointer Navigation}
 
-You can build pointers incrementally using the [/] operator (or {!append_index}):
+You can build pointers incrementally using the [/] operator (or {!Json_pointer.append_index}):
 
 {@ocaml[
 # let db_ptr = of_string_nav "/database";;
···
 
 {2 Typed Access with [path]}
 
-The {!path} combinator combines pointer navigation with typed decoding:
+The {!Json_pointer.path} combinator combines pointer navigation with typed decoding:
 
 {@ocaml[
 # let nav = of_string_nav "/database/host";;
···
 
 {2 Updates with Polymorphic Pointers}
 
-The {!set} and {!add} functions accept {!any} pointers, which means you can
-use the result of {!of_string} directly without pattern matching:
+The {!Json_pointer.set} and {!Json_pointer.add} functions accept {!type:Json_pointer.any} pointers, which means you can
+use the result of {!Json_pointer.of_string} directly without pattern matching:
 
 {x@ocaml[
 # let tasks = parse_json {|{"tasks":["buy milk"]}|};;
···
 This is useful for implementing JSON Patch ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}) where
 operations like ["add"] can target either existing positions or the
 append marker. If you need to distinguish between pointer types at runtime,
-use {!of_string_kind} which returns a polymorphic variant:
+use {!Json_pointer.of_string_kind} which returns a polymorphic variant:
 
 {x@ocaml[
 # of_string_kind "/tasks/0";;

src/json_pointer.mli

···
   (** [unescape s] unescapes a JSON Pointer reference token.
       Specifically, [~1] becomes [/] and [~0] becomes [~].
 
-      @raise Jsont.Error if [s] contains invalid escape sequences
+      @raise Jsont.Error.Error if [s] contains invalid escape sequences
       (a [~] not followed by [0] or [1]). *)
 end
 
···
 
 (** {2 Existential wrapper}
 
-    The {!any} type wraps a pointer of unknown phantom type, allowing
+    The {!type:any} type wraps a pointer of unknown phantom type, allowing
     ergonomic use with mutation operations like {!set} and {!add} without
     needing to pattern match on the pointer kind. *)
 
···
 (** {2:coercion Coercion and inspection} *)
 
 val any : _ t -> any
-(** [any p] wraps a typed pointer in the existential {!any} type.
-    Use this when you have a [nav t] or [append t] but need an {!any}
+(** [any p] wraps a typed pointer in the existential {!type:any} type.
+    Use this when you have a [nav t] or [append t] but need an {!type:any}
     for use with functions like {!set} or {!add}. *)
 
 val is_nav : any -> bool
···
 
 val to_nav_exn : any -> nav t
 (** [to_nav_exn p] returns the navigation pointer if [p] is one.
-    @raise Jsont.Error if [p] is an append pointer. *)
+    @raise Jsont.Error.Error if [p] is an append pointer. *)
 
 (** {2:parsing Parsing} *)
 
 val of_string : string -> any
 (** [of_string s] parses a JSON Pointer from its string representation.
 
-    Returns an {!any} pointer that can be used directly with mutation
+    Returns an {!type:any} pointer that can be used directly with mutation
     operations like {!set} and {!add}. For retrieval operations like
     {!get}, use {!of_string_nav} instead.
 
···
     with [/]. Each segment between [/] characters is unescaped as a
     reference token.
 
-    @raise Jsont.Error if [s] has invalid syntax:
+    @raise Jsont.Error.Error if [s] has invalid syntax:
     - Non-empty string not starting with [/]
     - Invalid escape sequence ([~] not followed by [0] or [1])
     - [-] appears in non-final position *)
···
     differently, or when you need a typed pointer for operations that
     require a specific kind.
 
-    @raise Jsont.Error if [s] has invalid syntax. *)
+    @raise Jsont.Error.Error if [s] has invalid syntax. *)
 
 val of_string_nav : string -> nav t
 (** [of_string_nav s] parses a JSON Pointer that must not contain [-].
···
     Use this when you need a {!nav} pointer for retrieval operations
     like {!get} or {!find}.
 
-    @raise Jsont.Error if [s] has invalid syntax or contains [-]. *)
+    @raise Jsont.Error.Error if [s] has invalid syntax or contains [-]. *)
 
 val of_string_result : string -> (any, string) result
 (** [of_string_result s] is like {!of_string} but returns a result
···
     according to {{:https://www.rfc-editor.org/rfc/rfc3986}RFC 3986}.
     The leading [#] should {b not} be included in [s].
 
-    @raise Jsont.Error on invalid syntax or invalid percent-encoding. *)
+    @raise Jsont.Error.Error on invalid syntax or invalid percent-encoding. *)
 
 val of_uri_fragment_nav : string -> nav t
 (** [of_uri_fragment_nav s] is like {!of_uri_fragment} but requires
     the pointer to not contain [-].
 
-    @raise Jsont.Error if invalid or contains [-]. *)
+    @raise Jsont.Error.Error if invalid or contains [-]. *)
 
 val of_uri_fragment_result : string -> (any, string) result
 (** [of_uri_fragment_result s] is like {!of_uri_fragment} but returns
···
 
 (** {1 Evaluation}
 
-    These functions evaluate a JSON Pointer against a {!Jsont.json} value
+    These functions evaluate a JSON Pointer against a {!type:Jsont.json} value
     to retrieve the referenced value. They only accept {!nav} pointers
     since {!append} pointers refer to nonexistent positions. *)
 
 val get : nav t -> Jsont.json -> Jsont.json
 (** [get p json] retrieves the value at pointer [p] in [json].
 
-    @raise Jsont.Error if:
+    @raise Jsont.Error.Error if:
     - The pointer references a nonexistent object member
     - The pointer references an out-of-bounds array index
     - An index type doesn't match the JSON value (e.g., [Nth]
···
 
 (** {1 Mutation}
 
-    These functions modify a {!Jsont.json} value at a location specified
+    These functions modify a {!type:Jsont.json} value at a location specified
     by a JSON Pointer. They are designed to support
     {{:https://www.rfc-editor.org/rfc/rfc6902}RFC 6902 JSON Patch}
     operations.
···
     applied; they do not mutate the input.
 
     Functions that support the [-] token ({!set}, {!add}, {!move}, {!copy})
-    accept {!any} pointers, making them easy to use with {!of_string}.
+    accept {!type:any} pointers, making them easy to use with {!of_string}.
     Functions that require an existing element ({!remove}, {!replace})
     only accept {!nav} pointers. *)
 
···
 
     For {!append} pointers, appends [value] to the end of the array.
 
-    This accepts {!any} pointers directly from {!of_string}:
+    This accepts {!type:any} pointers directly from {!of_string}:
     {[set (of_string "/tasks/-") json ~value:(Jsont.Json.string "new task")]}
 
-    @raise Jsont.Error if the pointer doesn't resolve to an existing
+    @raise Jsont.Error.Error if the pointer doesn't resolve to an existing
     location (except for {!append} pointers on arrays). *)
 
 val add : any -> Jsont.json -> value:Jsont.json -> Jsont.json
···
        valid (0 to length inclusive).}
     {- For {!append} pointers: Appends [value] to the array.}}
 
-    @raise Jsont.Error if:
+    @raise Jsont.Error.Error if:
     - The parent of the target location doesn't exist
     - An array index is out of bounds (except for {!append} pointers)
     - The parent is not an object or array *)
···
     For objects, removes the member. For arrays, removes the element
     and shifts subsequent elements.
 
-    @raise Jsont.Error if:
+    @raise Jsont.Error.Error if:
     - [p] is the root (cannot remove the root)
     - The pointer doesn't resolve to an existing value *)
 
···
 
     Unlike {!add}, this requires the target to exist.
 
-    @raise Jsont.Error if the pointer doesn't resolve to an existing value. *)
+    @raise Jsont.Error.Error if the pointer doesn't resolve to an existing value. *)
 
 val move : from:nav t -> path:any -> Jsont.json -> Jsont.json
 (** [move ~from ~path json] moves the value from [from] to [path].
···
     This is equivalent to {!remove} at [from] followed by {!add}
     at [path] with the removed value.
 
-    @raise Jsont.Error if:
+    @raise Jsont.Error.Error if:
     - [from] doesn't resolve to a value
     - [path] is a proper prefix of [from] (would create a cycle) *)
 
···
     This is equivalent to {!get} at [from] followed by {!add}
     at [path] with the retrieved value.
 
-    @raise Jsont.Error if [from] doesn't resolve to a value. *)
+    @raise Jsont.Error.Error if [from] doesn't resolve to a value. *)
 
 val test : nav t -> Jsont.json -> expected:Jsont.json -> bool
 (** [test p json ~expected] tests if the value at [p] equals [expected].
···
       The syntax is the same as RFC 6901 JSON Pointer, except [*] is allowed
       as a reference token for array mapping.
 
-      @raise Jsont.Error if [s] has invalid syntax. *)
+      @raise Jsont.Error.Error if [s] has invalid syntax. *)
 
   val of_string_result : string -> (t, string) result
   (** [of_string_result s] is like {!of_string} but returns a result. *)
···
       For [*] tokens on arrays, maps through all elements and collects results.
       Results that are arrays are flattened into the output.
 
-      @raise Jsont.Error if:
+      @raise Jsont.Error.Error if:
       - A standard token doesn't resolve (member not found, index out of bounds)
       - [*] is used on a non-array value
       - [-] appears in the pointer (not supported in JMAP extended pointers) *)
···
             (Jsont.list Jsont.string)
       ]}
 
-      @raise Jsont.Error if the pointer fails to resolve (and no [absent])
+      @raise Jsont.Error.Error if the pointer fails to resolve (and no [absent])
       or if decoding with [codec] fails. *)
 
   val path_list : t -> 'a Jsont.t -> 'a list Jsont.t
···
         Jmap.path (Jmap.of_string "/list/*/id") (Jsont.list Jsont.string)
       ]}
 
-      @raise Jsont.Error if pointer resolution fails, the result is not an array,
+      @raise Jsont.Error.Error if pointer resolution fails, the result is not an array,
       or any element fails to decode. *)
 end

src/top/json_pointer_top.mli

···
-(** Toplevel printers for {!Json_pointer}, {!Jsont.json}, and {!Jsont.Error.t}.
+(** Toplevel printers for {!Json_pointer}, {!type:Jsont.json}, and {!Jsont.Error.t}.
 
     Printers are automatically installed when the library is loaded:
     {[
···
     ]}
 
     JSON values will display as formatted JSON strings:
-    {[
+    {v
       # Jsont_bytesrw.decode_string Jsont.json {|{"foo": [1, 2]}|};;
       - : Jsont.json = {"foo": [1, 2]}
-    ]}
+    v}
 
     And errors will display as readable messages:
     {[
···
     Suitable for use with [#install_printer]. *)
 
 val json_printer : Format.formatter -> Jsont.json -> unit
-(** [json_printer] formats a {!Jsont.json} value as a human-readable
+(** [json_printer] formats a {!type:Jsont.json} value as a human-readable
     JSON string. Suitable for use with [#install_printer]. *)
 
 val error_printer : Format.formatter -> Jsont.Error.t -> unit