RFC6901 JSON Pointer implementation in OCaml using jsont
anil.recoil.org
1<!DOCTYPE html>
2<html xmlns="http://www.w3.org/1999/xhtml"><head><title>tutorial (tutorial)</title><meta charset="utf-8"/><link rel="stylesheet" href="odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">Index</a> » tutorial</nav><header class="odoc-preamble"><h1 id="json-pointer-tutorial"><a href="#json-pointer-tutorial" class="anchor"></a>JSON Pointer Tutorial</h1><p>This tutorial introduces JSON Pointer as defined in <a href="https://www.rfc-editor.org/rfc/rfc6901">RFC 6901</a>, and demonstrates the <code>json-pointer</code> OCaml library through interactive examples.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#json-pointer-vs-json-path">JSON Pointer vs JSON Path</a></li><li><a href="#setup">Setup</a></li><li><a href="#what-is-json-pointer?">What is JSON Pointer?</a></li><li><a href="#syntax:-reference-tokens">Syntax: Reference Tokens</a><ul><li><a href="#the-index-type">The Index Type</a></li><li><a href="#invalid-syntax">Invalid Syntax</a></li></ul></li><li><a href="#evaluation:-navigating-json">Evaluation: Navigating JSON</a><ul><li><a href="#the-root-pointer">The Root Pointer</a></li><li><a href="#object-member-access">Object Member Access</a></li><li><a href="#array-index-access">Array Index Access</a></li><li><a href="#empty-string-as-key">Empty String as Key</a></li><li><a href="#keys-with-special-characters">Keys with Special Characters</a></li><li><a href="#other-special-characters-(no-escaping-needed)">Other Special Characters (No Escaping Needed)</a></li><li><a href="#error-conditions">Error Conditions</a></li><li><a href="#array-index-rules">Array Index Rules</a></li></ul></li><li><a href="#the-end-of-array-marker:---and-type-safety">The End-of-Array Marker: <code>-</code> and Type Safety</a><ul><li><a href="#navigation-vs-append-pointers">Navigation vs Append Pointers</a></li><li><a href="#why-two-pointer-types?">Why Two Pointer Types?</a></li><li><a href="#creating-append-pointers-programmatically">Creating Append Pointers Programmatically</a></li></ul></li><li><a href="#mutation-operations">Mutation Operations</a><ul><li><a href="#add">Add</a></li><li><a href="#ergonomic-mutation-with-any">Ergonomic Mutation with <code>any</code></a></li><li><a href="#remove">Remove</a></li><li><a href="#replace">Replace</a></li><li><a href="#move">Move</a></li><li><a href="#copy">Copy</a></li><li><a href="#test">Test</a></li></ul></li><li><a href="#escaping">Escaping Special Characters</a><ul><li><a href="#the-library-handles-escaping-automatically">The Library Handles Escaping Automatically</a></li><li><a href="#escaping-in-action">Escaping in Action</a></li><li><a href="#unescaping">Unescaping</a></li><li><a href="#the-order-matters!">The Order Matters!</a></li></ul></li><li><a href="#uri-fragment-encoding">URI Fragment Encoding</a></li><li><a href="#building-pointers-programmatically">Building Pointers Programmatically</a><ul><li><a href="#pointer-navigation">Pointer Navigation</a></li></ul></li><li><a href="#jsont-integration">Jsont Integration</a><ul><li><a href="#typed-access-with-path">Typed Access with <code>path</code></a></li><li><a href="#default-values-with-~absent">Default Values with <code>~absent</code></a></li><li><a href="#nested-path-extraction">Nested Path Extraction</a></li><li><a href="#comparison:-raw-vs-typed-access">Comparison: Raw vs Typed Access</a></li><li><a href="#updates-with-polymorphic-pointers">Updates with Polymorphic Pointers</a></li></ul></li><li><a href="#summary">Summary</a><ul><li><a href="#key-points-on-json-pointer-vs-json-path">Key Points on JSON Pointer vs JSON Path</a></li></ul></li></ul></nav></div><div class="odoc-content"><h2 id="json-pointer-vs-json-path"><a href="#json-pointer-vs-json-path" class="anchor"></a>JSON Pointer vs JSON Path</h2><p>Before diving in, it's worth understanding the difference between JSON Pointer and JSON Path, as they serve different purposes:</p><p><b>JSON Pointer</b> (<a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a>) is an <em>indicator syntax</em> that specifies a <em>single location</em> within JSON data. It always identifies at most one value.</p><p><b>JSON Path</b> is a <em>query syntax</em> that can <em>search</em> JSON data and return <em>multiple</em> values matching specified criteria.</p><p>Use JSON Pointer when you need to address a single, specific location (like JSON Schema's <code>$ref</code>). Use JSON Path when you might need multiple results (like Kubernetes queries).</p><p>The <code>json-pointer</code> library implements JSON Pointer and integrates with the <code>Jsont.Path</code> type for representing navigation indices.</p><h2 id="setup"><a href="#setup" class="anchor"></a>Setup</h2><p>First, let's set up our environment. In the toplevel, you can load the library with <code>#require "json-pointer.top";;</code> which will automatically install pretty printers.</p><pre class="language-ocaml"><code># Json_pointer_top.install ();;
3- : unit = ()
4# open Json_pointer;;
5# let parse_json s =
6 match Jsont_bytesrw.decode_string Jsont.json s with
7 | Ok json -> json
8 | Error e -> failwith e;;
9val parse_json : string -> Jsont.json = <fun></code></pre><h2 id="what-is-json-pointer?"><a href="#what-is-json-pointer?" class="anchor"></a>What is JSON Pointer?</h2><p>From <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-1">RFC 6901, Section 1</a>:</p><p><i>JSON Pointer defines a string syntax for identifying a specific value within a JavaScript Object Notation (JSON) document.</i></p><p>In other words, JSON Pointer is an addressing scheme for locating values inside a JSON structure. Think of it like a filesystem path, but for JSON documents instead of files.</p><p>For example, given this JSON document:</p><pre class="language-ocaml"><code># let users_json = parse_json {|{
10 "users": [
11 {"name": "Alice", "age": 30},
12 {"name": "Bob", "age": 25}
13 ]
14 }|};;
15val users_json : Jsont.json =
16 {"users":[{"name":"Alice","age":30},{"name":"Bob","age":25}]}</code></pre><p>The JSON Pointer <code>/users/0/name</code> refers to the string <code>"Alice"</code>:</p><pre class="language-ocaml"><code># let ptr = of_string_nav "/users/0/name";;
17val ptr : nav t = [Mem "users"; Nth 0; Mem "name"]
18# get ptr users_json;;
19- : Jsont.json = "Alice"</code></pre><p>In OCaml, this is represented by the <code>'a Json_pointer.t</code> type - a sequence of navigation steps from the document root to a target value. The phantom type parameter <code>'a</code> encodes whether this is a navigation pointer or an append pointer (more on this later).</p><h2 id="syntax:-reference-tokens"><a href="#syntax:-reference-tokens" class="anchor"></a>Syntax: Reference Tokens</h2><p><a href="https://datatracker.ietf.org/doc/html/rfc6901#section-3">RFC 6901, Section 3</a> defines the syntax:</p><p><i>A JSON Pointer is a Unicode string containing a sequence of zero or more reference tokens, each prefixed by a '/' (%x2F) character.</i></p><p>The grammar is elegantly simple:</p><pre>json-pointer = *( "/" reference-token )
20reference-token = *( unescaped / escaped )</pre><p>This means:</p><ul><li>The empty string <code>""</code> is a valid pointer (it refers to the whole document)</li><li>Every non-empty pointer starts with <code>/</code></li><li>Everything between <code>/</code> characters is a "reference token"</li></ul><p>Let's see this in action:</p><pre class="language-ocaml"><code># of_string_nav "";;
21- : nav t = []</code></pre><p>The empty pointer has no reference tokens - it points to the root.</p><pre class="language-ocaml"><code># of_string_nav "/foo";;
22- : nav t = [Mem "foo"]</code></pre><p>The pointer <code>/foo</code> has one token: <code>foo</code>. Since it's not a number, it's interpreted as an object member name (<code>Mem</code>).</p><pre class="language-ocaml"><code># of_string_nav "/foo/0";;
23- : nav t = [Mem "foo"; Nth 0]</code></pre><p>Here we have two tokens: <code>foo</code> (a member name) and <code>0</code> (interpreted as an array index <code>Nth</code>).</p><pre class="language-ocaml"><code># of_string_nav "/foo/bar/baz";;
24- : nav t = [Mem "foo"; Mem "bar"; Mem "baz"]</code></pre><p>Multiple tokens navigate deeper into nested structures.</p><h3 id="the-index-type"><a href="#the-index-type" class="anchor"></a>The Index Type</h3><p>Each reference token is represented using <code>Jsont.Path.index</code>:</p><pre>type index = Jsont.Path.index
25(* = Jsont.Path.Mem of string * Jsont.Meta.t
26 | Jsont.Path.Nth of int * Jsont.Meta.t *)</pre><p>The <code>Mem</code> constructor is for object member access, and <code>Nth</code> is for array index access. The member name is <b>unescaped</b> - you work with the actual key string (like <code>"a/b"</code>) and the library handles any escaping needed for the JSON Pointer string representation.</p><h3 id="invalid-syntax"><a href="#invalid-syntax" class="anchor"></a>Invalid Syntax</h3><p>What happens if a pointer doesn't start with <code>/</code>?</p><pre class="language-ocaml"><code># of_string_nav "foo";;
27Exception:
28Jsont.Error Invalid JSON Pointer: must be empty or start with '/': foo.</code></pre><p>The RFC is strict: non-empty pointers MUST start with <code>/</code>.</p><p>For safer parsing, use <code>of_string_result</code>:</p><pre class="language-ocaml"><code># of_string_result "foo";;
29- : (any, string) result =
30Error "Invalid JSON Pointer: must be empty or start with '/': foo"
31# of_string_result "/valid";;
32- : (any, string) result = Ok (Any <abstr>)</code></pre><h2 id="evaluation:-navigating-json"><a href="#evaluation:-navigating-json" class="anchor"></a>Evaluation: Navigating JSON</h2><p>Now we come to the heart of JSON Pointer: evaluation. <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-4">RFC 6901, Section 4</a> describes how a pointer is resolved against a JSON document:</p><p><i>Evaluation of a JSON Pointer begins with a reference to the root value of a JSON document and completes with a reference to some value within the document. Each reference token in the JSON Pointer is evaluated sequentially.</i></p><p>Let's use the example JSON document from <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-5">RFC 6901, Section 5</a>:</p><pre class="language-ocaml"><code># let rfc_example = parse_json {|{
33 "foo": ["bar", "baz"],
34 "": 0,
35 "a/b": 1,
36 "c%d": 2,
37 "e^f": 3,
38 "g|h": 4,
39 "i\\j": 5,
40 "k\"l": 6,
41 " ": 7,
42 "m~n": 8
43 }|};;
44val rfc_example : Jsont.json =
45 {"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}</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 ;;
46- : Jsont.json =
47{"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}</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 "/foo") rfc_example ;;
48- : Jsont.json = ["bar","baz"]</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 "/foo/0") rfc_example ;;
49- : Jsont.json = "bar"
50# get (of_string_nav "/foo/1") rfc_example ;;
51- : Jsont.json = "baz"</code></pre><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><pre class="language-ocaml"><code># get (of_string_nav "/") rfc_example ;;
52- : Jsont.json = 0</code></pre><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><pre class="language-ocaml"><code># get (of_string_nav "/a~1b") rfc_example ;;
53- : Jsont.json = 1</code></pre><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><pre class="language-ocaml"><code># get (of_string_nav "/m~0n") rfc_example ;;
54- : Jsont.json = 8</code></pre><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><pre class="language-ocaml"><code># let slash_ptr = make [mem "a/b"];;
55val slash_ptr : nav t = [Mem "a/b"]
56# to_string slash_ptr;;
57- : string = "/a~1b"
58# get slash_ptr rfc_example ;;
59- : Jsont.json = 1</code></pre><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><pre class="language-ocaml"><code># get (of_string_nav "/c%d") rfc_example ;;
60- : Jsont.json = 2
61# get (of_string_nav "/e^f") rfc_example ;;
62- : Jsont.json = 3
63# get (of_string_nav "/g|h") rfc_example ;;
64- : Jsont.json = 4
65# get (of_string_nav "/ ") rfc_example ;;
66- : Jsont.json = 7</code></pre><p>Even a space is a valid key character!</p><h3 id="error-conditions"><a href="#error-conditions" class="anchor"></a>Error Conditions</h3><p>What happens when we try to access something that doesn't exist?</p><pre class="language-ocaml"><code># get_result (of_string_nav "/nonexistent") rfc_example;;
67- : (Jsont.json, Jsont.Error.t) result =
68Error JSON Pointer: member 'nonexistent' not found
69File "-":
70# find (of_string_nav "/nonexistent") rfc_example;;
71- : Jsont.json option = None</code></pre><p>Or an out-of-bounds array index:</p><pre class="language-ocaml"><code># find (of_string_nav "/foo/99") rfc_example;;
72- : Jsont.json option = None</code></pre><p>Or try to index into a non-container:</p><pre class="language-ocaml"><code># find (of_string_nav "/foo/0/invalid") rfc_example;;
73- : Jsont.json option = None</code></pre><p>The library provides both exception-raising and result-returning variants:</p><pre>val get : nav t -> Jsont.json -> Jsont.json
74val get_result : nav t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
75val find : nav t -> Jsont.json -> 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><pre class="language-ocaml"><code># of_string_nav "/foo/0";;
76- : nav t = [Mem "foo"; Nth 0]</code></pre><p>Zero itself is fine.</p><pre class="language-ocaml"><code># of_string_nav "/foo/01";;
77- : nav t = [Mem "foo"; Mem "01"]</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 "-", 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 *)
78type append (* A pointer ending with "-" (append position) *)
79type 'a t (* Pointer with phantom type parameter *)
80type 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 "/foo/0";;
81- : any = Any <abstr>
82# of_string "/foo/-";;
83- : any = Any <abstr></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 "-" 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 {|{"foo":["a","b"]}|};;
84val arr_obj : Jsont.json = {"foo":["a","b"]}
85# add (of_string "/foo/-") arr_obj ~value:(Jsont.Json.string "c");;
86- : Jsont.json = {"foo":["a","b","c"]}</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 "/foo/0";;
87- : nav t = [Mem "foo"; Nth 0]
88# of_string_nav "/foo/-";;
89Exception:
90Jsont.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 "/foo";;
91val nav_ptr : nav t = [Mem "foo"]
92# let app_ptr = at_end nav_ptr;;
93val app_ptr : append t = [Mem "foo"] /-
94# to_string app_ptr;;
95- : string = "/foo/-"</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 {|{"foo":"bar"}|};;
96val obj : Jsont.json = {"foo":"bar"}
97# add (of_string "/baz") obj ~value:(Jsont.Json.string "qux");;
98- : Jsont.json = {"foo":"bar","baz":"qux"}</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 {|{"foo":["a","b"]}|};;
99val arr_obj : Jsont.json = {"foo":["a","b"]}
100# add (of_string "/foo/1") arr_obj ~value:(Jsont.Json.string "X");;
101- : Jsont.json = {"foo":["a","X","b"]}</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 "/foo/-") arr_obj ~value:(Jsont.Json.string "c");;
102- : Jsont.json = {"foo":["a","b","c"]}</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 "/foo"))) arr_obj ~value:(Jsont.Json.string "c");;
103- : Jsont.json = {"foo":["a","b","c"]}</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 {|{"items":["x"]}|};;
104val items : Jsont.json = {"items":["x"]}
105# add (of_string "/items/0") items ~value:(Jsont.Json.string "y");;
106- : Jsont.json = {"items":["y","x"]}
107# add (of_string "/items/-") items ~value:(Jsont.Json.string "z");;
108- : Jsont.json = {"items":["x","z"]}</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 {|{"foo":"bar","baz":"qux"}|};;
109val two_fields : Jsont.json = {"foo":"bar","baz":"qux"}
110# remove (of_string_nav "/baz") two_fields ;;
111- : Jsont.json = {"foo":"bar"}</code></pre><p>For arrays, it removes and shifts:</p><pre class="language-ocaml"><code># let three_elem = parse_json {|{"foo":["a","b","c"]}|};;
112val three_elem : Jsont.json = {"foo":["a","b","c"]}
113# remove (of_string_nav "/foo/1") three_elem ;;
114- : Jsont.json = {"foo":["a","c"]}</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 "/foo") obj ~value:(Jsont.Json.string "baz")
115 ;;
116- : Jsont.json = {"foo":"baz"}</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 {|{"foo":{"bar":"baz"},"qux":{}}|};;
117val nested : Jsont.json = {"foo":{"bar":"baz"},"qux":{}}
118# move ~from:(of_string_nav "/foo/bar") ~path:(of_string "/qux/thud") nested;;
119- : Jsont.json = {"foo":{},"qux":{"thud":"baz"}}</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 {|{"foo":{"bar":"baz"}}|};;
120val to_copy : Jsont.json = {"foo":{"bar":"baz"}}
121# copy ~from:(of_string_nav "/foo/bar") ~path:(of_string "/foo/qux") to_copy;;
122- : Jsont.json = {"foo":{"bar":"baz","qux":"baz"}}</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 "/foo") obj ~expected:(Jsont.Json.string "bar");;
123- : bool = true
124# test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "wrong");;
125- : 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 "a/b"];;
126val p : nav t = [Mem "a/b"]
127# to_string p;;
128- : string = "/a~1b"
129# of_string_nav "/a~1b";;
130- : nav t = [Mem "a/b"]</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 "hello";;
131- : string = "hello"
132# Token.escape "a/b";;
133- : string = "a~1b"
134# Token.escape "a~b";;
135- : string = "a~0b"
136# Token.escape "~/";;
137- : string = "~0~1"</code></pre><h3 id="unescaping"><a href="#unescaping" class="anchor"></a>Unescaping</h3><p>And the reverse process:</p><pre class="language-ocaml"><code># Token.unescape "a~1b";;
138- : string = "a/b"
139# Token.unescape "a~0b";;
140- : string = "a~b"</code></pre><h3 id="the-order-matters!"><a href="#the-order-matters!" class="anchor"></a>The Order Matters!</h3><p><a href="https://datatracker.ietf.org/doc/html/rfc6901#section-4">RFC 6901, Section 4</a> is careful to specify the unescaping order:</p><p><i>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).</i></p><p>Let's verify this tricky case:</p><pre class="language-ocaml"><code># Token.unescape "~01";;
141- : string = "~1"</code></pre><p>If we unescaped <code>~0</code> first, <code>~01</code> would become <code>~1</code>, which would then become <code>/</code>. But that's wrong! The sequence <code>~01</code> should become the literal string <code>~1</code> (a tilde followed by the digit one).</p><h2 id="uri-fragment-encoding"><a href="#uri-fragment-encoding" class="anchor"></a>URI Fragment Encoding</h2><p>JSON Pointers can be embedded in URIs. <a href="https://datatracker.ietf.org/doc/html/rfc6901#section-6">RFC 6901, Section 6</a> explains:</p><p><i>A JSON Pointer can be represented in a URI fragment identifier by encoding it into octets using UTF-8, while percent-encoding those characters not allowed by the fragment rule in <a href="https://datatracker.ietf.org/doc/html/rfc3986">RFC 3986</a>.</i></p><p>This adds percent-encoding on top of the <code>~0</code>/<code>~1</code> escaping:</p><pre class="language-ocaml"><code># to_uri_fragment (of_string_nav "/foo");;
142- : string = "/foo"
143# to_uri_fragment (of_string_nav "/a~1b");;
144- : string = "/a~1b"
145# to_uri_fragment (of_string_nav "/c%d");;
146- : string = "/c%25d"
147# to_uri_fragment (of_string_nav "/ ");;
148- : string = "/%20"</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>""</code> -> <code>#</code> -> whole document</li><li><code>"/foo"</code> -> <code>#/foo</code> -> <code>["bar", "baz"]</code></li><li><code>"/foo/0"</code> -> <code>#/foo/0</code> -> <code>"bar"</code></li><li><code>"/"</code> -> <code>#/</code> -> <code>0</code></li><li><code>"/a~1b"</code> -> <code>#/a~1b</code> -> <code>1</code></li><li><code>"/c%d"</code> -> <code>#/c%25d</code> -> <code>2</code></li><li><code>"/ "</code> -> <code>#/%20</code> -> <code>7</code></li><li><code>"/m~0n"</code> -> <code>#/m~0n</code> -> <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 "database"; mem "port"];;
149val port_ptr : nav t = [Mem "database"; Mem "port"]
150# to_string port_ptr;;
151- : string = "/database/port"</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 "features"; nth 0];;
152val first_feature_ptr : nav t = [Mem "features"; Nth 0]
153# to_string first_feature_ptr;;
154- : string = "/features/0"</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 "/database";;
155val db_ptr : nav t = [Mem "database"]
156# let creds_ptr = db_ptr / mem "credentials";;
157val creds_ptr : nav t = [Mem "database"; Mem "credentials"]
158# let user_ptr = creds_ptr / mem "username";;
159val user_ptr : nav t = [Mem "database"; Mem "credentials"; Mem "username"]
160# to_string user_ptr;;
161- : string = "/database/credentials/username"</code></pre><p>Or concatenate two pointers:</p><pre class="language-ocaml"><code># let base = of_string_nav "/api/v1";;
162val base : nav t = [Mem "api"; Mem "v1"]
163# let endpoint = of_string_nav "/users/0";;
164val endpoint : nav t = [Mem "users"; Nth 0]
165# to_string (concat base endpoint);;
166- : string = "/api/v1/users/0"</code></pre><h2 id="jsont-integration"><a href="#jsont-integration" class="anchor"></a>Jsont Integration</h2><p>The library integrates with the <code>Jsont</code> codec system, allowing you to combine JSON Pointer navigation with typed decoding. This is powerful because you can point to a location in a JSON document and decode it directly to an OCaml type.</p><pre class="language-ocaml"><code># let config_json = parse_json {|{
167 "database": {
168 "host": "localhost",
169 "port": 5432,
170 "credentials": {"username": "admin", "password": "secret"}
171 },
172 "features": ["auth", "logging", "metrics"]
173 }|};;
174val config_json : Jsont.json =
175 {"database":{"host":"localhost","port":5432,"credentials":{"username":"admin","password":"secret"}},"features":["auth","logging","metrics"]}</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 "/database/host";;
176val nav : nav t = [Mem "database"; Mem "host"]
177# let db_host =
178 Jsont.Json.decode
179 (path nav Jsont.string)
180 config_json
181 |> Result.get_ok;;
182val db_host : string = "localhost"
183# let db_port =
184 Jsont.Json.decode
185 (path (of_string_nav "/database/port") Jsont.int)
186 config_json
187 |> Result.get_ok;;
188val db_port : int = 5432</code></pre><p>Extract a list of strings:</p><pre class="language-ocaml"><code># let features =
189 Jsont.Json.decode
190 (path (of_string_nav "/features") Jsont.(list string))
191 config_json
192 |> Result.get_ok;;
193val features : string list = ["auth"; "logging"; "metrics"]</code></pre><h3 id="default-values-with-~absent"><a href="#default-values-with-~absent" class="anchor"></a>Default Values with <code>~absent</code></h3><p>Use <code>~absent</code> to provide a default when a path doesn't exist:</p><pre class="language-ocaml"><code># let timeout =
194 Jsont.Json.decode
195 (path ~absent:30 (of_string_nav "/database/timeout") Jsont.int)
196 config_json
197 |> Result.get_ok;;
198val timeout : int = 30</code></pre><h3 id="nested-path-extraction"><a href="#nested-path-extraction" class="anchor"></a>Nested Path Extraction</h3><p>You can extract values from deeply nested structures:</p><pre class="language-ocaml"><code># let org_json = parse_json {|{
199 "organization": {
200 "owner": {"name": "Alice", "email": "alice@example.com", "age": 35},
201 "members": [{"name": "Bob", "email": "bob@example.com", "age": 28}]
202 }
203 }|};;
204val org_json : Jsont.json =
205 {"organization":{"owner":{"name":"Alice","email":"alice@example.com","age":35},"members":[{"name":"Bob","email":"bob@example.com","age":28}]}}
206# Jsont.Json.decode
207 (path (of_string_nav "/organization/owner/name") Jsont.string)
208 org_json
209 |> Result.get_ok;;
210- : string = "Alice"
211# Jsont.Json.decode
212 (path (of_string_nav "/organization/members/0/age") Jsont.int)
213 org_json
214 |> Result.get_ok;;
215- : int = 28</code></pre><h3 id="comparison:-raw-vs-typed-access"><a href="#comparison:-raw-vs-typed-access" class="anchor"></a>Comparison: Raw vs Typed Access</h3><p><b>Raw access</b> requires pattern matching:</p><pre class="language-ocaml"><code># let raw_port =
216 match get (of_string_nav "/database/port") config_json with
217 | Jsont.Number (f, _) -> int_of_float f
218 | _ -> failwith "expected number";;
219val raw_port : int = 5432</code></pre><p><b>Typed access</b> is cleaner and type-safe:</p><pre class="language-ocaml"><code># let typed_port =
220 Jsont.Json.decode
221 (path (of_string_nav "/database/port") Jsont.int)
222 config_json
223 |> Result.get_ok;;
224val 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 {|{"tasks":["buy milk"]}|};;
225val tasks : Jsont.json = {"tasks":["buy milk"]}
226# set (of_string "/tasks/0") tasks ~value:(Jsont.Json.string "buy eggs");;
227- : Jsont.json = {"tasks":["buy eggs"]}
228# set (of_string "/tasks/-") tasks ~value:(Jsont.Json.string "call mom");;
229- : Jsont.json = {"tasks":["buy milk","call mom"]}</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>"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><pre class="language-ocaml"><code># of_string_kind "/tasks/0";;
230- : [ `Append of append t | `Nav of nav t ] = `Nav [Mem "tasks"; Nth 0]
231# of_string_kind "/tasks/-";;
232- : [ `Append of append t | `Nav of nav t ] = `Append [Mem "tasks"] /-</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 "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>