anil.recoil.org
RFC6901 JSON Pointer implementation in OCaml using jsont
more
+16
-16
doc/tutorial.mld
+16
-16
doc/tutorial.mld
···
9
Before diving in, it's worth understanding the difference between JSON
10
Pointer and JSON Path, as they serve different purposes:
11
12
-
{b JSON Pointer} (RFC 6901) is an {e indicator syntax} that specifies a
13
{e single location} within JSON data. It always identifies at most one
14
value.
15
···
42
43
{1 What is JSON Pointer?}
44
45
-
From RFC 6901, Section 1:
46
47
{i JSON Pointer defines a string syntax for identifying a specific value
48
within a JavaScript Object Notation (JSON) document.}
···
80
81
{1 Syntax: Reference Tokens}
82
83
-
RFC 6901, Section 3 defines the syntax:
84
85
{i A JSON Pointer is a Unicode string containing a sequence of zero or more
86
reference tokens, each prefixed by a '/' (%x2F) character.}
···
168
169
{1 Evaluation: Navigating JSON}
170
171
-
Now we come to the heart of JSON Pointer: evaluation. RFC 6901, Section 4
172
describes how a pointer is resolved against a JSON document:
173
174
{i Evaluation of a JSON Pointer begins with a reference to the root value
···
176
the document. Each reference token in the JSON Pointer is evaluated
177
sequentially.}
178
179
-
Let's use the example JSON document from RFC 6901, Section 5:
180
181
{x@ocaml[
182
# let rfc_example = parse_json {|{
···
326
327
{2 Array Index Rules}
328
329
-
RFC 6901 has specific rules for array indices. Section 4 states:
330
331
{i characters comprised of digits [...] that represent an unsigned base-10
332
integer value, making the new referenced value the array element with
···
354
355
{1 The End-of-Array Marker: [-] and Type Safety}
356
357
-
RFC 6901, Section 4 introduces a special token:
358
359
{i exactly the single character "-", making the new referenced value the
360
(nonexistent) member after the last array element.}
361
362
This [-] marker is unique to JSON Pointer (JSON Path has no equivalent).
363
-
It's primarily useful for JSON Patch operations (RFC 6902) to append
364
elements to arrays.
365
366
{2 Navigation vs Append Pointers}
···
438
439
{1 Mutation Operations}
440
441
-
While RFC 6901 defines JSON Pointer for read-only access, RFC 6902
442
(JSON Patch) uses JSON Pointer for modifications. The [json-pointer]
443
library provides these operations.
444
···
566
567
{1:escaping Escaping Special Characters}
568
569
-
RFC 6901, Section 3 explains the escaping rules:
570
571
{i Because the characters '~' (%x7E) and '/' (%x2F) have special meanings
572
in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be
···
623
624
{2 The Order Matters!}
625
626
-
RFC 6901, Section 4 is careful to specify the unescaping order:
627
628
{i Evaluation of each reference token begins by decoding any escaped
629
character sequence. This is performed by first transforming any
···
646
647
{1 URI Fragment Encoding}
648
649
-
JSON Pointers can be embedded in URIs. RFC 6901, Section 6 explains:
650
651
{i A JSON Pointer can be represented in a URI fragment identifier by
652
encoding it into octets using UTF-8, while percent-encoding those
653
-
characters not allowed by the fragment rule in RFC 3986.}
654
655
This adds percent-encoding on top of the [~0]/[~1] escaping:
656
···
856
- : Jsont.json = {"tasks":["buy milk","call mom"]}
857
]x}
858
859
-
This is useful for implementing JSON Patch ([RFC 6902]) where
860
operations like ["add"] can target either existing positions or the
861
append marker. If you need to distinguish between pointer types at runtime,
862
use {!of_string_kind} which returns a polymorphic variant:
···
870
871
{1 Summary}
872
873
-
JSON Pointer (RFC 6901) provides a simple but powerful way to address
874
values within JSON documents:
875
876
{ol
···
878
{- {b Escaping}: Use [~0] for [~] and [~1] for [/] in tokens (handled automatically by the library)}
879
{- {b Evaluation}: Tokens navigate through objects (by key) and arrays (by index)}
880
{- {b URI Encoding}: Pointers can be percent-encoded for use in URIs}
881
-
{- {b Mutations}: Combined with JSON Patch (RFC 6902), pointers enable structured updates}
882
{- {b Type Safety}: Phantom types ([nav t] vs [append t]) prevent misuse of append pointers with retrieval operations, while the [any] existential type allows ergonomic use with mutation operations}
883
}
884
···
9
Before diving in, it's worth understanding the difference between JSON
10
Pointer and JSON Path, as they serve different purposes:
11
12
+
{b JSON Pointer} ({{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901}) is an {e indicator syntax} that specifies a
13
{e single location} within JSON data. It always identifies at most one
14
value.
15
···
42
43
{1 What is JSON Pointer?}
44
45
+
From {{:https://datatracker.ietf.org/doc/html/rfc6901#section-1}RFC 6901, Section 1}:
46
47
{i JSON Pointer defines a string syntax for identifying a specific value
48
within a JavaScript Object Notation (JSON) document.}
···
80
81
{1 Syntax: Reference Tokens}
82
83
+
{{:https://datatracker.ietf.org/doc/html/rfc6901#section-3}RFC 6901, Section 3} defines the syntax:
84
85
{i A JSON Pointer is a Unicode string containing a sequence of zero or more
86
reference tokens, each prefixed by a '/' (%x2F) character.}
···
168
169
{1 Evaluation: Navigating JSON}
170
171
+
Now we come to the heart of JSON Pointer: evaluation. {{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}RFC 6901, Section 4}
172
describes how a pointer is resolved against a JSON document:
173
174
{i Evaluation of a JSON Pointer begins with a reference to the root value
···
176
the document. Each reference token in the JSON Pointer is evaluated
177
sequentially.}
178
179
+
Let's use the example JSON document from {{:https://datatracker.ietf.org/doc/html/rfc6901#section-5}RFC 6901, Section 5}:
180
181
{x@ocaml[
182
# let rfc_example = parse_json {|{
···
326
327
{2 Array Index Rules}
328
329
+
{{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901} has specific rules for array indices. {{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}Section 4} states:
330
331
{i characters comprised of digits [...] that represent an unsigned base-10
332
integer value, making the new referenced value the array element with
···
354
355
{1 The End-of-Array Marker: [-] and Type Safety}
356
357
+
{{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}RFC 6901, Section 4} introduces a special token:
358
359
{i exactly the single character "-", making the new referenced value the
360
(nonexistent) member after the last array element.}
361
362
This [-] marker is unique to JSON Pointer (JSON Path has no equivalent).
363
+
It's primarily useful for JSON Patch operations ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}) to append
364
elements to arrays.
365
366
{2 Navigation vs Append Pointers}
···
438
439
{1 Mutation Operations}
440
441
+
While {{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901} defines JSON Pointer for read-only access, {{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}
442
(JSON Patch) uses JSON Pointer for modifications. The [json-pointer]
443
library provides these operations.
444
···
566
567
{1:escaping Escaping Special Characters}
568
569
+
{{:https://datatracker.ietf.org/doc/html/rfc6901#section-3}RFC 6901, Section 3} explains the escaping rules:
570
571
{i Because the characters '~' (%x7E) and '/' (%x2F) have special meanings
572
in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be
···
623
624
{2 The Order Matters!}
625
626
+
{{:https://datatracker.ietf.org/doc/html/rfc6901#section-4}RFC 6901, Section 4} is careful to specify the unescaping order:
627
628
{i Evaluation of each reference token begins by decoding any escaped
629
character sequence. This is performed by first transforming any
···
646
647
{1 URI Fragment Encoding}
648
649
+
JSON Pointers can be embedded in URIs. {{:https://datatracker.ietf.org/doc/html/rfc6901#section-6}RFC 6901, Section 6} explains:
650
651
{i A JSON Pointer can be represented in a URI fragment identifier by
652
encoding it into octets using UTF-8, while percent-encoding those
653
+
characters not allowed by the fragment rule in {{:https://datatracker.ietf.org/doc/html/rfc3986}RFC 3986}.}
654
655
This adds percent-encoding on top of the [~0]/[~1] escaping:
656
···
856
- : Jsont.json = {"tasks":["buy milk","call mom"]}
857
]x}
858
859
+
This is useful for implementing JSON Patch ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}) where
860
operations like ["add"] can target either existing positions or the
861
append marker. If you need to distinguish between pointer types at runtime,
862
use {!of_string_kind} which returns a polymorphic variant:
···
870
871
{1 Summary}
872
873
+
JSON Pointer ({{:https://datatracker.ietf.org/doc/html/rfc6901}RFC 6901}) provides a simple but powerful way to address
874
values within JSON documents:
875
876
{ol
···
878
{- {b Escaping}: Use [~0] for [~] and [~1] for [/] in tokens (handled automatically by the library)}
879
{- {b Evaluation}: Tokens navigate through objects (by key) and arrays (by index)}
880
{- {b URI Encoding}: Pointers can be percent-encoded for use in URIs}
881
+
{- {b Mutations}: Combined with JSON Patch ({{:https://datatracker.ietf.org/doc/html/rfc6902}RFC 6902}), pointers enable structured updates}
882
{- {b Type Safety}: Phantom types ([nav t] vs [append t]) prevent misuse of append pointers with retrieval operations, while the [any] existential type allows ergonomic use with mutation operations}
883
}
884