phantom

bin/jsonpp.ml

···
   | Ok s -> s
   | Error e -> failwith e
 
+(* Helper to get indices from either nav or append pointer *)
+let indices_of_result (result : [ `Nav of Jsont_pointer.nav Jsont_pointer.t
+                                | `Append of Jsont_pointer.append Jsont_pointer.t ]) =
+  match result with
+  | `Nav p -> Jsont_pointer.indices p
+  | `Append p -> Jsont_pointer.indices p
+
+(* Helper to convert to string from either nav or append pointer *)
+let to_string_of_result (result : [ `Nav of Jsont_pointer.nav Jsont_pointer.t
+                                  | `Append of Jsont_pointer.append Jsont_pointer.t ]) =
+  match result with
+  | `Nav p -> Jsont_pointer.to_string p
+  | `Append p -> Jsont_pointer.to_string p
+
 (* Test: parse pointer and print indices *)
 let test_parse pointer_str =
   try
-    let p = Jsont_pointer.of_string pointer_str in
-    let indices = Jsont_pointer.indices p in
+    let result = Jsont_pointer.of_string pointer_str in
+    let indices = indices_of_result result in
     let index_strs = List.map (fun idx ->
       match idx with
-      | `Mem s -> Printf.sprintf "Mem:%s" s
-      | `Nth n -> Printf.sprintf "Nth:%d" n
-      | `End -> "End"
+      | Jsont.Path.Mem (s, _) -> Printf.sprintf "Mem:%s" s
+      | Jsont.Path.Nth (n, _) -> Printf.sprintf "Nth:%d" n
     ) indices in
-    Printf.printf "OK: [%s]\n" (String.concat ", " index_strs)
+    let suffix = match result with `Nav _ -> "" | `Append _ -> ", /-" in
+    Printf.printf "OK: [%s%s]\n" (String.concat ", " index_strs) suffix
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
 
 (* Test: roundtrip pointer string *)
 let test_roundtrip pointer_str =
   try
-    let p = Jsont_pointer.of_string pointer_str in
-    let s = Jsont_pointer.to_string p in
+    let result = Jsont_pointer.of_string pointer_str in
+    let s = to_string_of_result result in
     if s = pointer_str then
       Printf.printf "OK: %s\n" s
     else
···
 let test_eval json_path pointer_str =
   try
     let json = parse_json (read_file json_path) in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let result = Jsont_pointer.get p json in
     Printf.printf "OK: %s\n" (json_to_string result)
   with
···
 (* Test: URI fragment roundtrip *)
 let test_uri_fragment pointer_str =
   try
-    let p = Jsont_pointer.of_string pointer_str in
-    let frag = Jsont_pointer.to_uri_fragment p in
-    let p2 = Jsont_pointer.of_uri_fragment frag in
-    let s2 = Jsont_pointer.to_string p2 in
+    let result = Jsont_pointer.of_string pointer_str in
+    let frag = match result with
+      | `Nav p -> Jsont_pointer.to_uri_fragment p
+      | `Append p -> Jsont_pointer.to_uri_fragment p
+    in
+    let result2 = Jsont_pointer.of_uri_fragment frag in
+    let s2 = to_string_of_result result2 in
     if s2 = pointer_str then
       Printf.printf "OK: %s -> %s\n" pointer_str frag
     else
···
 let test_add json_str pointer_str value_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
     let value = parse_json value_str in
-    let result = Jsont_pointer.add p json ~value in
+    let result = match Jsont_pointer.of_string pointer_str with
+      | `Nav p -> Jsont_pointer.add p json ~value
+      | `Append p -> Jsont_pointer.add p json ~value
+    in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
···
 let test_remove json_str pointer_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let result = Jsont_pointer.remove p json in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
···
 let test_replace json_str pointer_str value_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let value = parse_json value_str in
     let result = Jsont_pointer.replace p json ~value in
     Printf.printf "%s\n" (json_to_string result)
···
 let test_move json_str from_str path_str =
   try
     let json = parse_json json_str in
-    let from = Jsont_pointer.of_string from_str in
-    let path = Jsont_pointer.of_string path_str in
-    let result = Jsont_pointer.move ~from ~path json in
+    let from = Jsont_pointer.of_string_nav from_str in
+    let result = match Jsont_pointer.of_string path_str with
+      | `Nav path -> Jsont_pointer.move ~from ~path json
+      | `Append path -> Jsont_pointer.move ~from ~path json
+    in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
···
 let test_copy json_str from_str path_str =
   try
     let json = parse_json json_str in
-    let from = Jsont_pointer.of_string from_str in
-    let path = Jsont_pointer.of_string path_str in
-    let result = Jsont_pointer.copy ~from ~path json in
+    let from = Jsont_pointer.of_string_nav from_str in
+    let result = match Jsont_pointer.of_string path_str with
+      | `Nav path -> Jsont_pointer.copy ~from ~path json
+      | `Append path -> Jsont_pointer.copy ~from ~path json
+    in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
···
 let test_test json_str pointer_str expected_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let expected = parse_json expected_str in
     let result = Jsont_pointer.test p json ~expected in
     Printf.printf "%b\n" result
···
 let test_has json_str pointer_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let result = Jsont_pointer.find p json in
     Printf.printf "%b\n" (Option.is_some result)
   with Jsont.Error e ->

doc/tutorial.md

···
 [RFC 6901](https://www.rfc-editor.org/rfc/rfc6901), and demonstrates
 the `jsont-pointer` OCaml library through interactive examples.
 
+## JSON Pointer vs JSON Path
+
+Before diving in, it's worth understanding the difference between JSON
+Pointer and JSON Path, as they serve different purposes:
+
+**JSON Pointer** (RFC 6901) is an *indicator syntax* that specifies a
+*single location* within JSON data. It always identifies at most one
+value.
+
+**JSON Path** is a *query syntax* that can *search* JSON data and return
+*multiple* values matching specified criteria.
+
+Use JSON Pointer when you need to address a single, specific location
+(like JSON Schema's `$ref`). Use JSON Path when you might need multiple
+results (like Kubernetes queries).
+
+The `jsont-pointer` library implements JSON Pointer and integrates with
+the `Jsont.Path` type for representing navigation indices.
+
 ## Setup
 
 First, let's set up our environment with helper functions:
 
 ```ocaml
 # open Jsont_pointer;;
-# #install_printer Jsont_pointer_top.printer;;
+# #install_printer Jsont_pointer_top.nav_printer;;
+# #install_printer Jsont_pointer_top.append_printer;;
 # #install_printer Jsont_pointer_top.json_printer;;
 # #install_printer Jsont_pointer_top.error_printer;;
 # let parse_json s =
···
 The JSON Pointer `/users/0/name` refers to the string `"Alice"`:
 
 ```ocaml
-# let ptr = of_string "/users/0/name";;
-val ptr : t = [`Mem "users"; `Nth 0; `Mem "name"]
+# let ptr = of_string_nav "/users/0/name";;
+val ptr : nav t = [Mem "users"; Nth 0; Mem "name"]
 # get ptr users_json;;
 - : Jsont.json = "Alice"
 ```
 
-In OCaml, this is represented by the `Jsont_pointer.t` type - a sequence
-of navigation steps from the document root to a target value.
+In OCaml, this is represented by the `'a Jsont_pointer.t` type - a sequence
+of navigation steps from the document root to a target value. The phantom
+type parameter `'a` encodes whether this is a navigation pointer or an
+append pointer (more on this later).
 
 ## Syntax: Reference Tokens
 
···
 Let's see this in action:
 
 ```ocaml
-# of_string "";;
-- : t = []
+# of_string_nav "";;
+- : nav t = []
 ```
 
 The empty pointer has no reference tokens - it points to the root.
 
 ```ocaml
-# of_string "/foo";;
-- : t = [`Mem "foo"]
+# of_string_nav "/foo";;
+- : nav t = [Mem "foo"]
 ```
 
 The pointer `/foo` has one token: `foo`. Since it's not a number, it's
 interpreted as an object member name (`Mem`).
 
 ```ocaml
-# of_string "/foo/0";;
-- : t = [`Mem "foo"; `Nth 0]
+# of_string_nav "/foo/0";;
+- : nav t = [Mem "foo"; Nth 0]
 ```
 
 Here we have two tokens: `foo` (a member name) and `0` (interpreted as
 an array index `Nth`).
 
 ```ocaml
-# of_string "/foo/bar/baz";;
-- : t = [`Mem "foo"; `Mem "bar"; `Mem "baz"]
+# of_string_nav "/foo/bar/baz";;
+- : nav t = [Mem "foo"; Mem "bar"; Mem "baz"]
 ```
 
 Multiple tokens navigate deeper into nested structures.
 
 ### The Index Type
 
-Each reference token becomes an `Index.t` value in the library:
+Each reference token is represented using `Jsont.Path.index`:
 
 <!-- $MDX skip -->
 ```ocaml
-type t = [
-  | `Mem of string   (* Object member access *)
-  | `Nth of int      (* Array index access *)
-  | `End             (* The special "-" marker for append operations *)
-]
+type index = Jsont.Path.index
+(* = Jsont.Path.Mem of string * Jsont.Meta.t
+   | Jsont.Path.Nth of int * Jsont.Meta.t *)
 ```
 
-The `Mem` variant holds the **unescaped** member name - you work with the
-actual key string (like `"a/b"`) and the library handles any escaping needed
+The `Mem` constructor is for object member access, and `Nth` is for array
+index access. The member name is **unescaped** - you work with the actual
+key string (like `"a/b"`) and the library handles any escaping needed
 for the JSON Pointer string representation.
 
 ### Invalid Syntax
···
 What happens if a pointer doesn't start with `/`?
 
 ```ocaml
-# of_string "foo";;
+# of_string_nav "foo";;
 Exception:
 Jsont.Error Invalid JSON Pointer: must be empty or start with '/': foo.
 ```
···
 
 ```ocaml
 # of_string_result "foo";;
-- : (t, string) result =
+- : ([ `Append of append t | `Nav of nav t ], string) result =
 Error "Invalid JSON Pointer: must be empty or start with '/': foo"
 # of_string_result "/valid";;
-- : (t, string) result = Ok [`Mem "valid"]
+- : ([ `Append of append t | `Nav of nav t ], string) result =
+Ok (`Nav [Mem "valid"])
 ```
 
 ## Evaluation: Navigating JSON
···
 ### Object Member Access
 
 ```ocaml
-# get (of_string "/foo") rfc_example ;;
+# get (of_string_nav "/foo") rfc_example ;;
 - : Jsont.json = ["bar","baz"]
 ```
 
···
 ### Array Index Access
 
 ```ocaml
