+5

doc/dune

··· 1 1 (mdx 2 2 + (files tutorial.mld) 2 3 (libraries jsont jsont.bytesrw jsont_pointer jsont_pointer_top)) 4 4 + 5 5 + (documentation 6 6 + (package jsont-pointer) 7 7 + (mld_files index tutorial))

+8

doc/index.mld

··· 1 1 + {0 jsont-pointer} 2 2 + 3 3 + {!modules: Jsont_pointer Jsont_pointer_top} 4 4 + 5 5 + {1 Tutorial} 6 6 + 7 7 + See the {!page-tutorial} for a comprehensive guide to using JSON Pointers 8 8 + with this library.

-873

doc/tutorial.md

··· 1 1 - # JSON Pointer Tutorial 2 2 - 3 3 - This tutorial introduces JSON Pointer as defined in 4 4 - [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901), and demonstrates 5 5 - the `jsont-pointer` OCaml library through interactive examples. 6 6 - 7 7 - ## JSON Pointer vs JSON Path 8 8 - 9 9 - Before diving in, it's worth understanding the difference between JSON 10 10 - Pointer and JSON Path, as they serve different purposes: 11 11 - 12 12 - **JSON Pointer** (RFC 6901) is an *indicator syntax* that specifies a 13 13 - *single location* within JSON data. It always identifies at most one 14 14 - value. 15 15 - 16 16 - **JSON Path** is a *query syntax* that can *search* JSON data and return 17 17 - *multiple* values matching specified criteria. 18 18 - 19 19 - Use JSON Pointer when you need to address a single, specific location 20 20 - (like JSON Schema's `$ref`). Use JSON Path when you might need multiple 21 21 - results (like Kubernetes queries). 22 22 - 23 23 - The `jsont-pointer` library implements JSON Pointer and integrates with 24 24 - the `Jsont.Path` type for representing navigation indices. 25 25 - 26 26 - ## Setup 27 27 - 28 28 - First, let's set up our environment with helper functions: 29 29 - 30 30 - ```ocaml 31 31 - # open Jsont_pointer;; 32 32 - # #install_printer Jsont_pointer_top.nav_printer;; 33 33 - # #install_printer Jsont_pointer_top.append_printer;; 34 34 - # #install_printer Jsont_pointer_top.json_printer;; 35 35 - # #install_printer Jsont_pointer_top.error_printer;; 36 36 - # let parse_json s = 37 37 - match Jsont_bytesrw.decode_string Jsont.json s with 38 38 - | Ok json -> json 39 39 - | Error e -> failwith e;; 40 40 - val parse_json : string -> Jsont.json = <fun> 41 41 - ``` 42 42 - 43 43 - ## What is JSON Pointer? 44 44 - 45 45 - From RFC 6901, Section 1: 46 46 - 47 47 - > JSON Pointer defines a string syntax for identifying a specific value 48 48 - > within a JavaScript Object Notation (JSON) document. 49 49 - 50 50 - In other words, JSON Pointer is an addressing scheme for locating values 51 51 - inside a JSON structure. Think of it like a filesystem path, but for JSON 52 52 - documents instead of files. 53 53 - 54 54 - For example, given this JSON document: 55 55 - 56 56 - ```ocaml 57 57 - # let users_json = parse_json {|{ 58 58 - "users": [ 59 59 - {"name": "Alice", "age": 30}, 60 60 - {"name": "Bob", "age": 25} 61 61 - ] 62 62 - }|};; 63 63 - val users_json : Jsont.json = 64 64 - {"users":[{"name":"Alice","age":30},{"name":"Bob","age":25}]} 65 65 - ``` 66 66 - 67 67 - The JSON Pointer `/users/0/name` refers to the string `"Alice"`: 68 68 - 69 69 - ```ocaml 70 70 - # let ptr = of_string_nav "/users/0/name";; 71 71 - val ptr : nav t = [Mem "users"; Nth 0; Mem "name"] 72 72 - # get ptr users_json;; 73 73 - - : Jsont.json = "Alice" 74 74 - ``` 75 75 - 76 76 - In OCaml, this is represented by the `'a Jsont_pointer.t` type - a sequence 77 77 - of navigation steps from the document root to a target value. The phantom 78 78 - type parameter `'a` encodes whether this is a navigation pointer or an 79 79 - append pointer (more on this later). 80 80 - 81 81 - ## Syntax: Reference Tokens 82 82 - 83 83 - RFC 6901, Section 3 defines the syntax: 84 84 - 85 85 - > A JSON Pointer is a Unicode string containing a sequence of zero or more 86 86 - > reference tokens, each prefixed by a '/' (%x2F) character. 87 87 - 88 88 - The grammar is elegantly simple: 89 89 - 90 90 - ``` 91 91 - json-pointer = *( "/" reference-token ) 92 92 - reference-token = *( unescaped / escaped ) 93 93 - ``` 94 94 - 95 95 - This means: 96 96 - - The empty string `""` is a valid pointer (it refers to the whole document) 97 97 - - Every non-empty pointer starts with `/` 98 98 - - Everything between `/` characters is a "reference token" 99 99 - 100 100 - Let's see this in action: 101 101 - 102 102 - ```ocaml 103 103 - # of_string_nav "";; 104 104 - - : nav t = [] 105 105 - ``` 106 106 - 107 107 - The empty pointer has no reference tokens - it points to the root. 108 108 - 109 109 - ```ocaml 110 110 - # of_string_nav "/foo";; 111 111 - - : nav t = [Mem "foo"] 112 112 - ``` 113 113 - 114 114 - The pointer `/foo` has one token: `foo`. Since it's not a number, it's 115 115 - interpreted as an object member name (`Mem`). 116 116 - 117 117 - ```ocaml 118 118 - # of_string_nav "/foo/0";; 119 119 - - : nav t = [Mem "foo"; Nth 0] 120 120 - ``` 121 121 - 122 122 - Here we have two tokens: `foo` (a member name) and `0` (interpreted as 123 123 - an array index `Nth`). 124 124 - 125 125 - ```ocaml 126 126 - # of_string_nav "/foo/bar/baz";; 127 127 - - : nav t = [Mem "foo"; Mem "bar"; Mem "baz"] 128 128 - ``` 129 129 - 130 130 - Multiple tokens navigate deeper into nested structures. 131 131 - 132 132 - ### The Index Type 133 133 - 134 134 - Each reference token is represented using `Jsont.Path.index`: 135 135 - 136 136 - <!-- $MDX skip --> 137 137 - ```ocaml 138 138 - type index = Jsont.Path.index 139 139 - (* = Jsont.Path.Mem of string * Jsont.Meta.t 140 140 - | Jsont.Path.Nth of int * Jsont.Meta.t *) 141 141 - ``` 142 142 - 143 143 - The `Mem` constructor is for object member access, and `Nth` is for array 144 144 - index access. The member name is **unescaped** - you work with the actual 145 145 - key string (like `"a/b"`) and the library handles any escaping needed 146 146 - for the JSON Pointer string representation. 147 147 - 148 148 - ### Invalid Syntax 149 149 - 150 150 - What happens if a pointer doesn't start with `/`? 151 151 - 152 152 - ```ocaml 153 153 - # of_string_nav "foo";; 154 154 - Exception: 155 155 - Jsont.Error Invalid JSON Pointer: must be empty or start with '/': foo. 156 156 - ``` 157 157 - 158 158 - The RFC is strict: non-empty pointers MUST start with `/`. 159 159 - 160 160 - For safer parsing, use `of_string_result`: 161 161 - 162 162 - ```ocaml 163 163 - # of_string_result "foo";; 164 164 - - : ([ `Append of append t | `Nav of nav t ], string) result = 165 165 - Error "Invalid JSON Pointer: must be empty or start with '/': foo" 166 166 - # of_string_result "/valid";; 167 167 - - : ([ `Append of append t | `Nav of nav t ], string) result = 168 168 - Ok (`Nav [Mem "valid"]) 169 169 - ``` 170 170 - 171 171 - ## Evaluation: Navigating JSON 172 172 - 173 173 - Now we come to the heart of JSON Pointer: evaluation. RFC 6901, Section 4 174 174 - describes how a pointer is resolved against a JSON document: 175 175 - 176 176 - > Evaluation of a JSON Pointer begins with a reference to the root value 177 177 - > of a JSON document and completes with a reference to some value within 178 178 - > the document. Each reference token in the JSON Pointer is evaluated 179 179 - > sequentially. 180 180 - 181 181 - Let's use the example JSON document from RFC 6901, Section 5: 182 182 - 183 183 - ```ocaml 184 184 - # let rfc_example = parse_json {|{ 185 185 - "foo": ["bar", "baz"], 186 186 - "": 0, 187 187 - "a/b": 1, 188 188 - "c%d": 2, 189 189 - "e^f": 3, 190 190 - "g|h": 4, 191 191 - "i\\j": 5, 192 192 - "k\"l": 6, 193 193 - " ": 7, 194 194 - "m~n": 8 195 195 - }|};; 196 196 - val rfc_example : Jsont.json = 197 197 - {"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} 198 198 - ``` 199 199 - 200 200 - This document is carefully constructed to exercise various edge cases! 201 201 - 202 202 - ### The Root Pointer 203 203 - 204 204 - ```ocaml 205 205 - # get root rfc_example ;; 206 206 - - : Jsont.json = 207 207 - {"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} 208 208 - ``` 209 209 - 210 210 - The empty pointer (`root`) returns the whole document. 211 211 - 212 212 - ### Object Member Access 213 213 - 214 214 - ```ocaml 215 215 - # get (of_string_nav "/foo") rfc_example ;; 216 216 - - : Jsont.json = ["bar","baz"] 217 217 - ``` 218 218 - 219 219 - `/foo` accesses the member named `foo`, which is an array. 220 220 - 221 221 - ### Array Index Access 222 222 - 223 223 - ```ocaml 224 224 - # get (of_string_nav "/foo/0") rfc_example ;; 225 225 - - : Jsont.json = "bar" 226 226 - # get (of_string_nav "/foo/1") rfc_example ;; 227 227 - - : Jsont.json = "baz" 228 228 - ``` 229 229 - 230 230 - `/foo/0` first goes to `foo`, then accesses index 0 of the array. 231 231 - 232 232 - ### Empty String as Key 233 233 - 234 234 - JSON allows empty strings as object keys: 235 235 - 236 236 - ```ocaml 237 237 - # get (of_string_nav "/") rfc_example ;; 238 238 - - : Jsont.json = 0 239 239 - ``` 240 240 - 241 241 - The pointer `/` has one token: the empty string. This accesses the member 242 242 - with an empty name. 243 243 - 244 244 - ### Keys with Special Characters 245 245 - 246 246 - The RFC example includes keys with `/` and `~` characters: 247 247 - 248 248 - ```ocaml 249 249 - # get (of_string_nav "/a~1b") rfc_example ;; 250 250 - - : Jsont.json = 1 251 251 - ``` 252 252 - 253 253 - The token `a~1b` refers to the key `a/b`. We'll explain this escaping 254 254 - [below](#escaping-special-characters). 255 255 - 256 256 - ```ocaml 257 257 - # get (of_string_nav "/m~0n") rfc_example ;; 258 258 - - : Jsont.json = 8 259 259 - ``` 260 260 - 261 261 - The token `m~0n` refers to the key `m~n`. 262 262 - 263 263 - **Important**: When using the OCaml library programmatically, you don't need 264 264 - to worry about escaping. The `Mem` variant holds the literal key name: 265 265 - 266 266 - ```ocaml 267 267 - # let slash_ptr = make [mem "a/b"];; 268 268 - val slash_ptr : nav t = [Mem "a/b"] 269 269 - # to_string slash_ptr;; 270 270 - - : string = "/a~1b" 271 271 - # get slash_ptr rfc_example ;; 272 272 - - : Jsont.json = 1 273 273 - ``` 274 274 - 275 275 - The library escapes it when converting to string. 276 276 - 277 277 - ### Other Special Characters (No Escaping Needed) 278 278 - 279 279 - Most characters don't need escaping in JSON Pointer strings: 280 280 - 281 281 - ```ocaml 282 282 - # get (of_string_nav "/c%d") rfc_example ;; 283 283 - - : Jsont.json = 2 284 284 - # get (of_string_nav "/e^f") rfc_example ;; 285 285 - - : Jsont.json = 3 286 286 - # get (of_string_nav "/g|h") rfc_example ;; 287 287 - - : Jsont.json = 4 288 288 - # get (of_string_nav "/ ") rfc_example ;; 289 289 - - : Jsont.json = 7 290 290 - ``` 291 291 - 292 292 - Even a space is a valid key character! 293 293 - 294 294 - ### Error Conditions 295 295 - 296 296 - What happens when we try to access something that doesn't exist? 297 297 - 298 298 - ```ocaml 299 299 - # get_result (of_string_nav "/nonexistent") rfc_example;; 300 300 - - : (Jsont.json, Jsont.Error.t) result = 301 301 - Error JSON Pointer: member 'nonexistent' not found 302 302 - File "-": 303 303 - # find (of_string_nav "/nonexistent") rfc_example;; 304 304 - - : Jsont.json option = None 305 305 - ``` 306 306 - 307 307 - Or an out-of-bounds array index: 308 308 - 309 309 - ```ocaml 310 310 - # find (of_string_nav "/foo/99") rfc_example;; 311 311 - - : Jsont.json option = None 312 312 - ``` 313 313 - 314 314 - Or try to index into a non-container: 315 315 - 316 316 - ```ocaml 317 317 - # find (of_string_nav "/foo/0/invalid") rfc_example;; 318 318 - - : Jsont.json option = None 319 319 - ``` 320 320 - 321 321 - The library provides both exception-raising and result-returning variants: 322 322 - 323 323 - <!-- $MDX skip --> 324 324 - ```ocaml 325 325 - val get : nav t -> Jsont.json -> Jsont.json 326 326 - val get_result : nav t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result 327 327 - val find : nav t -> Jsont.json -> Jsont.json option 328 328 - ``` 329 329 - 330 330 - ### Array Index Rules 331 331 - 332 332 - RFC 6901 has specific rules for array indices. Section 4 states: 333 333 - 334 334 - > characters comprised of digits [...] that represent an unsigned base-10 335 335 - > integer value, making the new referenced value the array element with 336 336 - > the zero-based index identified by the token 337 337 - 338 338 - And importantly: 339 339 - 340 340 - > note that leading zeros are not allowed 341 341 - 342 342 - ```ocaml 343 343 - # of_string_nav "/foo/0";; 344 344 - - : nav t = [Mem "foo"; Nth 0] 345 345 - ``` 346 346 - 347 347 - Zero itself is fine. 348 348 - 349 349 - ```ocaml 350 350 - # of_string_nav "/foo/01";; 351 351 - - : nav t = [Mem "foo"; Mem "01"] 352 352 - ``` 353 353 - 354 354 - But `01` has a leading zero, so it's NOT treated as an array index - it 355 355 - becomes a member name instead. This protects against accidental octal 356 356 - interpretation. 357 357 - 358 358 - ## The End-of-Array Marker: `-` and Type Safety 359 359 - 360 360 - RFC 6901, Section 4 introduces a special token: 361 361 - 362 362 - > exactly the single character "-", making the new referenced value the 363 363 - > (nonexistent) member after the last array element. 364 364 - 365 365 - This `-` marker is unique to JSON Pointer (JSON Path has no equivalent). 366 366 - It's primarily useful for JSON Patch operations (RFC 6902) to append 367 367 - elements to arrays. 368 368 - 369 369 - ### Navigation vs Append Pointers 370 370 - 371 371 - The `jsont-pointer` library uses **phantom types** to encode the difference 372 372 - between pointers that can be used for navigation and pointers that target 373 373 - the "append position": 374 374 - 375 375 - <!-- $MDX skip --> 376 376 - ```ocaml 377 377 - type nav (* A pointer to an existing element *) 378 378 - type append (* A pointer ending with "-" (append position) *) 379 379 - type 'a t (* Pointer with phantom type parameter *) 380 380 - ``` 381 381 - 382 382 - When you parse a pointer, you get either a `nav t` or an `append t`: 383 383 - 384 384 - ```ocaml 385 385 - # of_string "/foo/0";; 386 386 - - : [ `Append of append t | `Nav of nav t ] = `Nav [Mem "foo"; Nth 0] 387 387 - # of_string "/foo/-";; 388 388 - - : [ `Append of append t | `Nav of nav t ] = `Append [Mem "foo"] /- 389 389 - ``` 390 390 - 391 391 - The `-` creates an `append` pointer. Note that in the internal 392 392 - representation, the append position is tracked separately (shown as `/-`). 393 393 - 394 394 - ### Why Phantom Types? 395 395 - 396 396 - The RFC explains that `-` refers to a *nonexistent* position: 397 397 - 398 398 - > Note that the use of the "-" character to index an array will always 399 399 - > result in such an error condition because by definition it refers to 400 400 - > a nonexistent array element. 401 401 - 402 402 - So you **cannot use `get` or `find`** with an append pointer - it makes 403 403 - no sense to retrieve a value from a position that doesn't exist! The 404 404 - library enforces this at compile time: 405 405 - 406 406 - ```ocaml 407 407 - # (* This won't compile: get requires nav t, not append t *) 408 408 - (* get (match of_string "/foo/-" with `Append p -> p | _ -> assert false) rfc_example;; *) 409 409 - ``` 410 410 - 411 411 - However, append pointers **are** valid for mutation operations like `add`: 412 412 - 413 413 - ```ocaml 414 414 - # let arr_obj = parse_json {|{"foo":["a","b"]}|};; 415 415 - val arr_obj : Jsont.json = {"foo":["a","b"]} 416 416 - # match of_string "/foo/-" with 417 417 - | `Append p -> add p arr_obj ~value:(Jsont.Json.string "c") 418 418 - | `Nav _ -> assert false ;; 419 419 - - : Jsont.json = {"foo":["a","b","c"]} 420 420 - ``` 421 421 - 422 422 - For convenience, use `of_string_nav` when you know a pointer shouldn't 423 423 - contain `-`: 424 424 - 425 425 - ```ocaml 426 426 - # of_string_nav "/foo/0";; 427 427 - - : nav t = [Mem "foo"; Nth 0] 428 428 - # of_string_nav "/foo/-";; 429 429 - Exception: 430 430 - Jsont.Error Invalid JSON Pointer: '-' not allowed in navigation pointer. 431 431 - ``` 432 432 - 433 433 - ### Creating Append Pointers Programmatically 434 434 - 435 435 - You can convert a navigation pointer to an append pointer using `at_end`: 436 436 - 437 437 - ```ocaml 438 438 - # let nav_ptr = of_string_nav "/foo";; 439 439 - val nav_ptr : nav t = [Mem "foo"] 440 440 - # let app_ptr = at_end nav_ptr;; 441 441 - val app_ptr : append t = [Mem "foo"] /- 442 442 - # to_string app_ptr;; 443 443 - - : string = "/foo/-" 444 444 - ``` 445 445 - 446 446 - ## Mutation Operations 447 447 - 448 448 - While RFC 6901 defines JSON Pointer for read-only access, RFC 6902 449 449 - (JSON Patch) uses JSON Pointer for modifications. The `jsont-pointer` 450 450 - library provides these operations. 451 451 - 452 452 - ### Which Pointer Type for Which Operation? 453 453 - 454 454 - The phantom type system enforces correct usage: 455 455 - 456 456 - | Operation | Accepts | Because | 457 457 - |-----------|---------|---------| 458 458 - | `get`, `find` | `nav t` only | Can't retrieve from non-existent position | 459 459 - | `remove` | `nav t` only | Can't remove what doesn't exist | 460 460 - | `replace` | `nav t` only | Can't replace what doesn't exist | 461 461 - | `test` | `nav t` only | Can't test non-existent position | 462 462 - | `add` | `_ t` (both) | Can add at existing position OR append | 463 463 - | `set` | `_ t` (both) | Can set existing position OR append | 464 464 - | `move`, `copy` | `from:nav t`, `path:_ t` | Source must exist, dest can be append | 465 465 - 466 466 - ### Add 467 467 - 468 468 - The `add` operation inserts a value at a location: 469 469 - 470 470 - ```ocaml 471 471 - # let obj = parse_json {|{"foo":"bar"}|};; 472 472 - val obj : Jsont.json = {"foo":"bar"} 473 473 - # add (of_string_nav "/baz") obj ~value:(Jsont.Json.string "qux") 474 474 - ;; 475 475 - - : Jsont.json = {"foo":"bar","baz":"qux"} 476 476 - ``` 477 477 - 478 478 - For arrays, `add` inserts BEFORE the specified index: 479 479 - 480 480 - ```ocaml 481 481 - # let arr_obj = parse_json {|{"foo":["a","b"]}|};; 482 482 - val arr_obj : Jsont.json = {"foo":["a","b"]} 483 483 - # add (of_string_nav "/foo/1") arr_obj ~value:(Jsont.Json.string "X") 484 484 - ;; 485 485 - - : Jsont.json = {"foo":["a","X","b"]} 486 486 - ``` 487 487 - 488 488 - This is where the `-` marker and append pointers shine - they append to the end: 489 489 - 490 490 - ```ocaml 491 491 - # match of_string "/foo/-" with 492 492 - | `Append p -> add p arr_obj ~value:(Jsont.Json.string "c") 493 493 - | `Nav _ -> assert false ;; 494 494 - - : Jsont.json = {"foo":["a","b","c"]} 495 495 - ``` 496 496 - 497 497 - Or more conveniently using `at_end`: 498 498 - 499 499 - ```ocaml 500 500 - # add (at_end (of_string_nav "/foo")) arr_obj ~value:(Jsont.Json.string "c") 501 501 - ;; 502 502 - - : Jsont.json = {"foo":["a","b","c"]} 503 503 - ``` 504 504 - 505 505 - ### Remove 506 506 - 507 507 - The `remove` operation deletes a value. It only accepts `nav t` because 508 508 - you can only remove something that exists: 509 509 - 510 510 - ```ocaml 511 511 - # let two_fields = parse_json {|{"foo":"bar","baz":"qux"}|};; 512 512 - val two_fields : Jsont.json = {"foo":"bar","baz":"qux"} 513 513 - # remove (of_string_nav "/baz") two_fields ;; 514 514 - - : Jsont.json = {"foo":"bar"} 515 515 - ``` 516 516 - 517 517 - For arrays, it removes and shifts: 518 518 - 519 519 - ```ocaml 520 520 - # let three_elem = parse_json {|{"foo":["a","b","c"]}|};; 521 521 - val three_elem : Jsont.json = {"foo":["a","b","c"]} 522 522 - # remove (of_string_nav "/foo/1") three_elem ;; 523 523 - - : Jsont.json = {"foo":["a","c"]} 524 524 - ``` 525 525 - 526 526 - ### Replace 527 527 - 528 528 - The `replace` operation updates an existing value: 529 529 - 530 530 - ```ocaml 531 531 - # replace (of_string_nav "/foo") obj ~value:(Jsont.Json.string "baz") 532 532 - ;; 533 533 - - : Jsont.json = {"foo":"baz"} 534 534 - ``` 535 535 - 536 536 - Unlike `add`, `replace` requires the target to already exist (hence `nav t`). 537 537 - Attempting to replace a nonexistent path raises an error. 538 538 - 539 539 - ### Move 540 540 - 541 541 - The `move` operation relocates a value. The source (`from`) must be a `nav t` 542 542 - (you can only move something that exists), but the destination (`path`) can 543 543 - be either: 544 544 - 545 545 - ```ocaml 546 546 - # let nested = parse_json {|{"foo":{"bar":"baz"},"qux":{}}|};; 547 547 - val nested : Jsont.json = {"foo":{"bar":"baz"},"qux":{}} 548 548 - # move ~from:(of_string_nav "/foo/bar") ~path:(of_string_nav "/qux/thud") nested 549 549 - ;; 550 550 - - : Jsont.json = {"foo":{},"qux":{"thud":"baz"}} 551 551 - ``` 552 552 - 553 553 - ### Copy 554 554 - 555 555 - The `copy` operation duplicates a value (same typing as `move`): 556 556 - 557 557 - ```ocaml 558 558 - # let to_copy = parse_json {|{"foo":{"bar":"baz"}}|};; 559 559 - val to_copy : Jsont.json = {"foo":{"bar":"baz"}} 560 560 - # copy ~from:(of_string_nav "/foo/bar") ~path:(of_string_nav "/foo/qux") to_copy 561 561 - ;; 562 562 - - : Jsont.json = {"foo":{"bar":"baz","qux":"baz"}} 563 563 - ``` 564 564 - 565 565 - ### Test 566 566 - 567 567 - The `test` operation verifies a value (useful in JSON Patch): 568 568 - 569 569 - ```ocaml 570 570 - # test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "bar");; 571 571 - - : bool = true 572 572 - # test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "wrong");; 573 573 - - : bool = false 574 574 - ``` 575 575 - 576 576 - ## Escaping Special Characters 577 577 - 578 578 - RFC 6901, Section 3 explains the escaping rules: 579 579 - 580 580 - > Because the characters '\~' (%x7E) and '/' (%x2F) have special meanings 581 581 - > in JSON Pointer, '\~' needs to be encoded as '\~0' and '/' needs to be 582 582 - > encoded as '\~1' when these characters appear in a reference token. 583 583 - 584 584 - Why these specific characters? 585 585 - - `/` separates tokens, so it must be escaped inside a token 586 586 - - `~` is the escape character itself, so it must also be escaped 587 587 - 588 588 - The escape sequences are: 589 589 - - `~0` represents `~` (tilde) 590 590 - - `~1` represents `/` (forward slash) 591 591 - 592 592 - ### The Library Handles Escaping Automatically 593 593 - 594 594 - **Important**: When using `jsont-pointer` programmatically, you rarely need 595 595 - to think about escaping. The `Mem` variant stores unescaped strings, 596 596 - and escaping happens automatically during serialization: 597 597 - 598 598 - ```ocaml 599 599 - # let p = make [mem "a/b"];; 600 600 - val p : nav t = [Mem "a/b"] 601 601 - # to_string p;; 602 602 - - : string = "/a~1b" 603 603 - # of_string_nav "/a~1b";; 604 604 - - : nav t = [Mem "a/b"] 605 605 - ``` 606 606 - 607 607 - ### Escaping in Action 608 608 - 609 609 - The `Token` module exposes the escaping functions: 610 610 - 611 611 - ```ocaml 612 612 - # Token.escape "hello";; 613 613 - - : string = "hello" 614 614 - # Token.escape "a/b";; 615 615 - - : string = "a~1b" 616 616 - # Token.escape "a~b";; 617 617 - - : string = "a~0b" 618 618 - # Token.escape "~/";; 619 619 - - : string = "~0~1" 620 620 - ``` 621 621 - 622 622 - ### Unescaping 623 623 - 624 624 - And the reverse process: 625 625 - 626 626 - ```ocaml 627 627 - # Token.unescape "a~1b";; 628 628 - - : string = "a/b" 629 629 - # Token.unescape "a~0b";; 630 630 - - : string = "a~b" 631 631 - ``` 632 632 - 633 633 - ### The Order Matters! 634 634 - 635 635 - RFC 6901, Section 4 is careful to specify the unescaping order: 636 636 - 637 637 - > Evaluation of each reference token begins by decoding any escaped 638 638 - > character sequence. This is performed by first transforming any 639 639 - > occurrence of the sequence '~1' to '/', and then transforming any 640 640 - > occurrence of the sequence '~0' to '~'. By performing the substitutions 641 641 - > in this order, an implementation avoids the error of turning '~01' first 642 642 - > into '~1' and then into '/', which would be incorrect (the string '~01' 643 643 - > correctly becomes '~1' after transformation). 644 644 - 645 645 - Let's verify this tricky case: 646 646 - 647 647 - ```ocaml 648 648 - # Token.unescape "~01";; 649 649 - - : string = "~1" 650 650 - ``` 651 651 - 652 652 - If we unescaped `~0` first, `~01` would become `~1`, which would then become 653 653 - `/`. But that's wrong! The sequence `~01` should become the literal string 654 654 - `~1` (a tilde followed by the digit one). 655 655 - 656 656 - ## URI Fragment Encoding 657 657 - 658 658 - JSON Pointers can be embedded in URIs. RFC 6901, Section 6 explains: 659 659 - 660 660 - > A JSON Pointer can be represented in a URI fragment identifier by 661 661 - > encoding it into octets using UTF-8, while percent-encoding those 662 662 - > characters not allowed by the fragment rule in RFC 3986. 663 663 - 664 664 - This adds percent-encoding on top of the `~0`/`~1` escaping: 665 665 - 666 666 - ```ocaml 667 667 - # to_uri_fragment (of_string_nav "/foo");; 668 668 - - : string = "/foo" 669 669 - # to_uri_fragment (of_string_nav "/a~1b");; 670 670 - - : string = "/a~1b" 671 671 - # to_uri_fragment (of_string_nav "/c%d");; 672 672 - - : string = "/c%25d" 673 673 - # to_uri_fragment (of_string_nav "/ ");; 674 674 - - : string = "/%20" 675 675 - ``` 676 676 - 677 677 - The `%` character must be percent-encoded as `%25` in URIs, and 678 678 - spaces become `%20`. 679 679 - 680 680 - Here's the RFC example showing the URI fragment forms: 681 681 - 682 682 - | JSON Pointer | URI Fragment | Value | 683 683 - |-------------|-------------|-------| 684 684 - | `""` | `#` | whole document | 685 685 - | `"/foo"` | `#/foo` | `["bar", "baz"]` | 686 686 - | `"/foo/0"` | `#/foo/0` | `"bar"` | 687 687 - | `"/"` | `#/` | `0` | 688 688 - | `"/a~1b"` | `#/a~1b` | `1` | 689 689 - | `"/c%d"` | `#/c%25d` | `2` | 690 690 - | `"/ "` | `#/%20` | `7` | 691 691 - | `"/m~0n"` | `#/m~0n` | `8` | 692 692 - 693 693 - ## Building Pointers Programmatically 694 694 - 695 695 - Instead of parsing strings, you can build pointers from indices: 696 696 - 697 697 - ```ocaml 698 698 - # let port_ptr = make [mem "database"; mem "port"];; 699 699 - val port_ptr : nav t = [Mem "database"; Mem "port"] 700 700 - # to_string port_ptr;; 701 701 - - : string = "/database/port" 702 702 - ``` 703 703 - 704 704 - For array access, use the `nth` helper: 705 705 - 706 706 - ```ocaml 707 707 - # let first_feature_ptr = make [mem "features"; nth 0];; 708 708 - val first_feature_ptr : nav t = [Mem "features"; Nth 0] 709 709 - # to_string first_feature_ptr;; 710 710 - - : string = "/features/0" 711 711 - ``` 712 712 - 713 713 - ### Pointer Navigation 714 714 - 715 715 - You can build pointers incrementally using the `/` operator (or `append_index`): 716 716 - 717 717 - ```ocaml 718 718 - # let db_ptr = of_string_nav "/database";; 719 719 - val db_ptr : nav t = [Mem "database"] 720 720 - # let creds_ptr = db_ptr / mem "credentials";; 721 721 - val creds_ptr : nav t = [Mem "database"; Mem "credentials"] 722 722 - # let user_ptr = creds_ptr / mem "username";; 723 723 - val user_ptr : nav t = [Mem "database"; Mem "credentials"; Mem "username"] 724 724 - # to_string user_ptr;; 725 725 - - : string = "/database/credentials/username" 726 726 - ``` 727 727 - 728 728 - Or concatenate two pointers: 729 729 - 730 730 - ```ocaml 731 731 - # let base = of_string_nav "/api/v1";; 732 732 - val base : nav t = [Mem "api"; Mem "v1"] 733 733 - # let endpoint = of_string_nav "/users/0";; 734 734 - val endpoint : nav t = [Mem "users"; Nth 0] 735 735 - # to_string (concat base endpoint);; 736 736 - - : string = "/api/v1/users/0" 737 737 - ``` 738 738 - 739 739 - ## Jsont Integration 740 740 - 741 741 - The library integrates with the `Jsont` codec system, allowing you to 742 742 - combine JSON Pointer navigation with typed decoding. This is powerful 743 743 - because you can point to a location in a JSON document and decode it 744 744 - directly to an OCaml type. 745 745 - 746 746 - ```ocaml 747 747 - # let config_json = parse_json {|{ 748 748 - "database": { 749 749 - "host": "localhost", 750 750 - "port": 5432, 751 751 - "credentials": {"username": "admin", "password": "secret"} 752 752 - }, 753 753 - "features": ["auth", "logging", "metrics"] 754 754 - }|};; 755 755 - val config_json : Jsont.json = 756 756 - {"database":{"host":"localhost","port":5432,"credentials":{"username":"admin","password":"secret"}},"features":["auth","logging","metrics"]} 757 757 - ``` 758 758 - 759 759 - ### Typed Access with `path` 760 760 - 761 761 - The `path` combinator combines pointer navigation with typed decoding: 762 762 - 763 763 - ```ocaml 764 764 - # let db_host = 765 765 - Jsont.Json.decode 766 766 - (path (of_string_nav "/database/host") Jsont.string) 767 767 - config_json 768 768 - |> Result.get_ok;; 769 769 - val db_host : string = "localhost" 770 770 - # let db_port = 771 771 - Jsont.Json.decode 772 772 - (path (of_string_nav "/database/port") Jsont.int) 773 773 - config_json 774 774 - |> Result.get_ok;; 775 775 - val db_port : int = 5432 776 776 - ``` 777 777 - 778 778 - Extract a list of strings: 779 779 - 780 780 - ```ocaml 781 781 - # let features = 782 782 - Jsont.Json.decode 783 783 - (path (of_string_nav "/features") Jsont.(list string)) 784 784 - config_json 785 785 - |> Result.get_ok;; 786 786 - val features : string list = ["auth"; "logging"; "metrics"] 787 787 - ``` 788 788 - 789 789 - ### Default Values with `~absent` 790 790 - 791 791 - Use `~absent` to provide a default when a path doesn't exist: 792 792 - 793 793 - ```ocaml 794 794 - # let timeout = 795 795 - Jsont.Json.decode 796 796 - (path ~absent:30 (of_string_nav "/database/timeout") Jsont.int) 797 797 - config_json 798 798 - |> Result.get_ok;; 799 799 - val timeout : int = 30 800 800 - ``` 801 801 - 802 802 - ### Nested Path Extraction 803 803 - 804 804 - You can extract values from deeply nested structures: 805 805 - 806 806 - ```ocaml 807 807 - # let org_json = parse_json {|{ 808 808 - "organization": { 809 809 - "owner": {"name": "Alice", "email": "alice@example.com", "age": 35}, 810 810 - "members": [{"name": "Bob", "email": "bob@example.com", "age": 28}] 811 811 - } 812 812 - }|};; 813 813 - val org_json : Jsont.json = 814 814 - {"organization":{"owner":{"name":"Alice","email":"alice@example.com","age":35},"members":[{"name":"Bob","email":"bob@example.com","age":28}]}} 815 815 - # Jsont.Json.decode 816 816 - (path (of_string_nav "/organization/owner/name") Jsont.string) 817 817 - org_json 818 818 - |> Result.get_ok;; 819 819 - - : string = "Alice" 820 820 - # Jsont.Json.decode 821 821 - (path (of_string_nav "/organization/members/0/age") Jsont.int) 822 822 - org_json 823 823 - |> Result.get_ok;; 824 824 - - : int = 28 825 825 - ``` 826 826 - 827 827 - ### Comparison: Raw vs Typed Access 828 828 - 829 829 - **Raw access** requires pattern matching: 830 830 - 831 831 - ```ocaml 832 832 - # let raw_port = 833 833 - match get (of_string_nav "/database/port") config_json with 834 834 - | Jsont.Number (f, _) -> int_of_float f 835 835 - | _ -> failwith "expected number";; 836 836 - val raw_port : int = 5432 837 837 - ``` 838 838 - 839 839 - **Typed access** is cleaner and type-safe: 840 840 - 841 841 - ```ocaml 842 842 - # let typed_port = 843 843 - Jsont.Json.decode 844 844 - (path (of_string_nav "/database/port") Jsont.int) 845 845 - config_json 846 846 - |> Result.get_ok;; 847 847 - val typed_port : int = 5432 848 848 - ``` 849 849 - 850 850 - The typed approach catches mismatches at decode time with clear errors. 851 851 - 852 852 - ## Summary 853 853 - 854 854 - JSON Pointer (RFC 6901) provides a simple but powerful way to address 855 855 - values within JSON documents: 856 856 - 857 857 - 1. **Syntax**: Pointers are strings of `/`-separated reference tokens 858 858 - 2. **Escaping**: Use `~0` for `~` and `~1` for `/` in tokens (handled automatically by the library) 859 859 - 3. **Evaluation**: Tokens navigate through objects (by key) and arrays (by index) 860 860 - 4. **URI Encoding**: Pointers can be percent-encoded for use in URIs 861 861 - 5. **Mutations**: Combined with JSON Patch (RFC 6902), pointers enable structured updates 862 862 - 6. **Type Safety**: Phantom types (`nav t` vs `append t`) prevent misuse of append pointers with retrieval operations 863 863 - 864 864 - The `jsont-pointer` library implements all of this with type-safe OCaml 865 865 - interfaces, integration with the `jsont` codec system, and proper error 866 866 - handling for malformed pointers and missing values. 867 867 - 868 868 - ### Key Points on JSON Pointer vs JSON Path 869 869 - 870 870 - - **JSON Pointer** addresses a *single* location (like a file path) 871 871 - - **JSON Path** queries for *multiple* values (like a search) 872 872 - - The `-` token is unique to JSON Pointer - it means "append position" for arrays 873 873 - - The library uses phantom types to enforce that `-` (append) pointers cannot be used with `get`/`find`

+846

doc/tutorial.mld

··· 1 1 + {0 JSON Pointer Tutorial} 2 2 + 3 3 + This tutorial introduces JSON Pointer as defined in 4 4 + {{:https://www.rfc-editor.org/rfc/rfc6901} RFC 6901}, and demonstrates 5 5 + the [jsont-pointer] OCaml library through interactive examples. 6 6 + 7 7 + {1 JSON Pointer vs JSON Path} 8 8 + 9 9 + Before diving in, it's worth understanding the difference between JSON 10 10 + Pointer and JSON Path, as they serve different purposes: 11 11 + 12 12 + {b JSON Pointer} (RFC 6901) is an {e indicator syntax} that specifies a 13 13 + {e single location} within JSON data. It always identifies at most one 14 14 + value. 15 15 + 16 16 + {b JSON Path} is a {e query syntax} that can {e search} JSON data and return 17 17 + {e multiple} values matching specified criteria. 18 18 + 19 19 + Use JSON Pointer when you need to address a single, specific location 20 20 + (like JSON Schema's [$ref]). Use JSON Path when you might need multiple 21 21 + results (like Kubernetes queries). 22 22 + 23 23 + The [jsont-pointer] library implements JSON Pointer and integrates with 24 24 + the {!Jsont.Path} type for representing navigation indices. 25 25 + 26 26 + {1 Setup} 27 27 + 28 28 + First, let's set up our environment. In the toplevel, you can load the 29 29 + library with [#require "jsont-pointer.top";;] which will automatically 30 30 + install pretty printers. 31 31 + 32 32 + {@ocaml[ 33 33 + # Jsont_pointer_top.install ();; 34 34 + - : unit = () 35 35 + # open Jsont_pointer;; 36 36 + # let parse_json s = 37 37 + match Jsont_bytesrw.decode_string Jsont.json s with 38 38 + | Ok json -> json 39 39 + | Error e -> failwith e;; 40 40 + val parse_json : string -> Jsont.json = <fun> 41 41 + ]} 42 42 + 43 43 + {1 What is JSON Pointer?} 44 44 + 45 45 + From RFC 6901, Section 1: 46 46 + 47 47 + {i JSON Pointer defines a string syntax for identifying a specific value 48 48 + within a JavaScript Object Notation (JSON) document.} 49 49 + 50 50 + In other words, JSON Pointer is an addressing scheme for locating values 51 51 + inside a JSON structure. Think of it like a filesystem path, but for JSON 52 52 + documents instead of files. 53 53 + 54 54 + For example, given this JSON document: 55 55 + 56 56 + {x@ocaml[ 57 57 + # let users_json = 58 58 + parse_json "{\"users\":[{\"name\":\"Alice\",\"age\":30},{\"name\":\"Bob\",\"age\":25}]}";; 59 59 + val users_json : Jsont.json = 60 60 + {"users":[{"name":"Alice","age":30},{"name":"Bob","age":25}]} 61 61 + ]x} 62 62 + 63 63 + The JSON Pointer [/users/0/name] refers to the string ["Alice"]: 64 64 + 65 65 + {@ocaml[ 66 66 + # let ptr = of_string_nav "/users/0/name";; 67 67 + val ptr : nav t = [Mem "users"; Nth 0; Mem "name"] 68 68 + # get ptr users_json;; 69 69 + - : Jsont.json = "Alice" 70 70 + ]} 71 71 + 72 72 + In OCaml, this is represented by the ['a Jsont_pointer.t] type - a sequence 73 73 + of navigation steps from the document root to a target value. The phantom 74 74 + type parameter ['a] encodes whether this is a navigation pointer or an 75 75 + append pointer (more on this later). 76 76 + 77 77 + {1 Syntax: Reference Tokens} 78 78 + 79 79 + RFC 6901, Section 3 defines the syntax: 80 80 + 81 81 + {i A JSON Pointer is a Unicode string containing a sequence of zero or more 82 82 + reference tokens, each prefixed by a '/' (%x2F) character.} 83 83 + 84 84 + The grammar is elegantly simple: 85 85 + 86 86 + {v 87 87 + json-pointer = *( "/" reference-token ) 88 88 + reference-token = *( unescaped / escaped ) 89 89 + v} 90 90 + 91 91 + This means: 92 92 + - The empty string [""] is a valid pointer (it refers to the whole document) 93 93 + - Every non-empty pointer starts with [/] 94 94 + - Everything between [/] characters is a "reference token" 95 95 + 96 96 + Let's see this in action: 97 97 + 98 98 + {@ocaml[ 99 99 + # of_string_nav "";; 100 100 + - : nav t = [] 101 101 + ]} 102 102 + 103 103 + The empty pointer has no reference tokens - it points to the root. 104 104 + 105 105 + {@ocaml[ 106 106 + # of_string_nav "/foo";; 107 107 + - : nav t = [Mem "foo"] 108 108 + ]} 109 109 + 110 110 + The pointer [/foo] has one token: [foo]. Since it's not a number, it's 111 111 + interpreted as an object member name ([Mem]). 112 112 + 113 113 + {@ocaml[ 114 114 + # of_string_nav "/foo/0";; 115 115 + - : nav t = [Mem "foo"; Nth 0] 116 116 + ]} 117 117 + 118 118 + Here we have two tokens: [foo] (a member name) and [0] (interpreted as 119 119 + an array index [Nth]). 120 120 + 121 121 + {@ocaml[ 122 122 + # of_string_nav "/foo/bar/baz";; 123 123 + - : nav t = [Mem "foo"; Mem "bar"; Mem "baz"] 124 124 + ]} 125 125 + 126 126 + Multiple tokens navigate deeper into nested structures. 127 127 + 128 128 + {2 The Index Type} 129 129 + 130 130 + Each reference token is represented using {!Jsont.Path.index}: 131 131 + 132 132 + {[ 133 133 + type index = Jsont.Path.index 134 134 + (* = Jsont.Path.Mem of string * Jsont.Meta.t 135 135 + | Jsont.Path.Nth of int * Jsont.Meta.t *) 136 136 + ]} 137 137 + 138 138 + The [Mem] constructor is for object member access, and [Nth] is for array 139 139 + index access. The member name is {b unescaped} - you work with the actual 140 140 + key string (like ["a/b"]) and the library handles any escaping needed 141 141 + for the JSON Pointer string representation. 142 142 + 143 143 + {2 Invalid Syntax} 144 144 + 145 145 + What happens if a pointer doesn't start with [/]? 146 146 + 147 147 + {@ocaml[ 148 148 + # of_string_nav "foo";; 149 149 + Exception: 150 150 + Jsont.Error Invalid JSON Pointer: must be empty or start with '/': foo. 151 151 + ]} 152 152 + 153 153 + The RFC is strict: non-empty pointers MUST start with [/]. 154 154 + 155 155 + For safer parsing, use [of_string_result]: 156 156 + 157 157 + {@ocaml[ 158 158 + # of_string_result "foo";; 159 159 + - : ([ `Append of append t | `Nav of nav t ], string) result = 160 160 + Error "Invalid JSON Pointer: must be empty or start with '/': foo" 161 161 + # of_string_result "/valid";; 162 162 + - : ([ `Append of append t | `Nav of nav t ], string) result = 163 163 + Ok (`Nav [Mem "valid"]) 164 164 + ]} 165 165 + 166 166 + {1 Evaluation: Navigating JSON} 167 167 + 168 168 + Now we come to the heart of JSON Pointer: evaluation. RFC 6901, Section 4 169 169 + describes how a pointer is resolved against a JSON document: 170 170 + 171 171 + {i Evaluation of a JSON Pointer begins with a reference to the root value 172 172 + of a JSON document and completes with a reference to some value within 173 173 + the document. Each reference token in the JSON Pointer is evaluated 174 174 + sequentially.} 175 175 + 176 176 + Let's use the example JSON document from RFC 6901, Section 5: 177 177 + 178 178 + {@ocaml[ 179 179 + # let rfc_example = parse_json "{\"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}";; 180 180 + val rfc_example : Jsont.json = 181 181 + {"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} 182 182 + ]} 183 183 + 184 184 + This document is carefully constructed to exercise various edge cases! 185 185 + 186 186 + {2 The Root Pointer} 187 187 + 188 188 + {@ocaml[ 189 189 + # get root rfc_example ;; 190 190 + - : Jsont.json = 191 191 + {"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} 192 192 + ]} 193 193 + 194 194 + The empty pointer ({!root}) returns the whole document. 195 195 + 196 196 + {2 Object Member Access} 197 197 + 198 198 + {@ocaml[ 199 199 + # get (of_string_nav "/foo") rfc_example ;; 200 200 + - : Jsont.json = ["bar","baz"] 201 201 + ]} 202 202 + 203 203 + [/foo] accesses the member named [foo], which is an array. 204 204 + 205 205 + {2 Array Index Access} 206 206 + 207 207 + {@ocaml[ 208 208 + # get (of_string_nav "/foo/0") rfc_example ;; 209 209 + - : Jsont.json = "bar" 210 210 + # get (of_string_nav "/foo/1") rfc_example ;; 211 211 + - : Jsont.json = "baz" 212 212 + ]} 213 213 + 214 214 + [/foo/0] first goes to [foo], then accesses index 0 of the array. 215 215 + 216 216 + {2 Empty String as Key} 217 217 + 218 218 + JSON allows empty strings as object keys: 219 219 + 220 220 + {@ocaml[ 221 221 + # get (of_string_nav "/") rfc_example ;; 222 222 + - : Jsont.json = 0 223 223 + ]} 224 224 + 225 225 + The pointer [/] has one token: the empty string. This accesses the member 226 226 + with an empty name. 227 227 + 228 228 + {2 Keys with Special Characters} 229 229 + 230 230 + The RFC example includes keys with [/] and [~] characters: 231 231 + 232 232 + {@ocaml[ 233 233 + # get (of_string_nav "/a~1b") rfc_example ;; 234 234 + - : Jsont.json = 1 235 235 + ]} 236 236 + 237 237 + The token [a~1b] refers to the key [a/b]. We'll explain this escaping 238 238 + {{:#escaping}below}. 239 239 + 240 240 + {@ocaml[ 241 241 + # get (of_string_nav "/m~0n") rfc_example ;; 242 242 + - : Jsont.json = 8 243 243 + ]} 244 244 + 245 245 + The token [m~0n] refers to the key [m~n]. 246 246 + 247 247 + {b Important}: When using the OCaml library programmatically, you don't need 248 248 + to worry about escaping. The [Mem] variant holds the literal key name: 249 249 + 250 250 + {@ocaml[ 251 251 + # let slash_ptr = make [mem "a/b"];; 252 252 + val slash_ptr : nav t = [Mem "a/b"] 253 253 + # to_string slash_ptr;; 254 254 + - : string = "/a~1b" 255 255 + # get slash_ptr rfc_example ;; 256 256 + - : Jsont.json = 1 257 257 + ]} 258 258 + 259 259 + The library escapes it when converting to string. 260 260 + 261 261 + {2 Other Special Characters (No Escaping Needed)} 262 262 + 263 263 + Most characters don't need escaping in JSON Pointer strings: 264 264 + 265 265 + {@ocaml[ 266 266 + # get (of_string_nav "/c%d") rfc_example ;; 267 267 + - : Jsont.json = 2 268 268 + # get (of_string_nav "/e^f") rfc_example ;; 269 269 + - : Jsont.json = 3 270 270 + # get (of_string_nav "/g|h") rfc_example ;; 271 271 + - : Jsont.json = 4 272 272 + # get (of_string_nav "/ ") rfc_example ;; 273 273 + - : Jsont.json = 7 274 274 + ]} 275 275 + 276 276 + Even a space is a valid key character! 277 277 + 278 278 + {2 Error Conditions} 279 279 + 280 280 + What happens when we try to access something that doesn't exist? 281 281 + 282 282 + {@ocaml[ 283 283 + # get_result (of_string_nav "/nonexistent") rfc_example;; 284 284 + - : (Jsont.json, Jsont.Error.t) result = 285 285 + Error JSON Pointer: member 'nonexistent' not found 286 286 + File "-": 287 287 + # find (of_string_nav "/nonexistent") rfc_example;; 288 288 + - : Jsont.json option = None 289 289 + ]} 290 290 + 291 291 + Or an out-of-bounds array index: 292 292 + 293 293 + {@ocaml[ 294 294 + # find (of_string_nav "/foo/99") rfc_example;; 295 295 + - : Jsont.json option = None 296 296 + ]} 297 297 + 298 298 + Or try to index into a non-container: 299 299 + 300 300 + {@ocaml[ 301 301 + # find (of_string_nav "/foo/0/invalid") rfc_example;; 302 302 + - : Jsont.json option = None 303 303 + ]} 304 304 + 305 305 + The library provides both exception-raising and result-returning variants: 306 306 + 307 307 + [ 308 308 + val get : nav t -> Jsont.json -> Jsont.json 309 309 + val get_result : nav t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result 310 310 + val find : nav t -> Jsont.json -> Jsont.json option 311 311 + ] 312 312 + 313 313 + {2 Array Index Rules} 314 314 + 315 315 + RFC 6901 has specific rules for array indices. Section 4 states: 316 316 + 317 317 + {i characters comprised of digits [...] that represent an unsigned base-10 318 318 + integer value, making the new referenced value the array element with 319 319 + the zero-based index identified by the token} 320 320 + 321 321 + And importantly: 322 322 + 323 323 + {i note that leading zeros are not allowed} 324 324 + 325 325 + {@ocaml[ 326 326 + # of_string_nav "/foo/0";; 327 327 + - : nav t = [Mem "foo"; Nth 0] 328 328 + ]} 329 329 + 330 330 + Zero itself is fine. 331 331 + 332 332 + {@ocaml[ 333 333 + # of_string_nav "/foo/01";; 334 334 + - : nav t = [Mem "foo"; Mem "01"] 335 335 + ]} 336 336 + 337 337 + But [01] has a leading zero, so it's NOT treated as an array index - it 338 338 + becomes a member name instead. This protects against accidental octal 339 339 + interpretation. 340 340 + 341 341 + {1 The End-of-Array Marker: [-] and Type Safety} 342 342 + 343 343 + RFC 6901, Section 4 introduces a special token: 344 344 + 345 345 + {i exactly the single character "-", making the new referenced value the 346 346 + (nonexistent) member after the last array element.} 347 347 + 348 348 + This [-] marker is unique to JSON Pointer (JSON Path has no equivalent). 349 349 + It's primarily useful for JSON Patch operations (RFC 6902) to append 350 350 + elements to arrays. 351 351 + 352 352 + {2 Navigation vs Append Pointers} 353 353 + 354 354 + The [jsont-pointer] library uses {b phantom types} to encode the difference 355 355 + between pointers that can be used for navigation and pointers that target 356 356 + the "append position": 357 357 + 358 358 + {[ 359 359 + type nav (* A pointer to an existing element *) 360 360 + type append (* A pointer ending with "-" (append position) *) 361 361 + type 'a t (* Pointer with phantom type parameter *) 362 362 + ]} 363 363 + 364 364 + When you parse a pointer, you get either a [nav t] or an [append t]: 365 365 + 366 366 + {@ocaml[ 367 367 + # of_string "/foo/0";; 368 368 + - : [ `Append of Jsont_pointer.append Jsont_pointer.t 369 369 + | `Nav of Jsont_pointer.nav Jsont_pointer.t ] 370 370 + = `Nav [Mem "foo"; Nth 0] 371 371 + # of_string "/foo/-";; 372 372 + - : [ `Append of Jsont_pointer.append Jsont_pointer.t 373 373 + | `Nav of Jsont_pointer.nav Jsont_pointer.t ] 374 374 + = `Append [Mem "foo"] /- 375 375 + ]} 376 376 + 377 377 + The [-] creates an [append] pointer. Note that in the internal 378 378 + representation, the append position is tracked separately (shown as [/-]). 379 379 + 380 380 + {2 Why Phantom Types?} 381 381 + 382 382 + The RFC explains that [-] refers to a {e nonexistent} position: 383 383 + 384 384 + {i Note that the use of the "-" character to index an array will always 385 385 + result in such an error condition because by definition it refers to 386 386 + a nonexistent array element.} 387 387 + 388 388 + So you {b cannot use [get] or [find]} with an append pointer - it makes 389 389 + no sense to retrieve a value from a position that doesn't exist! The 390 390 + library enforces this at compile time. 391 391 + 392 392 + However, append pointers {b are} valid for mutation operations like {!add}: 393 393 + 394 394 + {x@ocaml[ 395 395 + # let arr_obj = parse_json "{\"foo\":[\"a\",\"b\"]}";; 396 396 + val arr_obj : Jsont.json = {"foo":["a","b"]} 397 397 + # (match of_string "/foo/-" with `Append p -> add p arr_obj ~value:(Jsont.Json.string "c") | `Nav _ -> assert false);; 398 398 + - : Jsont.json = {"foo":["a","b","c"]} 399 399 + ]x} 400 400 + 401 401 + For convenience, use {!of_string_nav} when you know a pointer shouldn't 402 402 + contain [-]: 403 403 + 404 404 + {@ocaml[ 405 405 + # of_string_nav "/foo/0";; 406 406 + - : Jsont_pointer.nav Jsont_pointer.t = [Mem "foo"; Nth 0] 407 407 + # of_string_nav "/foo/-";; 408 408 + Exception: 409 409 + Jsont.Error Invalid JSON Pointer: '-' not allowed in navigation pointer. 410 410 + ]} 411 411 + 412 412 + {2 Creating Append Pointers Programmatically} 413 413 + 414 414 + You can convert a navigation pointer to an append pointer using {!at_end}: 415 415 + 416 416 + {@ocaml[ 417 417 + # let nav_ptr = of_string_nav "/foo";; 418 418 + val nav_ptr : Jsont_pointer.nav Jsont_pointer.t = [Mem "foo"] 419 419 + # let app_ptr = at_end nav_ptr;; 420 420 + val app_ptr : Jsont_pointer.append Jsont_pointer.t = [Mem "foo"] /- 421 421 + # to_string app_ptr;; 422 422 + - : string = "/foo/-" 423 423 + ]} 424 424 + 425 425 + {1 Mutation Operations} 426 426 + 427 427 + While RFC 6901 defines JSON Pointer for read-only access, RFC 6902 428 428 + (JSON Patch) uses JSON Pointer for modifications. The [jsont-pointer] 429 429 + library provides these operations. 430 430 + 431 431 + {2 Which Pointer Type for Which Operation?} 432 432 + 433 433 + The phantom type system enforces correct usage: 434 434 + 435 435 + {ul 436 436 + {- {!get}, {!find} - [nav t] only - Can't retrieve from non-existent position} 437 437 + {- {!remove} - [nav t] only - Can't remove what doesn't exist} 438 438 + {- {!replace} - [nav t] only - Can't replace what doesn't exist} 439 439 + {- {!test} - [nav t] only - Can't test non-existent position} 440 440 + {- {!add} - [_ t] (both) - Can add at existing position OR append} 441 441 + {- {!set} - [_ t] (both) - Can set existing position OR append} 442 442 + {- {!move}, {!copy} - [from:nav t], [path:_ t] - Source must exist, dest can be append} 443 443 + } 444 444 + 445 445 + {2 Add} 446 446 + 447 447 + The {!add} operation inserts a value at a location: 448 448 + 449 449 + {@ocaml[ 450 450 + # let obj = parse_json "{\"foo\":\"bar\"}";; 451 451 + val obj : Jsont.json = {"foo":"bar"} 452 452 + # add (of_string_nav "/baz") obj ~value:(Jsont.Json.string "qux") 453 453 + ;; 454 454 + - : Jsont.json = {"foo":"bar","baz":"qux"} 455 455 + ]} 456 456 + 457 457 + For arrays, {!add} inserts BEFORE the specified index: 458 458 + 459 459 + {x@ocaml[ 460 460 + # let arr_obj = parse_json "{\"foo\":[\"a\",\"b\"]}";; 461 461 + val arr_obj : Jsont.json = {"foo":["a","b"]} 462 462 + # add (of_string_nav "/foo/1") arr_obj ~value:(Jsont.Json.string "X") 463 463 + ;; 464 464 + - : Jsont.json = {"foo":["a","X","b"]} 465 465 + ]x} 466 466 + 467 467 + This is where the [-] marker and append pointers shine - they append to the end: 468 468 + 469 469 + {@ocaml[ 470 470 + # (match of_string "/foo/-" with `Append p -> add p arr_obj ~value:(Jsont.Json.string "c") | `Nav _ -> assert false);; 471 471 + - : Jsont.json = {"foo":["a","b","c"]}]}]} 472 472 + ]} 473 473 + 474 474 + Or more conveniently using {!at_end}: 475 475 + 476 476 + {@ocaml[ 477 477 + # add (at_end (of_string_nav "/foo")) arr_obj ~value:(Jsont.Json.string "c") 478 478 + ;; 479 479 + - : Jsont.json = {"foo":["a","b","c"]}]}]} 480 480 + ]} 481 481 + 482 482 + {2 Remove} 483 483 + 484 484 + The {!remove} operation deletes a value. It only accepts [nav t] because 485 485 + you can only remove something that exists: 486 486 + 487 487 + {@ocaml[ 488 488 + # let two_fields = parse_json "{\"foo\":\"bar\",\"baz\":\"qux\"}";; 489 489 + val two_fields : Jsont.json = {"foo":"bar","baz":"qux"} 490 490 + # remove (of_string_nav "/baz") two_fields ;; 491 491 + - : Jsont.json = {"foo":"bar"} 492 492 + ]} 493 493 + 494 494 + For arrays, it removes and shifts: 495 495 + 496 496 + {x@ocaml[ 497 497 + # let three_elem = parse_json "{\"foo\":[\"a\",\"b\",\"c\"]}";; 498 498 + val three_elem : Jsont.json = {"foo":["a","b","c"]} 499 499 + # remove (of_string_nav "/foo/1") three_elem ;; 500 500 + - : Jsont.json = {"foo":["a","c"]} 501 501 + ]x} 502 502 + 503 503 + {2 Replace} 504 504 + 505 505 + The {!replace} operation updates an existing value: 506 506 + 507 507 + {@ocaml[ 508 508 + # replace (of_string_nav "/foo") obj ~value:(Jsont.Json.string "baz") 509 509 + ;; 510 510 + - : Jsont.json = {"foo":"baz"} 511 511 + ]} 512 512 + 513 513 + Unlike {!add}, {!replace} requires the target to already exist (hence [nav t]). 514 514 + Attempting to replace a nonexistent path raises an error. 515 515 + 516 516 + {2 Move} 517 517 + 518 518 + The {!move} operation relocates a value. The source ([from]) must be a [nav t] 519 519 + (you can only move something that exists), but the destination ([path]) can 520 520 + be either: 521 521 + 522 522 + {@ocaml[ 523 523 + # let nested = parse_json "{\"foo\":{\"bar\":\"baz\"},\"qux\":{}}";; 524 524 + val nested : Jsont.json = {"foo":{"bar":"baz"},"qux":{}} 525 525 + # move ~from:(of_string_nav "/foo/bar") ~path:(of_string_nav "/qux/thud") nested 526 526 + ;; 527 527 + - : Jsont.json = {"foo":{},"qux":{"thud":"baz"}} 528 528 + ]} 529 529 + 530 530 + {2 Copy} 531 531 + 532 532 + The {!copy} operation duplicates a value (same typing as {!move}): 533 533 + 534 534 + {@ocaml[ 535 535 + # let to_copy = parse_json "{\"foo\":{\"bar\":\"baz\"}}";; 536 536 + val to_copy : Jsont.json = {"foo":{"bar":"baz"}} 537 537 + # copy ~from:(of_string_nav "/foo/bar") ~path:(of_string_nav "/foo/qux") to_copy 538 538 + ;; 539 539 + - : Jsont.json = {"foo":{"bar":"baz","qux":"baz"}} 540 540 + ]} 541 541 + 542 542 + {2 Test} 543 543 + 544 544 + The {!test} operation verifies a value (useful in JSON Patch): 545 545 + 546 546 + {@ocaml[ 547 547 + # test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "bar");; 548 548 + - : bool = true 549 549 + # test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "wrong");; 550 550 + - : bool = false 551 551 + ]} 552 552 + 553 553 + {1:escaping Escaping Special Characters} 554 554 + 555 555 + RFC 6901, Section 3 explains the escaping rules: 556 556 + 557 557 + {i Because the characters '~' (%x7E) and '/' (%x2F) have special meanings 558 558 + in JSON Pointer, '~' needs to be encoded as '~0' and '/' needs to be 559 559 + encoded as '~1' when these characters appear in a reference token.} 560 560 + 561 561 + Why these specific characters? 562 562 + - [/] separates tokens, so it must be escaped inside a token 563 563 + - [~] is the escape character itself, so it must also be escaped 564 564 + 565 565 + The escape sequences are: 566 566 + - [~0] represents [~] (tilde) 567 567 + - [~1] represents [/] (forward slash) 568 568 + 569 569 + {2 The Library Handles Escaping Automatically} 570 570 + 571 571 + {b Important}: When using [jsont-pointer] programmatically, you rarely need 572 572 + to think about escaping. The [Mem] variant stores unescaped strings, 573 573 + and escaping happens automatically during serialization: 574 574 + 575 575 + {@ocaml[ 576 576 + # let p = make [mem "a/b"];; 577 577 + val p : Jsont_pointer.nav Jsont_pointer.t = [Mem "a/b"] 578 578 + # to_string p;; 579 579 + - : string = "/a~1b" 580 580 + # of_string_nav "/a~1b";; 581 581 + - : Jsont_pointer.nav Jsont_pointer.t = [Mem "a/b"] 582 582 + ]} 583 583 + 584 584 + {2 Escaping in Action} 585 585 + 586 586 + The {!Token} module exposes the escaping functions: 587 587 + 588 588 + {@ocaml[ 589 589 + # Token.escape "hello";; 590 590 + - : string = "hello" 591 591 + # Token.escape "a/b";; 592 592 + - : string = "a~1b" 593 593 + # Token.escape "a~b";; 594 594 + - : string = "a~0b" 595 595 + # Token.escape "~/";; 596 596 + - : string = "~0~1" 597 597 + ]} 598 598 + 599 599 + {2 Unescaping} 600 600 + 601 601 + And the reverse process: 602 602 + 603 603 + {@ocaml[ 604 604 + # Token.unescape "a~1b";; 605 605 + - : string = "a/b" 606 606 + # Token.unescape "a~0b";; 607 607 + - : string = "a~b" 608 608 + ]} 609 609 + 610 610 + {2 The Order Matters!} 611 611 + 612 612 + RFC 6901, Section 4 is careful to specify the unescaping order: 613 613 + 614 614 + {i Evaluation of each reference token begins by decoding any escaped 615 615 + character sequence. This is performed by first transforming any 616 616 + occurrence of the sequence '~1' to '/', and then transforming any 617 617 + occurrence of the sequence '~0' to '~'. By performing the substitutions 618 618 + in this order, an implementation avoids the error of turning '~01' first 619 619 + into '~1' and then into '/', which would be incorrect (the string '~01' 620 620 + correctly becomes '~1' after transformation).} 621 621 + 622 622 + Let's verify this tricky case: 623 623 + 624 624 + {@ocaml[ 625 625 + # Token.unescape "~01";; 626 626 + - : string = "~1" 627 627 + ]} 628 628 + 629 629 + If we unescaped [~0] first, [~01] would become [~1], which would then become 630 630 + [/]. But that's wrong! The sequence [~01] should become the literal string 631 631 + [~1] (a tilde followed by the digit one). 632 632 + 633 633 + {1 URI Fragment Encoding} 634 634 + 635 635 + JSON Pointers can be embedded in URIs. RFC 6901, Section 6 explains: 636 636 + 637 637 + {i A JSON Pointer can be represented in a URI fragment identifier by 638 638 + encoding it into octets using UTF-8, while percent-encoding those 639 639 + characters not allowed by the fragment rule in RFC 3986.} 640 640 + 641 641 + This adds percent-encoding on top of the [~0]/[~1] escaping: 642 642 + 643 643 + {@ocaml[ 644 644 + # to_uri_fragment (of_string_nav "/foo");; 645 645 + - : string = "/foo" 646 646 + # to_uri_fragment (of_string_nav "/a~1b");; 647 647 + - : string = "/a~1b" 648 648 + # to_uri_fragment (of_string_nav "/c%d");; 649 649 + - : string = "/c%25d" 650 650 + # to_uri_fragment (of_string_nav "/ ");; 651 651 + - : string = "/%20" 652 652 + ]} 653 653 + 654 654 + The [%] character must be percent-encoded as [%25] in URIs, and 655 655 + spaces become [%20]. 656 656 + 657 657 + Here's the RFC example showing the URI fragment forms: 658 658 + 659 659 + {ul 660 660 + {- [""] → [#] → whole document} 661 661 + {- ["/foo"] → [#/foo] → [["bar", "baz"]]} 662 662 + {- ["/foo/0"] → [#/foo/0] → ["bar"]} 663 663 + {- ["/"] → [#/] → [0]} 664 664 + {- ["/a~1b"] → [#/a~1b] → [1]} 665 665 + {- ["/c%d"] → [#/c%25d] → [2]} 666 666 + {- ["/ "] → [#/%20] → [7]} 667 667 + {- ["/m~0n"] → [#/m~0n] → [8]} 668 668 + } 669 669 + 670 670 + {1 Building Pointers Programmatically} 671 671 + 672 672 + Instead of parsing strings, you can build pointers from indices: 673 673 + 674 674 + {@ocaml[ 675 675 + # let port_ptr = make [mem "database"; mem "port"];; 676 676 + val port_ptr : Jsont_pointer.nav Jsont_pointer.t = 677 677 + [Mem "database"; Mem "port"] 678 678 + # to_string port_ptr;; 679 679 + - : string = "/database/port" 680 680 + ]} 681 681 + 682 682 + For array access, use the {!nth} helper: 683 683 + 684 684 + {@ocaml[ 685 685 + # let first_feature_ptr = make [mem "features"; nth 0];; 686 686 + val first_feature_ptr : Jsont_pointer.nav Jsont_pointer.t = 687 687 + [Mem "features"; Nth 0] 688 688 + # to_string first_feature_ptr;; 689 689 + - : string = "/features/0" 690 690 + ]} 691 691 + 692 692 + {2 Pointer Navigation} 693 693 + 694 694 + You can build pointers incrementally using the [/] operator (or {!append_index}): 695 695 + 696 696 + {@ocaml[ 697 697 + # let db_ptr = of_string_nav "/database";; 698 698 + val db_ptr : Jsont_pointer.nav Jsont_pointer.t = [Mem "database"] 699 699 + # let creds_ptr = db_ptr / mem "credentials";; 700 700 + val creds_ptr : Jsont_pointer.nav Jsont_pointer.t = 701 701 + [Mem "database"; Mem "credentials"] 702 702 + # let user_ptr = creds_ptr / mem "username";; 703 703 + val user_ptr : Jsont_pointer.nav Jsont_pointer.t = 704 704 + [Mem "database"; Mem "credentials"; Mem "username"] 705 705 + # to_string user_ptr;; 706 706 + - : string = "/database/credentials/username" 707 707 + ]} 708 708 + 709 709 + Or concatenate two pointers: 710 710 + 711 711 + {@ocaml[ 712 712 + # let base = of_string_nav "/api/v1";; 713 713 + val base : Jsont_pointer.nav Jsont_pointer.t = [Mem "api"; Mem "v1"] 714 714 + # let endpoint = of_string_nav "/users/0";; 715 715 + val endpoint : Jsont_pointer.nav Jsont_pointer.t = [Mem "users"; Nth 0] 716 716 + # to_string (concat base endpoint);; 717 717 + - : string = "/api/v1/users/0" 718 718 + ]} 719 719 + 720 720 + {1 Jsont Integration} 721 721 + 722 722 + The library integrates with the {!Jsont} codec system, allowing you to 723 723 + combine JSON Pointer navigation with typed decoding. This is powerful 724 724 + because you can point to a location in a JSON document and decode it 725 725 + directly to an OCaml type. 726 726 + 727 727 + {x@ocaml[ 728 728 + # let config_json = parse_json "{\"database\":{\"host\":\"localhost\",\"port\":5432,\"credentials\":{\"username\":\"admin\",\"password\":\"secret\"}},\"features\":[\"auth\",\"logging\",\"metrics\"]}";; 729 729 + val config_json : Jsont.json = 730 730 + {"database":{"host":"localhost","port":5432,"credentials":{"username":"admin","password":"secret"}},"features":["auth","logging","metrics"]} 731 731 + ]x} 732 732 + 733 733 + {2 Typed Access with [path]} 734 734 + 735 735 + The {!path} combinator combines pointer navigation with typed decoding: 736 736 + 737 737 + {@ocaml[ 738 738 + # let db_host = 739 739 + Jsont.Json.decode 740 740 + (path (of_string_nav "/database/host") Jsont.string) 741 741 + config_json 742 742 + |> Result.get_ok;; 743 743 + val db_host : string = "localhost" 744 744 + # let db_port = 745 745 + Jsont.Json.decode 746 746 + (path (of_string_nav "/database/port") Jsont.int) 747 747 + config_json 748 748 + |> Result.get_ok;; 749 749 + val db_port : int = 5432 750 750 + ]} 751 751 + 752 752 + Extract a list of strings: 753 753 + 754 754 + {@ocaml[ 755 755 + # let features = 756 756 + Jsont.Json.decode 757 757 + (path (of_string_nav "/features") Jsont.(list string)) 758 758 + config_json 759 759 + |> Result.get_ok;; 760 760 + val features : string list = ["auth"; "logging"; "metrics"] 761 761 + ]} 762 762 + 763 763 + {2 Default Values with [~absent]} 764 764 + 765 765 + Use [~absent] to provide a default when a path doesn't exist: 766 766 + 767 767 + {@ocaml[ 768 768 + # let timeout = 769 769 + Jsont.Json.decode 770 770 + (path ~absent:30 (of_string_nav "/database/timeout") Jsont.int) 771 771 + config_json 772 772 + |> Result.get_ok;; 773 773 + val timeout : int = 30 774 774 + ]} 775 775 + 776 776 + {2 Nested Path Extraction} 777 777 + 778 778 + You can extract values from deeply nested structures: 779 779 + 780 780 + {x@ocaml[ 781 781 + # let org_json = parse_json "{\"organization\":{\"owner\":{\"name\":\"Alice\",\"email\":\"alice@example.com\",\"age\":35},\"members\":[{\"name\":\"Bob\",\"email\":\"bob@example.com\",\"age\":28}]}}";; 782 782 + val org_json : Jsont.json = 783 783 + {"organization":{"owner":{"name":"Alice","email":"alice@example.com","age":35},"members":[{"name":"Bob","email":"bob@example.com","age":28}]}} 784 784 + # Jsont.Json.decode 785 785 + (path (of_string_nav "/organization/owner/name") Jsont.string) 786 786 + org_json 787 787 + |> Result.get_ok;; 788 788 + - : string = "Alice" 789 789 + # Jsont.Json.decode 790 790 + (path (of_string_nav "/organization/members/0/age") Jsont.int) 791 791 + org_json 792 792 + |> Result.get_ok;; 793 793 + - : int = 28 794 794 + ]x} 795 795 + 796 796 + {2 Comparison: Raw vs Typed Access} 797 797 + 798 798 + {b Raw access} requires pattern matching: 799 799 + 800 800 + {@ocaml[ 801 801 + # let raw_port = 802 802 + match get (of_string_nav "/database/port") config_json with 803 803 + | Jsont.Number (f, _) -> int_of_float f 804 804 + | _ -> failwith "expected number";; 805 805 + val raw_port : int = 5432 806 806 + ]} 807 807 + 808 808 + {b Typed access} is cleaner and type-safe: 809 809 + 810 810 + {@ocaml[ 811 811 + # let typed_port = 812 812 + Jsont.Json.decode 813 813 + (path (of_string_nav "/database/port") Jsont.int) 814 814 + config_json 815 815 + |> Result.get_ok;; 816 816 + val typed_port : int = 5432 817 817 + ]} 818 818 + 819 819 + The typed approach catches mismatches at decode time with clear errors. 820 820 + 821 821 + {1 Summary} 822 822 + 823 823 + JSON Pointer (RFC 6901) provides a simple but powerful way to address 824 824 + values within JSON documents: 825 825 + 826 826 + {ol 827 827 + {- {b Syntax}: Pointers are strings of [/]-separated reference tokens} 828 828 + {- {b Escaping}: Use [~0] for [~] and [~1] for [/] in tokens (handled automatically by the library)} 829 829 + {- {b Evaluation}: Tokens navigate through objects (by key) and arrays (by index)} 830 830 + {- {b URI Encoding}: Pointers can be percent-encoded for use in URIs} 831 831 + {- {b Mutations}: Combined with JSON Patch (RFC 6902), pointers enable structured updates} 832 832 + {- {b Type Safety}: Phantom types ([nav t] vs [append t]) prevent misuse of append pointers with retrieval operations} 833 833 + } 834 834 + 835 835 + The [jsont-pointer] library implements all of this with type-safe OCaml 836 836 + interfaces, integration with the [jsont] codec system, and proper error 837 837 + handling for malformed pointers and missing values. 838 838 + 839 839 + {2 Key Points on JSON Pointer vs JSON Path} 840 840 + 841 841 + {ul 842 842 + {- {b JSON Pointer} addresses a {e single} location (like a file path)} 843 843 + {- {b JSON Path} queries for {e multiple} values (like a search)} 844 844 + {- The [-] token is unique to JSON Pointer - it means "append position" for arrays} 845 845 + {- The library uses phantom types to enforce that [-] (append) pointers cannot be used with [get]/[find]} 846 846 + }

+18 -9

src/top/jsont_pointer_top.ml

··· 28 28 "Jsont_pointer_top.json_printer"; 29 29 "Jsont_pointer_top.error_printer" ] 30 30 31 31 - let eval_string 32 32 - ?(print_outcome = false) ?(err_formatter = Format.err_formatter) str = 33 33 - let lexbuf = Lexing.from_string str in 34 34 - let phrase = !Toploop.parse_toplevel_phrase lexbuf in 35 35 - Toploop.execute_phrase print_outcome err_formatter phrase 31 31 + (* Suppress stderr during printer installation to avoid noise in MDX tests *) 32 32 + let null_formatter = Format.make_formatter (fun _ _ _ -> ()) (fun () -> ()) 33 33 + 34 34 + let eval_string_quiet str = 35 35 + try 36 36 + let lexbuf = Lexing.from_string str in 37 37 + let phrase = !Toploop.parse_toplevel_phrase lexbuf in 38 38 + Toploop.execute_phrase false null_formatter phrase 39 39 + with _ -> false 36 40 37 37 - let rec install_printers = function 41 41 + let rec do_install_printers = function 38 42 | [] -> true 39 43 | printer :: rest -> 40 44 let cmd = Printf.sprintf "#install_printer %s;;" printer in 41 41 - eval_string cmd && install_printers rest 45 45 + eval_string_quiet cmd && do_install_printers rest 46 46 + 47 47 + let install () = 48 48 + (* Silently ignore failures - this handles non-toplevel contexts like MDX *) 49 49 + ignore (do_install_printers printers) 42 50 51 51 + (* Only auto-install when OCAML_TOPLEVEL_NAME is set, indicating a real toplevel *) 43 52 let () = 44 44 - if not (install_printers printers) then 45 45 - Format.eprintf "Problem installing jsont-pointer printers@." 53 53 + if Sys.getenv_opt "OCAML_TOPLEVEL_NAME" <> None then 54 54 + install ()

+5

src/top/jsont_pointer_top.mli

··· 38 38 val error_printer : Format.formatter -> Jsont.Error.t -> unit 39 39 (** [error_printer] formats a {!Jsont.Error.t} as a human-readable 40 40 error message. Suitable for use with [#install_printer]. *) 41 41 + 42 42 + val install : unit -> unit 43 43 + (** [install ()] installs all printers. This is called automatically when 44 44 + the library is loaded, but can be called again if needed (e.g., in 45 45 + test environments where automatic initialization doesn't run). *)