-# get (of_string "/foo/0") rfc_example ;;
+# get (of_string_nav "/foo/0") rfc_example ;;
 - : Jsont.json = "bar"
-# get (of_string "/foo/1") rfc_example ;;
+# get (of_string_nav "/foo/1") rfc_example ;;
 - : Jsont.json = "baz"
 ```
 
···
 JSON allows empty strings as object keys:
 
 ```ocaml
-# get (of_string "/") rfc_example ;;
+# get (of_string_nav "/") rfc_example ;;
 - : Jsont.json = 0
 ```
 
···
 The RFC example includes keys with `/` and `~` characters:
 
 ```ocaml
-# get (of_string "/a~1b") rfc_example ;;
+# get (of_string_nav "/a~1b") rfc_example ;;
 - : Jsont.json = 1
 ```
 
···
 [below](#escaping-special-characters).
 
 ```ocaml
-# get (of_string "/m~0n") rfc_example ;;
+# get (of_string_nav "/m~0n") rfc_example ;;
 - : Jsont.json = 8
 ```
 
···
 to worry about escaping. The `Mem` variant holds the literal key name:
 
 ```ocaml
-# let slash_ptr = make [`Mem "a/b"];;
-val slash_ptr : t = [`Mem "a/b"]
+# let slash_ptr = make [mem "a/b"];;
+val slash_ptr : nav t = [Mem "a/b"]
 # to_string slash_ptr;;
 - : string = "/a~1b"
 # get slash_ptr rfc_example ;;
···
 Most characters don't need escaping in JSON Pointer strings:
 
 ```ocaml
-# get (of_string "/c%d") rfc_example ;;
+# get (of_string_nav "/c%d") rfc_example ;;
 - : Jsont.json = 2
-# get (of_string "/e^f") rfc_example ;;
+# get (of_string_nav "/e^f") rfc_example ;;
 - : Jsont.json = 3
-# get (of_string "/g|h") rfc_example ;;
+# get (of_string_nav "/g|h") rfc_example ;;
 - : Jsont.json = 4
-# get (of_string "/ ") rfc_example ;;
+# get (of_string_nav "/ ") rfc_example ;;
 - : Jsont.json = 7
 ```
 
···
 What happens when we try to access something that doesn't exist?
 
 ```ocaml
-# get_result (of_string "/nonexistent") rfc_example;;
+# get_result (of_string_nav "/nonexistent") rfc_example;;
 - : (Jsont.json, Jsont.Error.t) result =
 Error JSON Pointer: member 'nonexistent' not found
 File "-":
-# find (of_string "/nonexistent") rfc_example;;
+# find (of_string_nav "/nonexistent") rfc_example;;
 - : Jsont.json option = None
 ```
 
 Or an out-of-bounds array index:
 
 ```ocaml
-# find (of_string "/foo/99") rfc_example;;
+# find (of_string_nav "/foo/99") rfc_example;;
 - : Jsont.json option = None
 ```
 
 Or try to index into a non-container:
 
 ```ocaml
-# find (of_string "/foo/0/invalid") rfc_example;;
+# find (of_string_nav "/foo/0/invalid") rfc_example;;
 - : Jsont.json option = None
 ```
 
···
 
 <!-- $MDX skip -->
 ```ocaml
-val get : t -> Jsont.json -> Jsont.json
-val get_result : t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
-val find : t -> Jsont.json -> Jsont.json option
+val get : nav t -> Jsont.json -> Jsont.json
+val get_result : nav t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
+val find : nav t -> Jsont.json -> Jsont.json option
 ```
 
 ### Array Index Rules
···
 > note that leading zeros are not allowed
 
 ```ocaml
-# of_string "/foo/0";;
-- : t = [`Mem "foo"; `Nth 0]
+# of_string_nav "/foo/0";;
+- : nav t = [Mem "foo"; Nth 0]
 ```
 
 Zero itself is fine.
 
 ```ocaml
-# of_string "/foo/01";;
-- : t = [`Mem "foo"; `Mem "01"]
+# of_string_nav "/foo/01";;
+- : nav t = [Mem "foo"; Mem "01"]
 ```
 
 But `01` 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.
 
-## The End-of-Array Marker: `-`
+## The End-of-Array Marker: `-` and Type Safety
 
 RFC 6901, Section 4 introduces a special token:
 
 > exactly the single character "-", making the new referenced value the
 > (nonexistent) member after the last array element.
 
-This is primarily useful for JSON Patch operations (RFC 6902). Let's see
-how it parses:
+This `-` marker is unique to JSON Pointer (JSON Path has no equivalent).
+It's primarily useful for JSON Patch operations (RFC 6902) to append
+elements to arrays.
+
+### Navigation vs Append Pointers
 
+The `jsont-pointer` library uses **phantom types** to encode the difference
+between pointers that can be used for navigation and pointers that target
+the "append position":
+
+<!-- $MDX skip -->
 ```ocaml
-# of_string "/foo/-";;
-- : t = [`Mem "foo"; `End]
+type nav     (* A pointer to an existing element *)
+type append  (* A pointer ending with "-" (append position) *)
+type 'a t    (* Pointer with phantom type parameter *)
 ```
 
-The `-` is recognized as a special `End` index.
-
-However, you cannot evaluate a pointer containing `-` because it refers
-to a position that doesn't exist:
+When you parse a pointer, you get either a `nav t` or an `append t`:
 
 ```ocaml
-# find (of_string "/foo/-") rfc_example;;
-- : Jsont.json option = None
+# of_string "/foo/0";;
+- : [ `Append of append t | `Nav of nav t ] = `Nav [Mem "foo"; Nth 0]
+# of_string "/foo/-";;
+- : [ `Append of append t | `Nav of nav t ] = `Append [Mem "foo"] /-
 ```
 
-The RFC explains this:
+The `-` creates an `append` pointer. Note that in the internal
+representation, the append position is tracked separately (shown as `/-`).
+
+### Why Phantom Types?
+
+The RFC explains that `-` refers to a *nonexistent* position:
 
 > 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.
 
-But we'll see later that `-` is very useful for mutation operations!
+So you **cannot use `get` or `find`** with an append pointer - it makes
+no sense to retrieve a value from a position that doesn't exist! The
+library enforces this at compile time:
+
+```ocaml
+# (* This won't compile: get requires nav t, not append t *)
+  (* get (match of_string "/foo/-" with `Append p -> p | _ -> assert false) rfc_example;; *)
+```
+
+However, append pointers **are** valid for mutation operations like `add`:
+
+```ocaml
+# let arr_obj = parse_json {|{"foo":["a","b"]}|};;
+val arr_obj : Jsont.json = {"foo":["a","b"]}
+# match of_string "/foo/-" with
+  | `Append p -> add p arr_obj ~value:(Jsont.Json.string "c")
+  | `Nav _ -> assert false ;;
+- : Jsont.json = {"foo":["a","b","c"]}
+```
+
+For convenience, use `of_string_nav` when you know a pointer shouldn't
+contain `-`:
+
+```ocaml
+# of_string_nav "/foo/0";;
+- : nav t = [Mem "foo"; Nth 0]
+# of_string_nav "/foo/-";;
+Exception:
+Jsont.Error Invalid JSON Pointer: '-' not allowed in navigation pointer.
+```
+
+### Creating Append Pointers Programmatically
+
+You can convert a navigation pointer to an append pointer using `at_end`:
+
+```ocaml
+# let nav_ptr = of_string_nav "/foo";;
+val nav_ptr : nav t = [Mem "foo"]
+# let app_ptr = at_end nav_ptr;;
+val app_ptr : append t = [Mem "foo"] /-
+# to_string app_ptr;;
+- : string = "/foo/-"
+```
 
 ## Mutation Operations
 
···
 (JSON Patch) uses JSON Pointer for modifications. The `jsont-pointer`
 library provides these operations.
 
+### Which Pointer Type for Which Operation?
+
+The phantom type system enforces correct usage:
+
+| Operation | Accepts | Because |
+|-----------|---------|---------|
+| `get`, `find` | `nav t` only | Can't retrieve from non-existent position |
+| `remove` | `nav t` only | Can't remove what doesn't exist |
+| `replace` | `nav t` only | Can't replace what doesn't exist |
+| `test` | `nav t` only | Can't test non-existent position |
+| `add` | `_ t` (both) | Can add at existing position OR append |
+| `set` | `_ t` (both) | Can set existing position OR append |
+| `move`, `copy` | `from:nav t`, `path:_ t` | Source must exist, dest can be append |
+
 ### Add
 
 The `add` operation inserts a value at a location:
···
 ```ocaml
 # let obj = parse_json {|{"foo":"bar"}|};;
 val obj : Jsont.json = {"foo":"bar"}
-# add (of_string "/baz") obj ~value:(Jsont.Json.string "qux")
+# add (of_string_nav "/baz") obj ~value:(Jsont.Json.string "qux")
   ;;
 - : Jsont.json = {"foo":"bar","baz":"qux"}
 ```
···
 ```ocaml
 # let arr_obj = parse_json {|{"foo":["a","b"]}|};;
 val arr_obj : Jsont.json = {"foo":["a","b"]}
-# add (of_string "/foo/1") arr_obj ~value:(Jsont.Json.string "X")
+# add (of_string_nav "/foo/1") arr_obj ~value:(Jsont.Json.string "X")
   ;;
 - : Jsont.json = {"foo":["a","X","b"]}
 ```
 
-This is where the `-` marker shines - it appends to the end:
+This is where the `-` marker and append pointers shine - they append to the end:
 
 ```ocaml
-# add (of_string "/foo/-") arr_obj ~value:(Jsont.Json.string "c")
+# match of_string "/foo/-" with
+  | `Append p -> add p arr_obj ~value:(Jsont.Json.string "c")
+  | `Nav _ -> assert false ;;
+- : Jsont.json = {"foo":["a","b","c"]}
+```
+
+Or more conveniently using `at_end`:
+
+```ocaml
+# add (at_end (of_string_nav "/foo")) arr_obj ~value:(Jsont.Json.string "c")
   ;;
 - : Jsont.json = {"foo":["a","b","c"]}
 ```
 
 ### Remove
 
-The `remove` operation deletes a value:
+The `remove` operation deletes a value. It only accepts `nav t` because
+you can only remove something that exists:
 
 ```ocaml
 # let two_fields = parse_json {|{"foo":"bar","baz":"qux"}|};;
 val two_fields : Jsont.json = {"foo":"bar","baz":"qux"}
-# remove (of_string "/baz") two_fields ;;
+# remove (of_string_nav "/baz") two_fields ;;
 - : Jsont.json = {"foo":"bar"}
 ```
 
···
 ```ocaml
 # let three_elem = parse_json {|{"foo":["a","b","c"]}|};;
 val three_elem : Jsont.json = {"foo":["a","b","c"]}
-# remove (of_string "/foo/1") three_elem ;;
+# remove (of_string_nav "/foo/1") three_elem ;;
 - : Jsont.json = {"foo":["a","c"]}
 ```
 
···
 The `replace` operation updates an existing value:
 
 ```ocaml
-# replace (of_string "/foo") obj ~value:(Jsont.Json.string "baz")
+# replace (of_string_nav "/foo") obj ~value:(Jsont.Json.string "baz")
   ;;
 - : Jsont.json = {"foo":"baz"}
 ```
 
-Unlike `add`, `replace` requires the target to already exist.
+Unlike `add`, `replace` requires the target to already exist (hence `nav t`).
 Attempting to replace a nonexistent path raises an error.
 
 ### Move
 
-The `move` operation relocates a value:
+The `move` operation relocates a value. The source (`from`) must be a `nav t`
+(you can only move something that exists), but the destination (`path`) can
+be either:
 
 ```ocaml
 # let nested = parse_json {|{"foo":{"bar":"baz"},"qux":{}}|};;
 val nested : Jsont.json = {"foo":{"bar":"baz"},"qux":{}}
-# move ~from:(of_string "/foo/bar") ~path:(of_string "/qux/thud") nested
+# move ~from:(of_string_nav "/foo/bar") ~path:(of_string_nav "/qux/thud") nested
   ;;
 - : Jsont.json = {"foo":{},"qux":{"thud":"baz"}}
 ```
 
 ### Copy
 
-The `copy` operation duplicates a value:
+The `copy` operation duplicates a value (same typing as `move`):
 
 ```ocaml
 # let to_copy = parse_json {|{"foo":{"bar":"baz"}}|};;
 val to_copy : Jsont.json = {"foo":{"bar":"baz"}}
-# copy ~from:(of_string "/foo/bar") ~path:(of_string "/foo/qux") to_copy
+# copy ~from:(of_string_nav "/foo/bar") ~path:(of_string_nav "/foo/qux") to_copy
   ;;
 - : Jsont.json = {"foo":{"bar":"baz","qux":"baz"}}
 ```
···
 The `test` operation verifies a value (useful in JSON Patch):
 
 ```ocaml
-# test (of_string "/foo") obj ~expected:(Jsont.Json.string "bar");;
+# test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "bar");;
 - : bool = true
-# test (of_string "/foo") obj ~expected:(Jsont.Json.string "wrong");;
+# test (of_string_nav "/foo") obj ~expected:(Jsont.Json.string "wrong");;
 - : bool = false
 ```
 
···
 and escaping happens automatically during serialization:
 
 ```ocaml
-# let p = make [`Mem "a/b"];;
-val p : t = [`Mem "a/b"]
+# let p = make [mem "a/b"];;
+val p : nav t = [Mem "a/b"]
 # to_string p;;
 - : string = "/a~1b"
-# of_string "/a~1b";;
-- : t = [`Mem "a/b"]
+# of_string_nav "/a~1b";;
+- : nav t = [Mem "a/b"]
 ```
 
 ### Escaping in Action
···
 This adds percent-encoding on top of the `~0`/`~1` escaping:
 
 ```ocaml
-# to_uri_fragment (of_string "/foo");;
+# to_uri_fragment (of_string_nav "/foo");;
 - : string = "/foo"
-# to_uri_fragment (of_string "/a~1b");;
+# to_uri_fragment (of_string_nav "/a~1b");;
 - : string = "/a~1b"
-# to_uri_fragment (of_string "/c%d");;
+# to_uri_fragment (of_string_nav "/c%d");;
 - : string = "/c%25d"
-# to_uri_fragment (of_string "/ ");;
+# to_uri_fragment (of_string_nav "/ ");;
 - : string = "/%20"
 ```
 
···
 Instead of parsing strings, you can build pointers from indices:
 
 ```ocaml
-# let port_ptr = make [`Mem "database"; `Mem "port"];;
-val port_ptr : t = [`Mem "database"; `Mem "port"]
+# let port_ptr = make [mem "database"; mem "port"];;
+val port_ptr : nav t = [Mem "database"; Mem "port"]
 # to_string port_ptr;;
 - : string = "/database/port"
 ```
 
-For array access, use `Nth`:
+For array access, use the `nth` helper:
 
 ```ocaml
-# let first_feature_ptr = make [`Mem "features"; `Nth 0];;
-val first_feature_ptr : t = [`Mem "features"; `Nth 0]
+# let first_feature_ptr = make [mem "features"; nth 0];;
+val first_feature_ptr : nav t = [Mem "features"; Nth 0]
 # to_string first_feature_ptr;;
 - : string = "/features/0"
 ```
 
 ### Pointer Navigation
 
-You can build pointers incrementally using `append`:
+You can build pointers incrementally using the `/` operator (or `append_index`):
 
 ```ocaml
-# let db_ptr = of_string "/database";;
-val db_ptr : t = [`Mem "database"]
-# let creds_ptr = append db_ptr (`Mem "credentials");;
-val creds_ptr : t = [`Mem "database"; `Mem "credentials"]
-# let user_ptr = append creds_ptr (`Mem "username");;
-val user_ptr : t = [`Mem "database"; `Mem "credentials"; `Mem "username"]
+# let db_ptr = of_string_nav "/database";;
+val db_ptr : nav t = [Mem "database"]
+# let creds_ptr = db_ptr / mem "credentials";;
+val creds_ptr : nav t = [Mem "database"; Mem "credentials"]
+# let user_ptr = creds_ptr / mem "username";;
+val user_ptr : nav t = [Mem "database"; Mem "credentials"; Mem "username"]
 # to_string user_ptr;;
 - : string = "/database/credentials/username"
 ```
···
 Or concatenate two pointers:
 
 ```ocaml
-# let base = of_string "/api/v1";;
-val base : t = [`Mem "api"; `Mem "v1"]
-# let endpoint = of_string "/users/0";;
-val endpoint : t = [`Mem "users"; `Nth 0]
+# let base = of_string_nav "/api/v1";;
+val base : nav t = [Mem "api"; Mem "v1"]
+# let endpoint = of_string_nav "/users/0";;
+val endpoint : nav t = [Mem "users"; Nth 0]
 # to_string (concat base endpoint);;
 - : string = "/api/v1/users/0"
 ```
···
 ```ocaml
 # let db_host =
     Jsont.Json.decode
-      (path (of_string "/database/host") Jsont.string)
+      (path (of_string_nav "/database/host") Jsont.string)
       config_json
     |> Result.get_ok;;
 val db_host : string = "localhost"
 # let db_port =
     Jsont.Json.decode
-      (path (of_string "/database/port") Jsont.int)
+      (path (of_string_nav "/database/port") Jsont.int)
       config_json
     |> Result.get_ok;;
 val db_port : int = 5432
···
 ```ocaml
 # let features =
     Jsont.Json.decode
-      (path (of_string "/features") Jsont.(list string))
+      (path (of_string_nav "/features") Jsont.(list string))
       config_json
     |> Result.get_ok;;
 val features : string list = ["auth"; "logging"; "metrics"]
···
 ```ocaml
 # let timeout =
     Jsont.Json.decode
-      (path ~absent:30 (of_string "/database/timeout") Jsont.int)
+      (path ~absent:30 (of_string_nav "/database/timeout") Jsont.int)
       config_json
     |> Result.get_ok;;
 val timeout : int = 30
···
 val org_json : Jsont.json =
   {"organization":{"owner":{"name":"Alice","email":"[e-mail]","age":35},"members":[{"name":"Bob","email":"[e-mail]","age":28}]}}
 # Jsont.Json.decode
-    (path (of_string "/organization/owner/name") Jsont.string)
+    (path (of_string_nav "/organization/owner/name") Jsont.string)
     org_json
   |> Result.get_ok;;
 - : string = "Alice"
 # Jsont.Json.decode
-    (path (of_string "/organization/members/0/age") Jsont.int)
+    (path (of_string_nav "/organization/members/0/age") Jsont.int)
     org_json
   |> Result.get_ok;;
 - : int = 28
···
 
 ```ocaml
 # let raw_port =
-    match get (of_string "/database/port") config_json with
+    match get (of_string_nav "/database/port") config_json with
     | Jsont.Number (f, _) -> int_of_float f
     | _ -> failwith "expected number";;
 val raw_port : int = 5432
···
 ```ocaml
 # let typed_port =
     Jsont.Json.decode
-      (path (of_string "/database/port") Jsont.int)
+      (path (of_string_nav "/database/port") Jsont.int)
       config_json
     |> Result.get_ok;;
 val typed_port : int = 5432
···
 3. **Evaluation**: Tokens navigate through objects (by key) and arrays (by index)
 4. **URI Encoding**: Pointers can be percent-encoded for use in URIs
 5. **Mutations**: Combined with JSON Patch (RFC 6902), pointers enable structured updates
+6. **Type Safety**: Phantom types (`nav t` vs `append t`) prevent misuse of append pointers with retrieval operations
 
 The `jsont-pointer` library implements all of this with type-safe OCaml
 interfaces, integration with the `jsont` codec system, and proper error
 handling for malformed pointers and missing values.
+
+### Key Points on JSON Pointer vs JSON Path
+
+- **JSON Pointer** addresses a *single* location (like a file path)
+- **JSON Path** queries for *multiple* values (like a search)
+- The `-` token is unique to JSON Pointer - it means "append position" for arrays
+- The library uses phantom types to enforce that `-` (append) pointers cannot be used with `get`/`find`

src/jsont_pointer.ml

···
     else None
 end
 
-(* Index type - represents how a token is interpreted in context *)
-module Index = struct
-  type t = [ `Mem of string | `Nth of int | `End ]
-
-  let pp ppf = function
-    | `Mem s -> Format.fprintf ppf "/%s" (Token.escape s)
-    | `Nth n -> Format.fprintf ppf "/%d" n
-    | `End -> Format.fprintf ppf "/-"
+(* Index type - directly reuses Jsont.Path.index *)
+type index = Jsont.Path.index
 
-  let equal i1 i2 = match i1, i2 with
-    | `Mem s1, `Mem s2 -> String.equal s1 s2
-    | `Nth n1, `Nth n2 -> Int.equal n1 n2
-    | `End, `End -> true
-    | _ -> false
+(* Convenience constructors *)
+let mem ?(meta = Jsont.Meta.none) s : index = Jsont.Path.Mem (s, meta)
+let nth ?(meta = Jsont.Meta.none) n : index = Jsont.Path.Nth (n, meta)
 
-  let compare i1 i2 = match i1, i2 with
-    | `Mem s1, `Mem s2 -> String.compare s1 s2
-    | `Mem _, _ -> -1
-    | _, `Mem _ -> 1
-    | `Nth n1, `Nth n2 -> Int.compare n1 n2
-    | `Nth _, `End -> -1
-    | `End, `Nth _ -> 1
-    | `End, `End -> 0
+let pp_index ppf = function
+  | Jsont.Path.Mem (s, _) -> Format.fprintf ppf "/%s" (Token.escape s)
+  | Jsont.Path.Nth (n, _) -> Format.fprintf ppf "/%d" n
 
-  let of_path_index (idx : Jsont.Path.index) : t =
-    match idx with
-    | Jsont.Path.Mem (s, _meta) -> `Mem s
-    | Jsont.Path.Nth (n, _meta) -> `Nth n
+let equal_index i1 i2 = match i1, i2 with
+  | Jsont.Path.Mem (s1, _), Jsont.Path.Mem (s2, _) -> String.equal s1 s2
+  | Jsont.Path.Nth (n1, _), Jsont.Path.Nth (n2, _) -> Int.equal n1 n2
+  | _ -> false
 
-  let to_path_index (idx : t) : Jsont.Path.index option =
-    match idx with
-    | `Mem s -> Some (Jsont.Path.Mem (s, Jsont.Meta.none))
-    | `Nth n -> Some (Jsont.Path.Nth (n, Jsont.Meta.none))
-    | `End -> None
-end
+let compare_index i1 i2 = match i1, i2 with
+  | Jsont.Path.Mem (s1, _), Jsont.Path.Mem (s2, _) -> String.compare s1 s2
+  | Jsont.Path.Mem _, Jsont.Path.Nth _ -> -1
+  | Jsont.Path.Nth _, Jsont.Path.Mem _ -> 1
+  | Jsont.Path.Nth (n1, _), Jsont.Path.Nth (n2, _) -> Int.compare n1 n2
 
-(* Internal representation: raw unescaped tokens.
-   Per RFC 6901, interpretation as member name vs array index
-   depends on the JSON value type at evaluation time. *)
+(* Internal representation: raw unescaped tokens *)
 module Segment = struct
-  type t =
-    | Token of string  (* Unescaped reference token *)
-    | End              (* The "-" token for end-of-array *)
-
-  let of_escaped_string s =
-    if s = "-" then End
-    else Token (Token.unescape s)
+  type t = string  (* Unescaped reference token *)
 
-  let to_escaped_string = function
-    | Token s -> Token.escape s
-    | End -> "-"
+  let of_escaped_string s = Token.unescape s
 
-  (* Convert to Index for a given JSON value type *)
-  let to_index seg ~for_array =
-    match seg with
-    | End -> `End
-    | Token s ->
-      if for_array then
-        match Token.is_valid_array_index s with
-        | Some n -> `Nth n
-        | None -> `Mem s  (* Invalid index becomes member for error msg *)
-      else
-        `Mem s
+  let to_escaped_string s = Token.escape s
 
-  (* Convert from Index *)
   let of_index = function
-    | `End -> End
-    | `Mem s -> Token s
-    | `Nth n -> Token (string_of_int n)
+    | Jsont.Path.Mem (s, _) -> s
+    | Jsont.Path.Nth (n, _) -> string_of_int n
+
+  let to_index s : index =
+    match Token.is_valid_array_index s with
+    | Some n -> nth n
+    | None -> mem s
 end
 
-(* Pointer type - list of segments *)
-type t = Segment.t list
+(* Phantom types *)
+type nav
+type append
 
-let root = []
+(* Pointer type with phantom type parameter *)
+type _ t = {
+  segments : Segment.t list;
+  is_append : bool;  (* true if ends with "-" *)
+}
 
-let is_root p = p = []
+let root = { segments = []; is_append = false }
 
-(* Convert indices to segments *)
-let make indices = List.map Segment.of_index indices
+let is_root p = p.segments = [] && not p.is_append
 
-(* Convert segments to indices, assuming array context for numeric tokens *)
-let indices p = List.map (fun seg -> Segment.to_index seg ~for_array:true) p
+let make indices =
+  { segments = List.map Segment.of_index indices; is_append = false }
 
-let append p idx = p @ [Segment.of_index idx]
+let ( / ) p idx =
+  { segments = p.segments @ [Segment.of_index idx]; is_append = false }
 
-let concat p1 p2 = p1 @ p2
+let append_index = ( / )
 
-let parent p = match List.rev p with
+let at_end p =
+  { segments = p.segments; is_append = true }
+
+let concat p1 p2 =
+  { segments = p1.segments @ p2.segments; is_append = false }
+
+let parent p =
+  match List.rev p.segments with
   | [] -> None
-  | _ :: rest -> Some (List.rev rest)
+  | _ :: rest -> Some { segments = List.rev rest; is_append = false }
 
-let last p = match List.rev p with
+let last p =
+  match List.rev p.segments with
   | [] -> None
-  | seg :: _ -> Some (Segment.to_index seg ~for_array:true)
+  | seg :: _ -> Some (Segment.to_index seg)
+
+let indices (type a) (p : a t) = List.map Segment.to_index p.segments
 
 (* Parsing *)
 
-let of_string s =
-  if s = "" then root
+let parse_segments s =
+  if s = "" then []
   else if s.[0] <> '/' then
     Jsont.Error.msgf Jsont.Meta.none
       "Invalid JSON Pointer: must be empty or start with '/': %s" s
···
     let tokens = String.split_on_char '/' rest in
     List.map Segment.of_escaped_string tokens
 
+let of_string s : [ `Nav of nav t | `Append of append t ] =
+  let segments = parse_segments s in
+  (* Check if ends with "-" *)
+  match List.rev segments with
+  | "-" :: rest ->
+    (* Validate that "-" only appears at the end *)
+    if List.exists (( = ) "-") rest then
+      Jsont.Error.msgf Jsont.Meta.none
+        "Invalid JSON Pointer: '-' can only appear at the end";
+    `Append { segments = List.rev rest; is_append = true }
+  | _ ->
+    (* Validate no "-" anywhere *)
+    if List.exists (( = ) "-") segments then
+      Jsont.Error.msgf Jsont.Meta.none
+        "Invalid JSON Pointer: '-' can only appear at the end";
+    `Nav { segments; is_append = false }
+
+let of_string_nav s : nav t =
+  match of_string s with
+  | `Nav p -> p
+  | `Append _ ->
+    Jsont.Error.msgf Jsont.Meta.none
+      "Invalid JSON Pointer: '-' not allowed in navigation pointer"
+
 let of_string_result s =
   try Ok (of_string s)
   with Jsont.Error e -> Error (Jsont.Error.to_string e)
···
   in
   loop 0
 
-let of_uri_fragment s =
-  of_string (percent_decode s)
+let of_uri_fragment s = of_string (percent_decode s)
+
+let of_uri_fragment_nav s = of_string_nav (percent_decode s)
 
 let of_uri_fragment_result s =
   try Ok (of_uri_fragment s)
···
 
 (* Serialization *)
 
-let to_string p =
-  if p = [] then ""
-  else
-    let b = Buffer.create 64 in
-    List.iter (fun seg ->
-      Buffer.add_char b '/';
-      Buffer.add_string b (Segment.to_escaped_string seg)
-    ) p;
-    Buffer.contents b
+let to_string (type a) (p : a t) =
+  let base =
+    if p.segments = [] then ""
+    else
+      let b = Buffer.create 64 in
+      List.iter (fun seg ->
+        Buffer.add_char b '/';
+        Buffer.add_string b (Segment.to_escaped_string seg)
+      ) p.segments;
+      Buffer.contents b
+  in
+  if p.is_append then base ^ "/-" else base
 
 (* URI fragment percent-encoding *)
 let needs_percent_encoding c =
-  (* RFC 3986 fragment: unreserved / pct-encoded / sub-delims / ":" / "@" / "/" / "?" *)
-  (* unreserved = ALPHA / DIGIT / "-" / "." / "_" / "~" *)
-  (* sub-delims = "!" / "$" / "&" / "'" / "(" / ")" / "*" / "+" / "," / ";" / "=" *)
   not (
     (c >= 'A' && c <= 'Z') ||
     (c >= 'a' && c <= 'z') ||
···
   ) s;
   Buffer.contents b
 
-let to_uri_fragment p =
-  percent_encode (to_string p)
+let to_uri_fragment p = percent_encode (to_string p)
 
-let pp ppf p =
-  Format.pp_print_string ppf (to_string p)
+let pp ppf p = Format.pp_print_string ppf (to_string p)
 
-let pp_verbose ppf p =
-  let pp_index ppf = function
-    | `Mem s -> Format.fprintf ppf {|`Mem "%s"|} s
-    | `Nth n -> Format.fprintf ppf "`Nth %d" n
-    | `End -> Format.fprintf ppf "`End"
+let pp_verbose (type a) ppf (p : a t) =
+  let pp_idx ppf seg =
+    match Token.is_valid_array_index seg with
+    | Some n -> Format.fprintf ppf "Nth %d" n
+    | None -> Format.fprintf ppf {|Mem "%s"|} seg
   in
-  Format.fprintf ppf "[%a]"
-    (Format.pp_print_list ~pp_sep:(fun ppf () -> Format.fprintf ppf "; ") pp_index)
-    (indices p)
+  Format.fprintf ppf "[%a]%s"
+    (Format.pp_print_list ~pp_sep:(fun ppf () -> Format.fprintf ppf "; ") pp_idx)
+    p.segments
+    (if p.is_append then " /-" else "")
 
 (* Comparison *)
 
-let segment_equal s1 s2 = match s1, s2 with
-  | Segment.Token t1, Segment.Token t2 -> String.equal t1 t2
-  | Segment.End, Segment.End -> true
-  | _ -> false
+let equal (type a b) (p1 : a t) (p2 : b t) =
+  List.equal String.equal p1.segments p2.segments &&
+  p1.is_append = p2.is_append
 
-let segment_compare s1 s2 = match s1, s2 with
-  | Segment.Token t1, Segment.Token t2 -> String.compare t1 t2
-  | Segment.Token _, Segment.End -> -1
-  | Segment.End, Segment.Token _ -> 1
-  | Segment.End, Segment.End -> 0
-
-let equal p1 p2 =
-  List.equal segment_equal p1 p2
-
-let compare p1 p2 =
-  List.compare segment_compare p1 p2
+let compare (type a b) (p1 : a t) (p2 : b t) =
+  match List.compare String.compare p1.segments p2.segments with
+  | 0 -> Bool.compare p1.is_append p2.is_append
+  | n -> n
 
 (* Path conversion *)
 
-let segment_of_path_index (idx : Jsont.Path.index) : Segment.t =
-  match idx with
-  | Jsont.Path.Mem (s, _meta) -> Segment.Token s
-  | Jsont.Path.Nth (n, _meta) -> Segment.Token (string_of_int n)
-
-let of_path (p : Jsont.Path.t) : t =
-  List.rev_map segment_of_path_index (Jsont.Path.rev_indices p)
-
-let to_path p =
-  let rec convert acc = function
-    | [] -> Some acc
-    | Segment.End :: _ -> None
-    | Segment.Token s :: rest ->
-      (* For path conversion, we need to decide if it's a member or index.
-         We use array context for numeric tokens since Jsont.Path distinguishes. *)
-      let acc' = match Token.is_valid_array_index s with
-        | Some n -> Jsont.Path.nth ~meta:Jsont.Meta.none n acc
-        | None -> Jsont.Path.mem ~meta:Jsont.Meta.none s acc
-      in
-      convert acc' rest
-  in
-  convert Jsont.Path.root p
+let of_path (p : Jsont.Path.t) : nav t =
+  let segments = List.rev_map Segment.of_index (Jsont.Path.rev_indices p) in
+  { segments; is_append = false }
 
-let to_path_exn p =
-  match to_path p with
-  | Some path -> path
-  | None ->
-    Jsont.Error.msgf Jsont.Meta.none
-      "Cannot convert JSON Pointer with '-' index to Jsont.Path"
+let to_path (p : nav t) : Jsont.Path.t =
+  List.fold_left (fun acc seg ->
+    match Token.is_valid_array_index seg with
+    | Some n -> Jsont.Path.nth n acc
+    | None -> Jsont.Path.mem seg acc
+  ) Jsont.Path.root p.segments
 
 (* Evaluation helpers *)
 
···
   if n < 0 || n >= List.length arr then None
   else Some (List.nth arr n)
 
-(* Evaluation *)
+(* Evaluation - only for nav pointers *)
 
-let rec eval_get p json =
-  match p with
+let rec eval_get segments json =
+  match segments with
   | [] -> json
-  | Segment.End :: _ ->
-    Jsont.Error.msgf (Jsont.Json.meta json)
-      "JSON Pointer: '-' (end marker) refers to nonexistent array element"
-  | Segment.Token token :: rest ->
+  | token :: rest ->
     (match json with
      | Jsont.Object (members, _) ->
-       (* For objects, token is always a member name *)
        (match get_member token members with
         | Some (_, value) -> eval_get rest value
         | None ->
           Jsont.Error.msgf (Jsont.Json.meta json)
             "JSON Pointer: member '%s' not found" token)
      | Jsont.Array (elements, _) ->
-       (* For arrays, token must be a valid array index *)
        (match Token.is_valid_array_index token with
         | Some n ->
           (match get_nth n elements with
···
          "JSON Pointer: cannot index into %s with '%s'"
          (json_sort_string json) token)
 
-let get p json = eval_get p json
+let get (p : nav t) json = eval_get p.segments json
 
 let get_result p json =
   try Ok (get p json)
···
   Jsont.Error.msgf (Jsont.Json.meta json)
     "JSON Pointer: cannot navigate through %s" (json_sort_string json)
 
-(* Mutation: set *)
+(* Mutation: set - works with any pointer type *)
 
-let rec eval_set p value json =
-  match p with
-  | [] -> value
-  | [Segment.End] ->
+let rec eval_set_segments segments is_append value json =
+  match segments, is_append with
+  | [], false -> value
+  | [], true ->
+    (* Append to array *)
     (match json with
      | Jsont.Array (elements, meta) -> Jsont.Array (elements @ [value], meta)
      | _ ->
        Jsont.Error.msgf (Jsont.Json.meta json)
          "JSON Pointer: '-' can only be used on arrays, got %s"
          (json_sort_string json))
-  | Segment.End :: _ ->
-    Jsont.Error.msgf (Jsont.Json.meta json)
-      "JSON Pointer: '-' (end marker) refers to nonexistent array element"
-  | [Segment.Token token] ->
+  | [token], false ->
     navigate_to_child token json
       ~on_object:(fun members meta ->
         if Option.is_some (get_member token members) then
···
       ~on_other:(fun () ->
         Jsont.Error.msgf (Jsont.Json.meta json)
           "JSON Pointer: cannot set in %s" (json_sort_string json))
-  | Segment.Token token :: rest ->
+  | [token], true ->
+    (* Navigate to token, then append *)
     navigate_to_child token json
       ~on_object:(fun members meta ->
         match get_member token members with
         | Some (_, child) ->
-          Jsont.Object (set_member token (eval_set rest value child) members, meta)
+          let child' = eval_set_segments [] true value child in
+          Jsont.Object (set_member token child' members, meta)
         | None -> error_member_not_found json token)
       ~on_array:(fun elements meta n ->
         match get_nth n elements with
         | Some child ->
-          Jsont.Array (replace_at n (eval_set rest value child) elements, meta)
+          let child' = eval_set_segments [] true value child in
+          Jsont.Array (replace_at n child' elements, meta)
+        | None -> error_index_out_of_bounds json n)
+      ~on_other:(fun () -> error_cannot_navigate json)
+  | token :: rest, _ ->
+    navigate_to_child token json
+      ~on_object:(fun members meta ->
+        match get_member token members with
+        | Some (_, child) ->
+          Jsont.Object (set_member token (eval_set_segments rest is_append value child) members, meta)
+        | None -> error_member_not_found json token)
+      ~on_array:(fun elements meta n ->
+        match get_nth n elements with
+        | Some child ->
+          Jsont.Array (replace_at n (eval_set_segments rest is_append value child) elements, meta)
         | None -> error_index_out_of_bounds json n)
       ~on_other:(fun () -> error_cannot_navigate json)
 
-let set p json ~value = eval_set p value json
+let set (type a) (p : a t) json ~value =
+  eval_set_segments p.segments p.is_append value json
 
-(* Mutation: add (RFC 6902 semantics) *)
+(* Mutation: add (RFC 6902 semantics) - works with any pointer type *)
 
-let rec eval_add p value json =
-  match p with
-  | [] -> value
-  | [Segment.End] ->
+let rec eval_add_segments segments is_append value json =
+  match segments, is_append with
+  | [], false -> value
+  | [], true ->
+    (* Append to array *)
     (match json with
      | Jsont.Array (elements, meta) -> Jsont.Array (elements @ [value], meta)
      | _ ->
        Jsont.Error.msgf (Jsont.Json.meta json)
          "JSON Pointer: '-' can only be used on arrays, got %s"
          (json_sort_string json))
-  | Segment.End :: _ ->
-    Jsont.Error.msgf (Jsont.Json.meta json)
-      "JSON Pointer: '-' in non-final position"
-  | [Segment.Token token] ->
+  | [token], false ->
     navigate_to_child token json
       ~on_object:(fun members meta ->
         Jsont.Object (set_member token value members, meta))
···
       ~on_other:(fun () ->
         Jsont.Error.msgf (Jsont.Json.meta json)
           "JSON Pointer: cannot add to %s" (json_sort_string json))
-  | Segment.Token token :: rest ->
+  | [token], true ->
+    (* Navigate to token, then append *)
     navigate_to_child token json
       ~on_object:(fun members meta ->
         match get_member token members with
         | Some (_, child) ->
-          Jsont.Object (set_member token (eval_add rest value child) members, meta)
+          let child' = eval_add_segments [] true value child in
+          Jsont.Object (set_member token child' members, meta)
         | None -> error_member_not_found json token)
       ~on_array:(fun elements meta n ->
         match get_nth n elements with
         | Some child ->
-          Jsont.Array (replace_at n (eval_add rest value child) elements, meta)
+          let child' = eval_add_segments [] true value child in
+          Jsont.Array (replace_at n child' elements, meta)
+        | None -> error_index_out_of_bounds json n)
+      ~on_other:(fun () -> error_cannot_navigate json)
+  | token :: rest, _ ->
+    navigate_to_child token json
+      ~on_object:(fun members meta ->
+        match get_member token members with
+        | Some (_, child) ->
+          Jsont.Object (set_member token (eval_add_segments rest is_append value child) members, meta)
+        | None -> error_member_not_found json token)
+      ~on_array:(fun elements meta n ->
+        match get_nth n elements with
+        | Some child ->
+          Jsont.Array (replace_at n (eval_add_segments rest is_append value child) elements, meta)
         | None -> error_index_out_of_bounds json n)
       ~on_other:(fun () -> error_cannot_navigate json)
 
-let add p json ~value = eval_add p value json
+let add (type a) (p : a t) json ~value =
+  eval_add_segments p.segments p.is_append value json
 
-(* Mutation: remove *)
+(* Mutation: remove - only for nav pointers *)
 
-let rec eval_remove p json =
-  match p with
+let rec eval_remove_segments segments json =
+  match segments with
   | [] ->
     Jsont.Error.msgf Jsont.Meta.none "JSON Pointer: cannot remove root document"
-  | [Segment.End] ->
-    Jsont.Error.msgf (Jsont.Json.meta json)
-      "JSON Pointer: '-' refers to nonexistent element"
-  | Segment.End :: _ ->
-    Jsont.Error.msgf (Jsont.Json.meta json)
-      "JSON Pointer: '-' in non-final position"
-  | [Segment.Token token] ->
+  | [token] ->
     navigate_to_child token json
       ~on_object:(fun members meta ->
         if Option.is_some (get_member token members) then
···
       ~on_other:(fun () ->
         Jsont.Error.msgf (Jsont.Json.meta json)
           "JSON Pointer: cannot remove from %s" (json_sort_string json))
-  | Segment.Token token :: rest ->
+  | token :: rest ->
     navigate_to_child token json
       ~on_object:(fun members meta ->
         match get_member token members with
         | Some (_, child) ->
-          Jsont.Object (set_member token (eval_remove rest child) members, meta)
+          Jsont.Object (set_member token (eval_remove_segments rest child) members, meta)
         | None -> error_member_not_found json token)
       ~on_array:(fun elements meta n ->
         match get_nth n elements with
         | Some child ->
-          Jsont.Array (replace_at n (eval_remove rest child) elements, meta)
+          Jsont.Array (replace_at n (eval_remove_segments rest child) elements, meta)
         | None -> error_index_out_of_bounds json n)
       ~on_other:(fun () -> error_cannot_navigate json)
 
-let remove p json = eval_remove p json
+let remove (p : nav t) json = eval_remove_segments p.segments json
 
-(* Mutation: replace *)
+(* Mutation: replace - only for nav pointers *)
 
-let replace p json ~value =
-  (* Replace requires the target to exist, unlike add *)
+let replace (p : nav t) json ~value =
   let _ = get p json in (* Will raise if not found *)
-  eval_set p value json
+  eval_set_segments p.segments false value json
 
 (* Mutation: move *)
 
-let rec is_prefix_of p1 p2 =
-  match p1, p2 with
-  | [], _ -> true
-  | _, [] -> false
-  | h1 :: t1, h2 :: t2 -> segment_equal h1 h2 && is_prefix_of t1 t2
-
-let move ~from ~path json =
+let move ~(from : nav t) ~(path : _ t) json =
   (* Check for cycle: path cannot be a proper prefix of from *)
-  if is_prefix_of path from && not (equal path from) then
+  let from_segs = from.segments in
+  let path_segs = path.segments in
+  let rec is_prefix p1 p2 = match p1, p2 with
+    | [], _ -> true
+    | _, [] -> false
+    | h1 :: t1, h2 :: t2 -> String.equal h1 h2 && is_prefix t1 t2
+  in
+  if is_prefix path_segs from_segs &&
+     not (List.equal String.equal path_segs from_segs && path.is_append = false) then
     Jsont.Error.msgf Jsont.Meta.none
       "JSON Pointer: move would create cycle (path is prefix of from)";
   let value = get from json in
···
 
 (* Mutation: copy *)
 
-let copy ~from ~path json =
+let copy ~(from : nav t) ~(path : _ t) json =
   let value = get from json in
   add path json ~value
 
 (* Mutation: test *)
 
-let test p json ~expected =
+let test (p : nav t) json ~expected =
   Option.fold ~none:false ~some:(Jsont.Json.equal expected) (find p json)
 
 (* Jsont codec *)
 
-let jsont : t Jsont.t =
+let jsont : [ `Nav of nav t | `Append of append t ] Jsont.t =
   let dec _meta s = of_string s in
-  let enc p = to_string p in
+  let enc = function
+    | `Nav p -> to_string p
+    | `Append p -> to_string p
+  in
   Jsont.Base.string (Jsont.Base.map
     ~kind:"JSON Pointer"
     ~doc:"RFC 6901 JSON Pointer"
     ~dec ~enc ())
 
-let jsont_uri_fragment : t Jsont.t =
+let jsont_nav : nav t Jsont.t =
+  let dec _meta s = of_string_nav s in
+  let enc p = to_string p in
+  Jsont.Base.string (Jsont.Base.map
+    ~kind:"JSON Pointer (nav)"
+    ~doc:"RFC 6901 JSON Pointer (navigation only)"
+    ~dec ~enc ())
+
+let jsont_uri_fragment : [ `Nav of nav t | `Append of append t ] Jsont.t =
   let dec _meta s = of_uri_fragment s in
-  let enc p = to_uri_fragment p in
+  let enc = function
+    | `Nav p -> to_uri_fragment p
+    | `Append p -> to_uri_fragment p
+  in
   Jsont.Base.string (Jsont.Base.map
     ~kind:"JSON Pointer (URI fragment)"
     ~doc:"RFC 6901 JSON Pointer in URI fragment encoding"
···
 
 (* Query combinators *)
 
-let path ?absent p t =
+let path ?absent (p : nav t) t =
   let dec json =
     match find p json with
     | Some value ->
···
   Jsont.map Jsont.json ~dec ~enc:(fun _ ->
     Jsont.Error.msgf Jsont.Meta.none "path: encode not supported")
 
-let set_path ?(allow_absent = false) t p v =
+let set_path (type a) ?(allow_absent = false) t (p : a t) v =
   let encoded = match Jsont.Json.encode' t v with
     | Ok json -> json
     | Error e -> raise (Jsont.Error e)
···
   in
   Jsont.map Jsont.json ~dec ~enc:(fun j -> j)
 
-let update_path ?absent p t =
+let update_path ?absent (p : nav t) t =
   let dec json =
     let value = match find p json with
       | Some v -> v
···
   in
   Jsont.map Jsont.json ~dec ~enc:(fun j -> j)
 
-let delete_path ?(allow_absent = false) p =
+let delete_path ?(allow_absent = false) (p : nav t) =
   let dec json =
     if allow_absent then
       match find p json with

src/jsont_pointer.mli

···
     JSON Pointer parsing, serialization, and evaluation compatible with
     {!Jsont} codecs.
 
-    A JSON Pointer is a string syntax for identifying a specific value within
-    a JSON document. For example, given the JSON document:
+    {1 JSON Pointer vs JSON Path}
+
+    JSON Pointer (RFC 6901) and {!Jsont.Path} serve similar purposes but
+    have important differences:
+
+    {ul
+    {- {b JSON Pointer} is a {e string syntax} for addressing JSON values,
+       designed for use in URIs and JSON documents (like JSON Patch).
+       It uses [/] as separator and has escape sequences ([~0], [~1]).}
+    {- {b Jsont.Path} is an {e OCaml data structure} for programmatic
+       navigation, with no string representation defined.}}
+
+    A key difference is the [-] token: JSON Pointer's [-] refers to the
+    (nonexistent) element {e after} the last array element. This is used
+    for append operations in JSON Patch but is meaningless for retrieval.
+    {!Jsont.Path} has no equivalent concept.
+
+    This library uses phantom types to enforce this distinction at compile
+    time: pointers that may contain [-] ({!append} pointers) cannot be
+    passed to retrieval functions like {!get}.
+
+    {2 Example}
+
+    Given the JSON document:
     {v
     {
       "foo": ["bar", "baz"],
···
     {- ["/foo/0"] - the string ["bar"]}
     {- ["/"] - the integer [0] (empty string key)}
     {- ["/a~1b"] - the integer [1] ([~1] escapes [/])}
-    {- ["/m~0n"] - the integer [2] ([~0] escapes [~])}}
+    {- ["/m~0n"] - the integer [2] ([~0] escapes [~])}
+    {- ["/foo/-"] - nonexistent; only valid for mutations}}
 
     {1:tokens Reference Tokens}
 
···
 
 (** {1 Indices}
 
-    Indices represent individual navigation steps in a JSON Pointer.
-    For objects, this is a member name. For arrays, this is either
-    a numeric index or the special end-of-array marker [-]. *)
-module Index : sig
+    Indices are the individual navigation steps in a JSON Pointer.
+    This library reuses {!Jsont.Path.index} directly - the JSON Pointer
+    specific [-] token is handled separately via phantom types on the
+    pointer type itself. *)
 
-  type t = [
-    | `Mem of string
-    (** [`Mem name] indexes into an object member with the given [name].
-        The name is unescaped (i.e., [/] and [~] appear literally). *)
-    | `Nth of int
-    (** [`Nth n] indexes into an array at position [n] (zero-based).
-        Must be non-negative and without leading zeros in string form
-        (except for [0] itself). *)
-    | `End
-    (** [`End] represents the [-] token, indicating the position after
-        the last element of an array. This is used for append operations
-        in {!Jsont_pointer.add} and similar mutation functions.
-        Evaluating a pointer containing [`End] with {!Jsont_pointer.get}
-        will raise an error since it refers to a nonexistent element. *)
-  ]
+type index = Jsont.Path.index
+(** The type for navigation indices. This is exactly {!Jsont.Path.index}:
+    either [Jsont.Path.Mem (name, meta)] for object member access or
+    [Jsont.Path.Nth (n, meta)] for array index access. *)
 
-  val pp : Format.formatter -> t -> unit
-  (** [pp] formats an index in JSON Pointer string notation. *)
+val mem : ?meta:Jsont.Meta.t -> string -> index
+(** [mem ?meta s] is [Jsont.Path.Mem (s, meta)].
+    Convenience constructor for object member access.
+    [meta] defaults to {!Jsont.Meta.none}. *)
 
-  val equal : t -> t -> bool
-  (** [equal i1 i2] is [true] iff [i1] and [i2] are the same index. *)
+val nth : ?meta:Jsont.Meta.t -> int -> index
+(** [nth ?meta n] is [Jsont.Path.Nth (n, meta)].
+    Convenience constructor for array index access.
+    [meta] defaults to {!Jsont.Meta.none}. *)
 
-  val compare : t -> t -> int
-  (** [compare i1 i2] is a total order on indices. *)
+val pp_index : Format.formatter -> index -> unit
+(** [pp_index] formats an index in JSON Pointer string notation. *)
 
-  (** {2:jsont_conv Conversion with Jsont.Path} *)
+val equal_index : index -> index -> bool
+(** [equal_index i1 i2] is [true] iff [i1] and [i2] are the same index. *)
 
-  val of_path_index : Jsont.Path.index -> t
-  (** [of_path_index idx] converts a {!Jsont.Path.index} to an index. *)
+val compare_index : index -> index -> int
+(** [compare_index i1 i2] is a total order on indices. *)
 
-  val to_path_index : t -> Jsont.Path.index option
-  (** [to_path_index idx] converts to a {!Jsont.Path.index}.
-      Returns [None] for [`End] since it has no equivalent in
-      {!Jsont.Path}. *)
-end
+(** {1 Pointers}
 
-(** {1 Pointers} *)
+    JSON Pointers use phantom types to distinguish between:
+    {ul
+    {- {!nav} pointers that reference existing elements (safe for all operations)}
+    {- {!append} pointers that end with [-] (only valid for {!add} and {!set})}}
 
-type t
-(** The type for JSON Pointers. A pointer is a sequence of {!Index.t}
-    values representing a path from the root of a JSON document to
-    a specific value. *)
+    This ensures at compile time that you cannot accidentally try to
+    retrieve a nonexistent "end of array" position. *)
+
+type 'a t
+(** The type for JSON Pointers. The phantom type ['a] indicates whether
+    the pointer can be used for navigation ([nav]) or only for append
+    operations ([append]). *)
+
+type nav
+(** Phantom type for pointers that reference existing elements.
+    These can be used with all operations including {!get} and {!find}. *)
+
+type append
+(** Phantom type for pointers ending with [-] (the "after last element"
+    position). These can only be used with {!add} and {!set}. *)
 
-val root : t
+val root : nav t
 (** [root] is the empty pointer that references the whole document.
     In string form this is [""]. *)
 
-val is_root : t -> bool
+val is_root : _ t -> bool
 (** [is_root p] is [true] iff [p] is the {!root} pointer. *)
 
-val make : Index.t list -> t
-(** [make indices] creates a pointer from a list of indices.
+val make : index list -> nav t
+(** [make indices] creates a navigation pointer from a list of indices.
     The list is ordered from root to target (i.e., the first element
     is the first step from the root). *)
 
-val indices : t -> Index.t list
-(** [indices p] returns the indices of [p] from root to target. *)
+val ( / ) : nav t -> index -> nav t
+(** [p / idx] appends [idx] to pointer [p]. Operator form of {!append_index}. *)
+
+val append_index : nav t -> index -> nav t
+(** [append_index p idx] appends [idx] to the end of pointer [p]. *)
 
-val append : t -> Index.t -> t
-(** [append p idx] appends [idx] to the end of pointer [p]. *)
+val at_end : nav t -> append t
+(** [at_end p] creates an append pointer by adding [-] to [p].
+    The resulting pointer refers to the position after the last element
+    of the array at [p]. Only valid for use with {!add} and {!set}. *)
 
-val concat : t -> t -> t
+val concat : nav t -> nav t -> nav t
 (** [concat p1 p2] appends all indices of [p2] to [p1]. *)
 
-val parent : t -> t option
+val parent : nav t -> nav t option
 (** [parent p] returns the parent pointer of [p], or [None] if [p]
     is the {!root}. *)
 
-val last : t -> Index.t option
+val last : nav t -> index option
 (** [last p] returns the last index of [p], or [None] if [p] is
     the {!root}. *)
 
+val indices : _ t -> index list
+(** [indices p] returns the indices of [p] from root to target.
+    Note: for append pointers, this returns the indices of the path
+    portion; the [-] (append position) is not represented as an index. *)
+
 (** {2:parsing Parsing} *)
 
-val of_string : string -> t
+val of_string : string -> [ `Nav of nav t | `Append of append t ]
 (** [of_string s] parses a JSON Pointer from its string representation.
 
+    Returns [`Nav p] for pointers without [-], or [`Append p] for
+    pointers ending with [-].
+
     The string must be either empty (representing the root) or start
     with [/]. Each segment between [/] characters is unescaped as a
-    reference token. Segments that are valid non-negative integers
-    without leading zeros become [`Nth] indices; the string [-]
-    becomes [`End]; all others become [`Mem].
+    reference token.
 
     @raise Jsont.Error if [s] has invalid syntax:
     - Non-empty string not starting with [/]
     - Invalid escape sequence ([~] not followed by [0] or [1])
-    - Array index with leading zeros
-    - Array index that overflows [int] *)
+    - [-] appears in non-final position *)
+
+val of_string_nav : string -> nav t
+(** [of_string_nav s] parses a JSON Pointer that must not contain [-].
+
+    @raise Jsont.Error if [s] has invalid syntax or contains [-]. *)
 
-val of_string_result : string -> (t, string) result
+val of_string_result : string -> ([ `Nav of nav t | `Append of append t ], string) result
 (** [of_string_result s] is like {!of_string} but returns a result
     instead of raising. *)
 
-val of_uri_fragment : string -> t
+val of_uri_fragment : string -> [ `Nav of nav t | `Append of append t ]
 (** [of_uri_fragment s] parses a JSON Pointer from URI fragment form.
 
     This is like {!of_string} but first percent-decodes the string
···
 
     @raise Jsont.Error on invalid syntax or invalid percent-encoding. *)
 
-val of_uri_fragment_result : string -> (t, string) result
+val of_uri_fragment_nav : string -> nav t
+(** [of_uri_fragment_nav s] is like {!of_uri_fragment} but requires
+    the pointer to not contain [-].
+
+    @raise Jsont.Error if invalid or contains [-]. *)
+
+val of_uri_fragment_result : string -> ([ `Nav of nav t | `Append of append t ], string) result
 (** [of_uri_fragment_result s] is like {!of_uri_fragment} but returns
     a result instead of raising. *)
 
 (** {2:serializing Serializing} *)
 
-val to_string : t -> string
+val to_string : _ t -> string
 (** [to_string p] serializes [p] to its JSON Pointer string representation.
 
     Returns [""] for the root pointer, otherwise [/] followed by
-    escaped reference tokens joined by [/]. *)
+    escaped reference tokens joined by [/]. Append pointers include
+    the trailing [/-]. *)
 
-val to_uri_fragment : t -> string
+val to_uri_fragment : _ t -> string
 (** [to_uri_fragment p] serializes [p] to URI fragment form.
 
     This is like {!to_string} but additionally percent-encodes
     characters that are not allowed in URI fragments per RFC 3986.
     The leading [#] is {b not} included in the result. *)
 
-val pp : Format.formatter -> t -> unit
+val pp : Format.formatter -> _ t -> unit
 (** [pp] formats a pointer using {!to_string}. *)
 
-val pp_verbose : Format.formatter -> t -> unit
+val pp_verbose : Format.formatter -> _ t -> unit
 (** [pp_verbose] formats a pointer showing its index structure.
-    For example, [/foo/0/-] is formatted as [[`Mem "foo"; `Nth 0; `End]].
+    For example, [/foo/0] is formatted as [[Mem "foo"; Nth 0]].
+    Append pointers show [/-] at the end.
     Useful for debugging and understanding pointer structure. *)
 
 (** {2:comparison Comparison} *)
 
-val equal : t -> t -> bool
-(** [equal p1 p2] is [true] iff [p1] and [p2] have the same indices. *)
+val equal : _ t -> _ t -> bool
+(** [equal p1 p2] is [true] iff [p1] and [p2] have the same indices
+    and the same append status. *)
 
-val compare : t -> t -> int
+val compare : _ t -> _ t -> int
 (** [compare p1 p2] is a total order on pointers, comparing indices
-    lexicographically. *)
+    lexicographically. Append pointers sort after nav pointers with
+    the same prefix. *)
 
 (** {2:jsont_path Conversion with Jsont.Path} *)
 
-val of_path : Jsont.Path.t -> t
-(** [of_path p] converts a {!Jsont.Path.t} to a JSON Pointer. *)
+val of_path : Jsont.Path.t -> nav t
+(** [of_path p] converts a {!Jsont.Path.t} to a JSON Pointer.
+    Always returns a {!nav} pointer since {!Jsont.Path} has no [-] concept. *)
 
-val to_path : t -> Jsont.Path.t option
-(** [to_path p] converts to a {!Jsont.Path.t}.
-    Returns [None] if [p] contains an [`End] index. *)
-
-val to_path_exn : t -> Jsont.Path.t
-(** [to_path_exn p] is like {!to_path} but raises {!Jsont.Error}
-    if conversion fails. *)
+val to_path : nav t -> Jsont.Path.t
+(** [to_path p] converts a navigation pointer to a {!Jsont.Path.t}. *)
 
 (** {1 Evaluation}
 
     These functions evaluate a JSON Pointer against a {!Jsont.json} value
-    to retrieve the referenced value. *)
+    to retrieve the referenced value. They only accept {!nav} pointers
+    since {!append} pointers refer to nonexistent positions. *)
 
-val get : t -> Jsont.json -> Jsont.json
+val get : nav t -> Jsont.json -> Jsont.json
 (** [get p json] retrieves the value at pointer [p] in [json].
 
     @raise Jsont.Error if:
     - The pointer references a nonexistent object member
     - The pointer references an out-of-bounds array index
-    - The pointer contains [`End] (since [-] always refers
-      to a nonexistent element)
-    - An index type doesn't match the JSON value (e.g., [`Nth]
+    - An index type doesn't match the JSON value (e.g., [Nth]
       on an object) *)
 
-val get_result : t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
+val get_result : nav t -> Jsont.json -> (Jsont.json, Jsont.Error.t) result
 (** [get_result p json] is like {!get} but returns a result. *)
 
-val find : t -> Jsont.json -> Jsont.json option
+val find : nav t -> Jsont.json -> Jsont.json option
 (** [find p json] is like {!get} but returns [None] instead of
     raising when the pointer doesn't resolve to a value. *)
 
···
     operations.
 
     All mutation functions return a new JSON value with the modification
-    applied; they do not mutate the input. *)
+    applied; they do not mutate the input.
+
+    Functions that support the [-] token ({!add}, {!set}) accept any
+    pointer type ([_ t]). Functions that require an existing element
+    ({!remove}, {!replace}) only accept {!nav} pointers. *)
 
-val set : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+val set : _ t -> Jsont.json -> value:Jsont.json -> Jsont.json
 (** [set p json ~value] replaces the value at pointer [p] with [value].
 
-    For [`End] on arrays, appends [value] to the end of the array.
+    For {!append} pointers, appends [value] to the end of the array.
 
     @raise Jsont.Error if the pointer doesn't resolve to an existing
-    location (except for [`End] on arrays). *)
+    location (except for {!append} pointers on arrays). *)
 
-val add : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+val add : _ t -> Jsont.json -> value:Jsont.json -> Jsont.json
 (** [add p json ~value] adds [value] at the location specified by [p].
 
     The behavior depends on the target:
     {ul
     {- For objects: If the member exists, it is replaced. If it doesn't
        exist, a new member is added.}
-    {- For arrays with [`Nth]: Inserts [value] {e before} the
+    {- For arrays with [Nth]: Inserts [value] {e before} the
        specified index, shifting subsequent elements. The index must be
        valid (0 to length inclusive).}
-    {- For arrays with [`End]: Appends [value] to the array.}}
+    {- For {!append} pointers: Appends [value] to the array.}}
 
     @raise Jsont.Error if:
     - The parent of the target location doesn't exist
-    - An array index is out of bounds (except for [`End])
+    - An array index is out of bounds (except for {!append} pointers)
     - The parent is not an object or array *)
 
-val remove : t -> Jsont.json -> Jsont.json
+val remove : nav t -> Jsont.json -> Jsont.json
 (** [remove p json] removes the value at pointer [p].
 
     For objects, removes the member. For arrays, removes the element
···
 
     @raise Jsont.Error if:
     - [p] is the root (cannot remove the root)
-    - The pointer doesn't resolve to an existing value
-    - The pointer contains [`End] *)
+    - The pointer doesn't resolve to an existing value *)
 
-val replace : t -> Jsont.json -> value:Jsont.json -> Jsont.json
+val replace : nav t -> Jsont.json -> value:Jsont.json -> Jsont.json
 (** [replace p json ~value] replaces the value at pointer [p] with [value].
 
     Unlike {!add}, this requires the target to exist.
 
-    @raise Jsont.Error if:
-    - The pointer doesn't resolve to an existing value
-    - The pointer contains [`End] *)
+    @raise Jsont.Error if the pointer doesn't resolve to an existing value. *)
 
-val move : from:t -> path:t -> Jsont.json -> Jsont.json
+val move : from:nav t -> path:_ t -> Jsont.json -> Jsont.json
 (** [move ~from ~path json] moves the value from [from] to [path].
 
     This is equivalent to {!remove} at [from] followed by {!add}
···
 
     @raise Jsont.Error if:
     - [from] doesn't resolve to a value
-    - [path] is a proper prefix of [from] (would create a cycle)
-    - Either pointer contains [`End] *)
+    - [path] is a proper prefix of [from] (would create a cycle) *)
 
-val copy : from:t -> path:t -> Jsont.json -> Jsont.json
+val copy : from:nav t -> path:_ t -> Jsont.json -> Jsont.json
 (** [copy ~from ~path json] copies the value from [from] to [path].
 
     This is equivalent to {!get} at [from] followed by {!add}
     at [path] with the retrieved value.
 
-    @raise Jsont.Error if:
-    - [from] doesn't resolve to a value
-    - Either pointer contains [`End] *)
+    @raise Jsont.Error if [from] doesn't resolve to a value. *)
 
-val test : t -> Jsont.json -> expected:Jsont.json -> bool
+val test : nav t -> Jsont.json -> expected:Jsont.json -> bool
 (** [test p json ~expected] tests if the value at [p] equals [expected].
 
     Returns [true] if the values are equal according to {!Jsont.Json.equal},
···
     These types and functions integrate JSON Pointers with the {!Jsont}
     codec system. *)
 
-val jsont : t Jsont.t
+val jsont : [ `Nav of nav t | `Append of append t ] Jsont.t
 (** [jsont] is a {!Jsont.t} codec for JSON Pointers.
 
     On decode, parses a JSON string as a JSON Pointer using {!of_string}.
     On encode, serializes a pointer to a JSON string using {!to_string}. *)
 
-val jsont_uri_fragment : t Jsont.t
+val jsont_nav : nav t Jsont.t
+(** [jsont_nav] is a {!Jsont.t} codec for navigation JSON Pointers.
+
+    On decode, parses using {!of_string_nav} (fails on [-]).
+    On encode, serializes using {!to_string}. *)
+
+val jsont_uri_fragment : [ `Nav of nav t | `Append of append t ] Jsont.t
 (** [jsont_uri_fragment] is like {!jsont} but uses URI fragment encoding.
 
     On decode, parses using {!of_uri_fragment}.
···
     These combinators integrate with jsont's query system, allowing
     JSON Pointers to be used with jsont codecs for typed access. *)
 
-val path : ?absent:'a -> t -> 'a Jsont.t -> 'a Jsont.t
+val path : ?absent:'a -> nav t -> 'a Jsont.t -> 'a Jsont.t
 (** [path p t] decodes the value at pointer [p] using codec [t].
 
     If [absent] is provided and the pointer doesn't resolve, returns
···
 
     This is similar to {!Jsont.path} but uses JSON Pointer syntax. *)
 
-val set_path : ?allow_absent:bool -> 'a Jsont.t -> t -> 'a -> Jsont.json Jsont.t
+val set_path : ?allow_absent:bool -> 'a Jsont.t -> _ t -> 'a -> Jsont.json Jsont.t
 (** [set_path t p v] sets the value at pointer [p] to [v] encoded with [t].
 
     If [allow_absent] is [true] (default [false]), creates missing
···
 
     This is similar to {!Jsont.set_path} but uses JSON Pointer syntax. *)
 
-val update_path : ?absent:'a -> t -> 'a Jsont.t -> Jsont.json Jsont.t
+val update_path : ?absent:'a -> nav t -> 'a Jsont.t -> Jsont.json Jsont.t
 (** [update_path p t] recodes the value at pointer [p] with codec [t].
 
     This is similar to {!Jsont.update_path} but uses JSON Pointer syntax. *)
 
-val delete_path : ?allow_absent:bool -> t -> Jsont.json Jsont.t
+val delete_path : ?allow_absent:bool -> nav t -> Jsont.json Jsont.t
 (** [delete_path p] removes the value at pointer [p].
 
     If [allow_absent] is [true] (default [false]), does nothing if

test/comprehensive.t

···
   $ ./test_pointer.exe parse "/foo/bar"
   OK: [Mem:foo, Mem:bar]
   $ ./test_pointer.exe parse "/foo/-"
-  OK: [Mem:foo, End]
+  OK: [Mem:foo, /-]
   $ ./test_pointer.exe parse "/foo/1"
   OK: [Mem:foo, Nth:1]
   $ ./test_pointer.exe parse "/foo/~0"
···
   $ ./test_pointer.exe has 'null' ''
   true
 
-Has with '-' (end marker - should be false for get, points to nonexistent):
+Has with '-' (end marker - now errors because has uses of_string_nav):
   $ ./test_pointer.exe has '["foo"]' '/-'
-  false
+  ERROR: Invalid JSON Pointer: '-' not allowed in navigation pointer
   $ ./test_pointer.exe has '[]' '/-'
-  false
+  ERROR: Invalid JSON Pointer: '-' not allowed in navigation pointer

test/eval.t

···
 
 Error: end marker not allowed in get:
   $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/-"
-  ERROR: JSON Pointer: '-' (end marker) refers to nonexistent array element
-  File "-":
+  ERROR: Invalid JSON Pointer: '-' not allowed in navigation pointer
 
 Error: navigating through primitive (string):
   $ ./test_pointer.exe eval data/rfc6901_example.json "/foo/0/0"

test/parse.t

···
 
 End-of-array marker:
   $ ./test_pointer.exe parse "/-"
-  OK: [End]
+  OK: [, /-]
   $ ./test_pointer.exe parse "/foo/-"
-  OK: [Mem:foo, End]
+  OK: [Mem:foo, /-]
 
 Multiple levels:
   $ ./test_pointer.exe parse "/a/b/c"

test/test_pointer.ml

···
   | Ok s -> s
   | Error e -> failwith e
 
+(* Helper to get indices from either nav or append pointer *)
+let indices_of_result (result : [ `Nav of Jsont_pointer.nav Jsont_pointer.t
+                                | `Append of Jsont_pointer.append Jsont_pointer.t ]) =
+  match result with
+  | `Nav p -> Jsont_pointer.indices p
+  | `Append p -> Jsont_pointer.indices p
+
+(* Helper to convert to string from either nav or append pointer *)
+let to_string_of_result (result : [ `Nav of Jsont_pointer.nav Jsont_pointer.t
+                                  | `Append of Jsont_pointer.append Jsont_pointer.t ]) =
+  match result with
+  | `Nav p -> Jsont_pointer.to_string p
+  | `Append p -> Jsont_pointer.to_string p
+
 (* Test: parse pointer and print indices *)
 let test_parse pointer_str =
   try
-    let p = Jsont_pointer.of_string pointer_str in
-    let indices = Jsont_pointer.indices p in
+    let result = Jsont_pointer.of_string pointer_str in
+    let indices = indices_of_result result in
     let index_strs = List.map (fun idx ->
       match idx with
-      | `Mem s -> Printf.sprintf "Mem:%s" s
-      | `Nth n -> Printf.sprintf "Nth:%d" n
-      | `End -> "End"
+      | Jsont.Path.Mem (s, _) -> Printf.sprintf "Mem:%s" s
+      | Jsont.Path.Nth (n, _) -> Printf.sprintf "Nth:%d" n
     ) indices in
-    Printf.printf "OK: [%s]\n" (String.concat ", " index_strs)
+    let suffix = match result with `Nav _ -> "" | `Append _ -> ", /-" in
+    Printf.printf "OK: [%s%s]\n" (String.concat ", " index_strs) suffix
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
 
 (* Test: roundtrip pointer string *)
 let test_roundtrip pointer_str =
   try
-    let p = Jsont_pointer.of_string pointer_str in
-    let s = Jsont_pointer.to_string p in
+    let result = Jsont_pointer.of_string pointer_str in
+    let s = to_string_of_result result in
     if s = pointer_str then
       Printf.printf "OK: %s\n" s
     else
···
 let test_eval json_path pointer_str =
   try
     let json = parse_json (read_file json_path) in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let result = Jsont_pointer.get p json in
     Printf.printf "OK: %s\n" (json_to_string result)
   with
···
 (* Test: URI fragment roundtrip *)
 let test_uri_fragment pointer_str =
   try
-    let p = Jsont_pointer.of_string pointer_str in
-    let frag = Jsont_pointer.to_uri_fragment p in
-    let p2 = Jsont_pointer.of_uri_fragment frag in
-    let s2 = Jsont_pointer.to_string p2 in
+    let result = Jsont_pointer.of_string pointer_str in
+    let frag = match result with
+      | `Nav p -> Jsont_pointer.to_uri_fragment p
+      | `Append p -> Jsont_pointer.to_uri_fragment p
+    in
+    let result2 = Jsont_pointer.of_uri_fragment frag in
+    let s2 = to_string_of_result result2 in
     if s2 = pointer_str then
       Printf.printf "OK: %s -> %s\n" pointer_str frag
     else
···
 let test_add json_str pointer_str value_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
     let value = parse_json value_str in
-    let result = Jsont_pointer.add p json ~value in
+    let result = match Jsont_pointer.of_string pointer_str with
+      | `Nav p -> Jsont_pointer.add p json ~value
+      | `Append p -> Jsont_pointer.add p json ~value
+    in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
···
 let test_remove json_str pointer_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let result = Jsont_pointer.remove p json in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
···
 let test_replace json_str pointer_str value_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let value = parse_json value_str in
     let result = Jsont_pointer.replace p json ~value in
     Printf.printf "%s\n" (json_to_string result)
···
 let test_move json_str from_str path_str =
   try
     let json = parse_json json_str in
-    let from = Jsont_pointer.of_string from_str in
-    let path = Jsont_pointer.of_string path_str in
-    let result = Jsont_pointer.move ~from ~path json in
+    let from = Jsont_pointer.of_string_nav from_str in
+    let result = match Jsont_pointer.of_string path_str with
+      | `Nav path -> Jsont_pointer.move ~from ~path json
+      | `Append path -> Jsont_pointer.move ~from ~path json
+    in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
···
 let test_copy json_str from_str path_str =
   try
     let json = parse_json json_str in
-    let from = Jsont_pointer.of_string from_str in
-    let path = Jsont_pointer.of_string path_str in
-    let result = Jsont_pointer.copy ~from ~path json in
+    let from = Jsont_pointer.of_string_nav from_str in
+    let result = match Jsont_pointer.of_string path_str with
+      | `Nav path -> Jsont_pointer.copy ~from ~path json
+      | `Append path -> Jsont_pointer.copy ~from ~path json
+    in
     Printf.printf "%s\n" (json_to_string result)
   with Jsont.Error e ->
     Printf.printf "ERROR: %s\n" (Jsont.Error.to_string e)
···
 let test_test json_str pointer_str expected_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let expected = parse_json expected_str in
     let result = Jsont_pointer.test p json ~expected in
     Printf.printf "%b\n" result
···
 let test_has json_str pointer_str =
   try
     let json = parse_json json_str in
-    let p = Jsont_pointer.of_string pointer_str in
+    let p = Jsont_pointer.of_string_nav pointer_str in
     let result = Jsont_pointer.find p json in
     Printf.printf "%b\n" (Option.is_some result)
   with Jsont.Error e ->