diff --git a/CHANGELOG.md b/CHANGELOG.md
index f9686e3..42bcffe 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -5,29 +5,52 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-
 ## [Unreleased]
 
 ### Added
 
--   Adds method `into_buf` for `Box<Pointer>` and `impl From<PathBuf> for Box<Pointer>`. 
+-   Adds method `into_buf` for `Box<Pointer>` and `impl From<PathBuf> for Box<Pointer>`.
 -   Adds unsafe associated methods `Pointer::new_unchecked` and `PointerBuf::new_unchecked` for
     external zero-cost construction.
 -   Adds `Pointer::starts_with` and `Pointer::ends_with` for prefix and suffix matching.
 -   Adds new `ParseIndexError` variant to express the presence non-digit characters in the token.
 -   Adds `Token::is_next` for checking if a token represents the `-` character.
+-   Adds `InvalidEncoding` to represent the two possible encoding errors when decoding a token.
+-   Adds `diagnotic::Diagnostic` trait to facilitate error reporting and
+    `miette` integration. All errors intended for usage with `assign::Assign` or
+    `resolve::Resolve` must implement this trait.
+-   Adds `diagnostic::Report<T>` to capture the input for `PointerBuf::parse`
+    and to facilitate `miette` integration for all errors.
+-   Adds `"miette"` feature flag to enable `miette` integration for error reporting.
 
 ### Changed
 
--   Changed signature of `PathBuf::parse` to avoid requiring allocation.
--   Bumps minimum Rust version to 1.79.
 -   `Pointer::get` now accepts ranges and can produce `Pointer` segments as output (similar to
     `slice::get`).
+-   Bumps minimum Rust version to 1.79.
+-   `PointerBuf::parse` now returns `RichParseError`, an alias to
+    `Report<ParseError>` which contains the allocated string as well as the
+    error. Use `Report::original` for matches or `Report::
+-   Renames `ParseError::NoLeadingBackslash` to `ParseError::NoLeadingSlash`
+    (sorry for the churn, I spaced hard - @chanced).
+-   Adds field `position` to variants of `resolve::Error` and `assign::Error` to indicate the
+    token index of where the error occurred.
+-   Renames `ParseError::is_no_leading_backslash` to `ParseError::is_no_leading_slash`.
+-   Renames `assign::AssignError` to `assign::Error`
+-   Renames `resolve::ResolveError` to `resolve::Error`
+-   Renames `InvalidEncodingError` to `EncodingError`
 
 ### Fixed
 
 -   Make validation of array indices conform to RFC 6901 in the presence of non-digit characters.
 
+### Deprecated
+
+-   `ParseError::is_no_leading_backslash` renamed to `ParseError::is_no_leading_slash`.
+-   `assign::AssignError` renamed to `assign::Error`
+-   `resolve::ResolveError` renamed to `resolve::Error`
+-   `InvalidEncodingError` renamed to `EncodingError`
+
 ## [0.6.2] 2024-09-30
 
 ### Added
diff --git a/Cargo.lock b/Cargo.lock
index dd2668a..b85f907 100644
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -2,26 +2,71 @@
 # It is not intended for manual editing.
 version = 3
 
+[[package]]
+name = "addr2line"
+version = "0.24.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dfbe277e56a376000877090da837660b4427aad530e3028d44e0bffe4f89a1c1"
+dependencies = [
+ "gimli",
+]
+
+[[package]]
+name = "adler2"
+version = "2.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "512761e0bb2578dd7380c6baaa0f4ce03e84f95e960231d1dec8bf4d7d6e2627"
+
 [[package]]
 name = "aho-corasick"
-version = "0.7.6"
+version = "1.1.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "58fb5e95d83b38284460a5fda7d6470aa0b8844d283a0b614b8535e880800d2d"
+checksum = "8e60d3430d3a69478ad0993f19238d2df97c507009a52b3c10addcd7f6bcb916"
 dependencies = [
  "memchr",
 ]
 
+[[package]]
+name = "backtrace"
+version = "0.3.74"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8d82cb332cdfaed17ae235a638438ac4d4839913cc2af585c3c6746e8f8bee1a"
+dependencies = [
+ "addr2line",
+ "cfg-if",
+ "libc",
+ "miniz_oxide",
+ "object",
+ "rustc-demangle",
+ "windows-targets",
+]
+
+[[package]]
+name = "backtrace-ext"
+version = "0.2.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "537beee3be4a18fb023b570f80e3ae28003db9167a751266b259926e25539d50"
+dependencies = [
+ "backtrace",
+]
+
+[[package]]
+name = "bitflags"
+version = "2.6.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b048fb63fd8b5923fc5aa7b340d8e156aec7ec02f0c78fa8a6ddc2613f6f71de"
+
 [[package]]
 name = "cfg-if"
-version = "0.1.2"
+version = "1.0.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d4c819a1287eb618df47cc647173c5c4c66ba19d888a6e50d605672aed3140de"
+checksum = "baf1de4339761588bc0619e3cbc0120ee582ebb74b53b4efbf79117bd2da40fd"
 
 [[package]]
 name = "env_logger"
-version = "0.8.2"
+version = "0.8.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f26ecb66b4bdca6c1409b40fb255eefc2bd4f6d135dab3c3124f80ffa2a9661e"
+checksum = "a19187fea3ac7e84da7dacf48de0c45d63c6a76f9490dae389aead16c243fce3"
 dependencies = [
  "log",
  "regex",
@@ -29,47 +74,70 @@ dependencies = [
 
 [[package]]
 name = "equivalent"
-version = "1.0.0"
+version = "1.0.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "88bffebc5d80432c9b140ee17875ff173a8ab62faad5b257da912bd2f6c1c0a1"
+checksum = "5443807d6dff69373d433ab9ef5378ad8df50ca6298caf15de6e52e24aaf54d5"
+
+[[package]]
+name = "errno"
+version = "0.3.9"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "534c5cf6194dfab3db3242765c03bbe257cf92f22b38f6bc0c58d59108a820ba"
+dependencies = [
+ "libc",
+ "windows-sys 0.52.0",
+]
 
 [[package]]
 name = "getrandom"
-version = "0.2.0"
+version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "ee8025cf36f917e6a52cce185b7c7177689b838b7ec138364e50cc2277a56cf4"
+checksum = "c4567c8db10ae91089c99af84c68c38da3ec2f087c3f82960bcdbf3656b6f4d7"
 dependencies = [
  "cfg-if",
  "libc",
  "wasi",
 ]
 
+[[package]]
+name = "gimli"
+version = "0.31.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "07e28edb80900c19c28f1072f2e8aeca7fa06b23cd4169cefe1af5aa3260783f"
+
 [[package]]
 name = "hashbrown"
-version = "0.14.0"
+version = "0.15.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2c6201b9ff9fd90a5a3bac2e56a830d0caa509576f0e503818ee82c181b3437a"
+checksum = "3a9bfc1af68b1726ea47d3d5109de126281def866b33970e10fbab11b5dafab3"
 
 [[package]]
 name = "indexmap"
-version = "2.0.0"
+version = "2.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d5477fe2230a79769d8dc68e0eabf5437907c0457a5614a9e8dddb67f65eb65d"
+checksum = "707907fe3c25f5424cce2cb7e1cbcafee6bdbe735ca90ef77c29e84591e5b9da"
 dependencies = [
  "equivalent",
  "hashbrown",
 ]
 
+[[package]]
+name = "is_ci"
+version = "1.2.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "7655c9839580ee829dfacba1d1278c2b7883e50a277ff7541299489d6bdfdc45"
+
 [[package]]
 name = "itoa"
-version = "1.0.0"
+version = "1.0.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d2f3e61cf687687b30c9e6ddf0fc36cf15f035e66d491e6da968fa49ffa9a378"
+checksum = "49f1f14873335454500d59611f1cf4a4b0f786f9ac11f4312a78e4cf2566695b"
 
 [[package]]
 name = "jsonptr"
-version = "0.6.3"
+version = "0.7.0"
 dependencies = [
+ "miette",
  "quickcheck",
  "quickcheck_macros",
  "serde",
@@ -79,37 +147,89 @@ dependencies = [
 ]
 
 [[package]]
-name = "lazy_static"
-version = "1.0.0"
+name = "libc"
+version = "0.2.162"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c8f31047daa365f19be14b47c29df4f7c3b581832407daabe6ae77397619237d"
+checksum = "18d287de67fe55fd7e1581fe933d965a5a9477b38e949cfa9f8574ef01506398"
 
 [[package]]
-name = "libc"
-version = "0.2.64"
+name = "linux-raw-sys"
+version = "0.4.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "74dfca3d9957906e8d1e6a0b641dc9a59848e793f1da2165889fd4f62d10d79c"
+checksum = "78b3ae25bc7c8c38cec158d1f2757ee79e9b3740fbc7ccf0e59e4b08d793fa89"
 
 [[package]]
 name = "log"
-version = "0.4.8"
+version = "0.4.22"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a7a70ba024b9dc04c27ea2f0c0548feb474ec5c54bba33a7f72f873a39d07b24"
+
+[[package]]
+name = "memchr"
+version = "2.7.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "14b6052be84e6b71ab17edffc2eeabf5c2c3ae1fdb464aae35ac50c67a44e1f7"
+checksum = "78ca9ab1a0babb1e7d5695e3530886289c18cf2f87ec19a575a0abdce112e3a3"
+
+[[package]]
+name = "miette"
+version = "7.4.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "317f146e2eb7021892722af37cf1b971f0a70c8406f487e24952667616192c64"
 dependencies = [
+ "backtrace",
+ "backtrace-ext",
  "cfg-if",
+ "miette-derive",
+ "owo-colors",
+ "supports-color",
+ "supports-hyperlinks",
+ "supports-unicode",
+ "terminal_size",
+ "textwrap",
+ "thiserror",
+ "unicode-width",
 ]
 
 [[package]]
-name = "memchr"
-version = "2.5.0"
+name = "miette-derive"
+version = "7.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2dffe52ecf27772e601905b7522cb4ef790d2cc203488bbd0e2fe85fcb74566d"
+checksum = "23c9b935fbe1d6cbd1dac857b54a688145e2d93f48db36010514d0f612d0ad67"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.87",
+]
+
+[[package]]
+name = "miniz_oxide"
+version = "0.8.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e2d80299ef12ff69b16a84bb182e3b9df68b5a91574d3d4fa6e41b65deec4df1"
+dependencies = [
+ "adler2",
+]
+
+[[package]]
+name = "object"
+version = "0.36.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "aedf0a2d09c573ed1d8d85b30c119153926a2b36dce0ab28322c09a117a4683e"
+dependencies = [
+ "memchr",
+]
+
+[[package]]
+name = "owo-colors"
+version = "4.1.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "fb37767f6569cd834a413442455e0f066d0d522de8630436e2a1761d9726ba56"
 
 [[package]]
 name = "proc-macro2"
-version = "1.0.74"
+version = "1.0.89"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2de98502f212cfcea8d0bb305bd0f49d7ebdd75b64ba0a68f937d888f4e0d6db"
+checksum = "f139b0662de085916d1fb67d2b4169d1addddda1919e696f3252b740b629986e"
 dependencies = [
  "unicode-ident",
 ]
@@ -138,95 +258,147 @@ dependencies = [
 
 [[package]]
 name = "quote"
-version = "1.0.35"
+version = "1.0.37"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "291ec9ab5efd934aaf503a6466c5d5251535d108ee747472c3977cc5acc868ef"
+checksum = "b5b9d34b8991d19d98081b46eacdd8eb58c6f2b201139f7c5f643cc155a633af"
 dependencies = [
  "proc-macro2",
 ]
 
 [[package]]
 name = "rand"
-version = "0.8.0"
+version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a76330fb486679b4ace3670f117bbc9e16204005c4bde9c4bd372f45bed34f12"
+checksum = "34af8d1a0e25924bc5b7c43c079c942339d8f0a8b57c39049bef581b46327404"
 dependencies = [
  "rand_core",
 ]
 
 [[package]]
 name = "rand_core"
-version = "0.6.2"
+version = "0.6.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "34cf66eb183df1c5876e2dcf6b13d57340741e8dc255b48e40a26de954d06ae7"
+checksum = "ec0be4795e2f6a28069bec0b5ff3e2ac9bafc99e6a9a7dc3547996c5c816922c"
 dependencies = [
  "getrandom",
 ]
 
 [[package]]
 name = "regex"
-version = "1.3.0"
+version = "1.11.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b544ef1b4eac5dc2db33ea63606ae9ffcfac26c1416a2806ae0bf5f56b201191"
+dependencies = [
+ "aho-corasick",
+ "memchr",
+ "regex-automata",
+ "regex-syntax",
+]
+
+[[package]]
+name = "regex-automata"
+version = "0.4.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fc98360d9e6ad383647702acc90f80b0582eac3ea577ab47d96325d3575de908"
+checksum = "809e8dc61f6de73b46c85f4c96486310fe304c434cfa43669d7b40f711150908"
 dependencies = [
  "aho-corasick",
  "memchr",
  "regex-syntax",
- "thread_local",
 ]
 
 [[package]]
 name = "regex-syntax"
-version = "0.6.12"
+version = "0.8.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "11a7e20d1cce64ef2fed88b66d347f88bd9babb82845b2b858f3edbf59a4f716"
+checksum = "2b15c43186be67a4fd63bee50d0303afffcef381492ebe2c5d87f324e1b8815c"
+
+[[package]]
+name = "rustc-demangle"
+version = "0.1.24"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "719b953e2095829ee67db738b3bfa9fa368c94900df327b3f07fe6e794d2fe1f"
+
+[[package]]
+name = "rustix"
+version = "0.38.40"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "99e4ea3e1cdc4b559b8e5650f9c8e5998e3e5c1343b4eaf034565f32318d63c0"
+dependencies = [
+ "bitflags",
+ "errno",
+ "libc",
+ "linux-raw-sys",
+ "windows-sys 0.52.0",
+]
 
 [[package]]
 name = "ryu"
-version = "1.0.0"
+version = "1.0.18"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c92464b447c0ee8c4fb3824ecc8383b81717b9f1e74ba2e72540aef7b9f82997"
+checksum = "f3cb5ba0dc43242ce17de99c180e96db90b235b8a9fdc9543c96d2209116bd9f"
 
 [[package]]
 name = "serde"
-version = "1.0.203"
+version = "1.0.215"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7253ab4de971e72fb7be983802300c30b5a7f0c2e56fab8abfc6a214307c0094"
+checksum = "6513c1ad0b11a9376da888e3e0baa0077f1aed55c17f50e7b2397136129fb88f"
 dependencies = [
  "serde_derive",
 ]
 
 [[package]]
 name = "serde_derive"
-version = "1.0.203"
+version = "1.0.215"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "500cbc0ebeb6f46627f50f3f5811ccf6bf00643be300b4c3eabc0ef55dc5b5ba"
+checksum = "ad1e866f866923f252f05c889987993144fb74e722403468a4ebd70c3cd756c0"
 dependencies = [
  "proc-macro2",
  "quote",
- "syn 2.0.46",
+ "syn 2.0.87",
 ]
 
 [[package]]
 name = "serde_json"
-version = "1.0.119"
+version = "1.0.132"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e8eddb61f0697cc3989c5d64b452f5488e2b8a60fd7d5076a3045076ffef8cb0"
+checksum = "d726bfaff4b320266d395898905d0eba0345aae23b54aee3a737e260fd46db03"
 dependencies = [
  "itoa",
+ "memchr",
  "ryu",
  "serde",
 ]
 
 [[package]]
 name = "serde_spanned"
-version = "0.6.3"
+version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "96426c9936fd7a0124915f9185ea1d20aa9445cc9821142f0a73bc9207a2e186"
+checksum = "87607cb1398ed59d48732e575a4c28a7a8ebf2454b964fe3f224f2afc07909e1"
 dependencies = [
  "serde",
 ]
 
+[[package]]
+name = "supports-color"
+version = "3.0.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8775305acf21c96926c900ad056abeef436701108518cf890020387236ac5a77"
+dependencies = [
+ "is_ci",
+]
+
+[[package]]
+name = "supports-hyperlinks"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "2c0a1e5168041f5f3ff68ff7d95dcb9c8749df29f6e7e89ada40dd4c9de404ee"
+
+[[package]]
+name = "supports-unicode"
+version = "3.0.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b7401a30af6cb5818bb64852270bb722533397edcfc7344954a38f420819ece2"
+
 [[package]]
 name = "syn"
 version = "1.0.109"
@@ -240,9 +412,9 @@ dependencies = [
 
 [[package]]
 name = "syn"
-version = "2.0.46"
+version = "2.0.87"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "89456b690ff72fddcecf231caedbe615c59480c93358a93dfae7fc29e3ebbf0e"
+checksum = "25aa4ce346d03a6dcd68dd8b4010bcb74e54e62c90c573f394c46eae99aba32d"
 dependencies = [
  "proc-macro2",
  "quote",
@@ -250,19 +422,50 @@ dependencies = [
 ]
 
 [[package]]
-name = "thread_local"
-version = "0.3.6"
+name = "terminal_size"
+version = "0.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c6b53e329000edc2b34dbe8545fd20e55a333362d0a321909685a19bd28c3f1b"
+checksum = "5352447f921fda68cf61b4101566c0bdb5104eff6804d0678e5227580ab6a4e9"
 dependencies = [
- "lazy_static",
+ "rustix",
+ "windows-sys 0.59.0",
+]
+
+[[package]]
+name = "textwrap"
+version = "0.16.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23d434d3f8967a09480fb04132ebe0a3e088c173e6d0ee7897abbdf4eab0f8b9"
+dependencies = [
+ "unicode-linebreak",
+ "unicode-width",
+]
+
+[[package]]
+name = "thiserror"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "b6aaf5339b578ea85b50e080feb250a3e8ae8cfcdff9a461c9ec2904bc923f52"
+dependencies = [
+ "thiserror-impl",
+]
+
+[[package]]
+name = "thiserror-impl"
+version = "1.0.69"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "4fee6c4efc90059e10f81e6d42c60a18f76588c3d74cb83a0b242a2b6c7504c1"
+dependencies = [
+ "proc-macro2",
+ "quote",
+ "syn 2.0.87",
 ]
 
 [[package]]
 name = "toml"
-version = "0.8.0"
+version = "0.8.20"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c226a7bba6d859b63c92c4b4fe69c5b6b72d0cb897dbc8e6012298e6154cb56e"
+checksum = "cd87a5cdd6ffab733b2f74bc4fd7ee5fff6634124999ac278c35fc78c6120148"
 dependencies = [
  "serde",
  "serde_spanned",
@@ -272,18 +475,18 @@ dependencies = [
 
 [[package]]
 name = "toml_datetime"
-version = "0.6.3"
+version = "0.6.8"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7cda73e2f1397b1262d6dfdcef8aafae14d1de7748d66822d3bfeeb6d03e5e4b"
+checksum = "0dd7358ecb8fc2f8d014bf86f6f638ce72ba252a2c3a2572f2a795f1d23efb41"
 dependencies = [
  "serde",
 ]
 
 [[package]]
 name = "toml_edit"
-version = "0.20.0"
+version = "0.22.24"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "8ff63e60a958cefbb518ae1fd6566af80d9d4be430a33f3723dfc47d1d411d95"
+checksum = "17b4795ff5edd201c7cd6dca065ae59972ce77d1b80fa0a84d94950ece7d1474"
 dependencies = [
  "indexmap",
  "serde",
@@ -294,21 +497,115 @@ dependencies = [
 
 [[package]]
 name = "unicode-ident"
-version = "1.0.0"
+version = "1.0.13"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "e91b56cd4cadaeb79bbf1a5645f6b4f8dc5bde8834ad5894a8db35fda9efa1fe"
+
+[[package]]
+name = "unicode-linebreak"
+version = "0.1.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3b09c83c3c29d37506a3e260c08c03743a6bb66a9cd432c6934ab501a190571f"
+
+[[package]]
+name = "unicode-width"
+version = "0.1.14"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d22af068fba1eb5edcb4aea19d382b2a3deb4c8f9d475c589b6ada9e0fd493ee"
+checksum = "7dd6e30e90baa6f72411720665d41d89b9a3d039dc45b8faea1ddd07f617f6af"
 
 [[package]]
 name = "wasi"
-version = "0.9.0+wasi-snapshot-preview1"
+version = "0.11.0+wasi-snapshot-preview1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9c8d87e72b64a3b4db28d11ce29237c246188f4f51057d65a7eab63b7987e423"
+
+[[package]]
+name = "windows-sys"
+version = "0.52.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "282be5f36a8ce781fad8c8ae18fa3f9beff57ec1b52cb3de0789201425d9a33d"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-sys"
+version = "0.59.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "1e38bc4d79ed67fd075bcc251a1c39b32a1776bbe92e5bef1f0bf1f8c531853b"
+dependencies = [
+ "windows-targets",
+]
+
+[[package]]
+name = "windows-targets"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "9b724f72796e036ab90c1021d4780d4d3d648aca59e491e6b98e725b84e99973"
+dependencies = [
+ "windows_aarch64_gnullvm",
+ "windows_aarch64_msvc",
+ "windows_i686_gnu",
+ "windows_i686_gnullvm",
+ "windows_i686_msvc",
+ "windows_x86_64_gnu",
+ "windows_x86_64_gnullvm",
+ "windows_x86_64_msvc",
+]
+
+[[package]]
+name = "windows_aarch64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "32a4622180e7a0ec044bb555404c800bc9fd9ec262ec147edd5989ccd0c02cd3"
+
+[[package]]
+name = "windows_aarch64_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "09ec2a7bb152e2252b53fa7803150007879548bc709c039df7627cabbd05d469"
+
+[[package]]
+name = "windows_i686_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e9b5ad5ab802e97eb8e295ac6720e509ee4c243f69d781394014ebfe8bbfa0b"
+
+[[package]]
+name = "windows_i686_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0eee52d38c090b3caa76c563b86c3a4bd71ef1a819287c19d586d7334ae8ed66"
+
+[[package]]
+name = "windows_i686_msvc"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "240948bc05c5e7c6dabba28bf89d89ffce3e303022809e73deaefe4f6ec56c66"
+
+[[package]]
+name = "windows_x86_64_gnu"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "147a5c80aabfbf0c7d901cb5895d1de30ef2907eb21fbbab29ca94c5b08b1a78"
+
+[[package]]
+name = "windows_x86_64_gnullvm"
+version = "0.52.6"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "24d5b23dc417412679681396f2b49f3de8c1473deb516bd34410872eff51ed0d"
+
+[[package]]
+name = "windows_x86_64_msvc"
+version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "cccddf32554fecc6acb585f82a32a72e28b48f8c4c1883ddfeeeaa96f7d8e519"
+checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
 [[package]]
 name = "winnow"
-version = "0.5.0"
+version = "0.7.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "81fac9742fd1ad1bd9643b991319f72dd031016d44b77039a26977eb667141e7"
+checksum = "59690dea168f2198d1a3b0cac23b8063efcd11012f10ae4698f284808c8ef603"
 dependencies = [
  "memchr",
 ]
diff --git a/Cargo.toml b/Cargo.toml
index e4857e2..6ef6b2b 100644
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -13,9 +13,10 @@ license = "MIT OR Apache-2.0"
 name = "jsonptr"
 repository = "https://github.com/chanced/jsonptr"
 rust-version = "1.79.0"
-version = "0.6.3"
+version = "0.7.0"
 
 [dependencies]
+miette     = { version = "7.4.0", optional = true, features = ["fancy"] }
 serde      = { version = "1.0.203", optional = true, features = ["alloc"] }
 serde_json = { version = "1.0.119", optional = true, features = ["alloc"] }
 toml       = { version = "0.8", optional = true }
@@ -30,10 +31,20 @@ quickcheck_macros = "1.0.0"
 syn = { version = "1.0.109", optional = true }
 
 [features]
-assign  = []
-default = ["std", "serde", "json", "resolve", "assign", "delete"]
-delete  = ["resolve"]
-json    = ["dep:serde_json", "serde"]
+assign = []
+default = [
+  "std",
+  "serde",
+  "json",
+  "toml",    # TODO: remove
+  "resolve",
+  "assign",
+  "delete",
+  "miette",  # TODO: remove
+]
+delete = ["resolve"]
+json = ["dep:serde_json", "serde"]
+miette = ["dep:miette", "std"]
 resolve = []
-std     = ["serde/std", "serde_json?/std"]
-toml    = ["dep:toml", "serde", "std"]
+std = ["serde/std", "serde_json?/std"]
+toml = ["dep:toml", "serde", "std"]
diff --git a/src/assign.rs b/src/assign.rs
index a48bbb2..8b4e3bf 100644
--- a/src/assign.rs
+++ b/src/assign.rs
@@ -37,20 +37,15 @@
 //!
 
 use crate::{
+    diagnostic::{diagnostic_url, Diagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
-    Pointer,
+    Pointer, PointerBuf,
+};
+use alloc::{boxed::Box, string::ToString};
+use core::{
+    fmt::{self, Debug},
+    iter::once,
 };
-use core::fmt::{self, Debug};
-
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Assign                                    ║
-║                                   ¯¯¯¯¯¯¯¯                                   ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
 
 /// Implemented by types which can internally assign a
 /// ([`Value`](`Assign::Value`)) at a path represented by a JSON [`Pointer`].
@@ -129,31 +124,33 @@ pub trait Assign {
         V: Into<Self::Value>;
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                 AssignError                                  ║
-║                                ¯¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+/// Alias for [`Error`] - indicates a value assignment failed.
+#[deprecated(since = "0.7.0", note = "renamed to `Error`")]
+pub type AssignError = Error;
 
 /// Possible error returned from [`Assign`] implementations for
 /// [`serde_json::Value`] and
 /// [`toml::Value`](https://docs.rs/toml/0.8.14/toml/index.html).
 #[derive(Debug, PartialEq, Eq)]
-pub enum AssignError {
-    /// A `Token` within the `Pointer` failed to be parsed as an array index.
+pub enum Error {
+    /// A [`Token`](crate::Token) within the [`Pointer`] failed to be parsed as
+    /// an array index.
     FailedToParseIndex {
+        /// Position (index) of the token which failed to parse as an [`Index`](crate::index::Index)
+        position: usize,
         /// Offset of the partial pointer starting with the invalid index.
         offset: usize,
         /// The source [`ParseIndexError`]
         source: ParseIndexError,
     },
 
-    /// target array.
+    /// A [`Token`](crate::Token) within the [`Pointer`] contains an
+    /// [`Index`](crate::index::Index) which is out of bounds.
+    ///
+    /// The current or resulting array's length is less than the index.
     OutOfBounds {
+        /// Position (index) of the token which failed to parse as an [`Index`](crate::index::Index)
+        position: usize,
         /// Offset of the partial pointer starting with the invalid index.
         offset: usize,
         /// The source [`OutOfBoundsError`]
@@ -161,27 +158,91 @@ pub enum AssignError {
     },
 }
 
-impl fmt::Display for AssignError {
+impl Error {
+    /// The position (token index) of the [`Token`](crate::Token) which was out of bounds
+    pub fn position(&self) -> usize {
+        match self {
+            Self::OutOfBounds { position, .. } | Self::FailedToParseIndex { position, .. } => {
+                *position
+            }
+        }
+    }
+    /// Offset (in bytes) of the partial pointer starting with the invalid token.
+    pub fn offset(&self) -> usize {
+        match self {
+            Self::OutOfBounds { offset, .. } | Self::FailedToParseIndex { offset, .. } => *offset,
+        }
+    }
+
+    /// Returns `true` if the error is [`OutOfBounds`].
+    ///
+    /// [`OutOfBounds`]: Error::OutOfBounds
+    #[must_use]
+    pub fn is_out_of_bounds(&self) -> bool {
+        matches!(self, Self::OutOfBounds { .. })
+    }
+
+    /// Returns `true` if the error is [`FailedToParseIndex`].
+    ///
+    /// [`FailedToParseIndex`]: Error::FailedToParseIndex
+    #[must_use]
+    pub fn is_failed_to_parse_index(&self) -> bool {
+        matches!(self, Self::FailedToParseIndex { .. })
+    }
+}
+
+impl fmt::Display for Error {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
             Self::FailedToParseIndex { offset, .. } => {
                 write!(
                     f,
-                    "assignment failed due to an invalid index at offset {offset}"
-                )
-            }
-            Self::OutOfBounds { offset, .. } => {
-                write!(
-                    f,
-                    "assignment failed due to index at offset {offset} being out of bounds"
+                    "assign failed: json pointer token at offset {offset} failed to parse as an array index"
                 )
             }
+            Self::OutOfBounds { offset, .. } => write!(
+                f,
+                "assign failed: json pointer token at offset {offset} is out of bounds",
+            ),
         }
     }
 }
 
+impl Diagnostic for Error {
+    type Subject = PointerBuf;
+
+    fn url() -> &'static str {
+        diagnostic_url!(enum assign::Error)
+    }
+
+    fn labels(&self, origin: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
+        let position = self.position();
+        let token = origin.get(position)?;
+        let offset = if self.offset() + 1 < origin.as_str().len() {
+            self.offset() + 1
+        } else {
+            self.offset()
+        };
+        let len = token.encoded().len();
+        let text = match self {
+            Error::FailedToParseIndex { .. } => "expected array index or '-'".to_string(),
+            Error::OutOfBounds { source, .. } => {
+                format!("{} is out of bounds (len: {})", source.index, source.length)
+            }
+        };
+        Some(Box::new(once(Label::new(text, offset, len))))
+    }
+}
+
+#[cfg(feature = "miette")]
+impl miette::Diagnostic for Error {
+    fn url<'a>(&'a self) -> Option<Box<dyn fmt::Display + 'a>> {
+        Some(Box::new(<Self as Diagnostic>::url()))
+    }
+}
+
 #[cfg(feature = "std")]
-impl std::error::Error for AssignError {
+impl std::error::Error for Error {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
             Self::FailedToParseIndex { source, .. } => Some(source),
@@ -190,24 +251,9 @@ impl std::error::Error for AssignError {
     }
 }
 
-enum Assigned<'v, V> {
-    Done(Option<V>),
-    Continue { next_dest: &'v mut V, same_value: V },
-}
-
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  json impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "json")]
 mod json {
-    use super::{Assign, AssignError, Assigned};
+    use super::{Assign, Assigned, Error};
     use crate::{Pointer, Token};
     use alloc::{
         string::{String, ToString},
@@ -235,7 +281,7 @@ mod json {
     }
     impl Assign for Value {
         type Value = Value;
-        type Error = AssignError;
+        type Error = Error;
         fn assign<V>(&mut self, ptr: &Pointer, value: V) -> Result<Option<Self::Value>, Self::Error>
         where
             V: Into<Self::Value>,
@@ -248,14 +294,15 @@ mod json {
         mut ptr: &Pointer,
         mut dest: &mut Value,
         mut value: Value,
-    ) -> Result<Option<Value>, AssignError> {
+    ) -> Result<Option<Value>, Error> {
         let mut offset = 0;
 
+        let mut position = 0;
         while let Some((token, tail)) = ptr.split_front() {
             let tok_len = token.encoded().len();
 
             let assigned = match dest {
-                Value::Array(array) => assign_array(token, tail, array, value, offset)?,
+                Value::Array(array) => assign_array(token, tail, array, value, position, offset)?,
                 Value::Object(obj) => assign_object(token, tail, obj, value),
                 _ => assign_scalar(ptr, dest, value),
             };
@@ -273,6 +320,7 @@ mod json {
                 }
             }
             offset += 1 + tok_len;
+            position += 1;
         }
 
         // Pointer is root, we can replace `dest` directly
@@ -285,14 +333,23 @@ mod json {
         remaining: &Pointer,
         array: &'v mut Vec<Value>,
         src: Value,
+        position: usize,
         offset: usize,
-    ) -> Result<Assigned<'v, Value>, AssignError> {
+    ) -> Result<Assigned<'v, Value>, Error> {
         // parsing the index
         let idx = token
             .to_index()
-            .map_err(|source| AssignError::FailedToParseIndex { offset, source })?
+            .map_err(|source| Error::FailedToParseIndex {
+                position,
+                offset,
+                source,
+            })?
             .for_len_incl(array.len())
-            .map_err(|source| AssignError::OutOfBounds { offset, source })?;
+            .map_err(|source| Error::OutOfBounds {
+                position,
+                offset,
+                source,
+            })?;
 
         debug_assert!(idx <= array.len());
 
@@ -369,19 +426,9 @@ mod json {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  toml impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "toml")]
 mod toml {
-    use super::{Assign, AssignError, Assigned};
+    use super::{Assign, Assigned, Error};
     use crate::{Pointer, Token};
     use alloc::{string::String, vec, vec::Vec};
     use core::mem;
@@ -406,7 +453,7 @@ mod toml {
 
     impl Assign for Value {
         type Value = Value;
-        type Error = AssignError;
+        type Error = Error;
         fn assign<V>(&mut self, ptr: &Pointer, value: V) -> Result<Option<Self::Value>, Self::Error>
         where
             V: Into<Self::Value>,
@@ -419,14 +466,15 @@ mod toml {
         mut ptr: &Pointer,
         mut dest: &mut Value,
         mut value: Value,
-    ) -> Result<Option<Value>, AssignError> {
+    ) -> Result<Option<Value>, Error> {
         let mut offset = 0;
+        let mut position = 0;
 
         while let Some((token, tail)) = ptr.split_front() {
             let tok_len = token.encoded().len();
 
             let assigned = match dest {
-                Value::Array(array) => assign_array(token, tail, array, value, offset)?,
+                Value::Array(array) => assign_array(token, tail, array, value, position, offset)?,
                 Value::Table(tbl) => assign_object(token, tail, tbl, value),
                 _ => assign_scalar(ptr, dest, value),
             };
@@ -444,6 +492,7 @@ mod toml {
                 }
             }
             offset += 1 + tok_len;
+            position += 1;
         }
 
         // Pointer is root, we can replace `dest` directly
@@ -457,14 +506,23 @@ mod toml {
         remaining: &Pointer,
         array: &'v mut Vec<Value>,
         src: Value,
+        position: usize,
         offset: usize,
-    ) -> Result<Assigned<'v, Value>, AssignError> {
+    ) -> Result<Assigned<'v, Value>, Error> {
         // parsing the index
         let idx = token
             .to_index()
-            .map_err(|source| AssignError::FailedToParseIndex { offset, source })?
+            .map_err(|source| Error::FailedToParseIndex {
+                position,
+                offset,
+                source,
+            })?
             .for_len_incl(array.len())
-            .map_err(|source| AssignError::OutOfBounds { offset, source })?;
+            .map_err(|source| Error::OutOfBounds {
+                position,
+                offset,
+                source,
+            })?;
 
         debug_assert!(idx <= array.len());
 
@@ -537,20 +595,15 @@ mod toml {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Tests                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+enum Assigned<'v, V> {
+    Done(Option<V>),
+    Continue { next_dest: &'v mut V, same_value: V },
+}
 
 #[cfg(test)]
 #[allow(clippy::too_many_lines)]
 mod tests {
-    use super::{Assign, AssignError};
+    use super::{Assign, Error};
     use crate::{
         index::{InvalidCharacterError, OutOfBoundsError, ParseIndexError},
         Pointer,
@@ -574,9 +627,6 @@ mod tests {
         V::Error: Debug + PartialEq,
         Result<Option<V>, V::Error>: PartialEq<Result<Option<V::Value>, V::Error>>,
     {
-        fn all(tests: impl IntoIterator<Item = Test<V>>) {
-            tests.into_iter().enumerate().for_each(|(i, t)| t.run(i));
-        }
         fn run(self, i: usize) {
             let Test {
                 ptr,
@@ -596,18 +646,11 @@ mod tests {
         }
     }
 
-    /*
-    ╔═══════════════════════════════════════════════════╗
-    ║                        json                       ║
-    ╚═══════════════════════════════════════════════════╝
-    */
-
     #[test]
     #[cfg(feature = "json")]
     fn assign_json() {
         use serde_json::json;
-
-        Test::all([
+        [
             Test {
                 ptr: "/foo",
                 data: json!({}),
@@ -731,7 +774,8 @@ mod tests {
                 ptr: "/1",
                 data: json!([]),
                 assign: json!("foo"),
-                expected: Err(AssignError::OutOfBounds {
+                expected: Err(Error::OutOfBounds {
+                    position: 0,
                     offset: 0,
                     source: OutOfBoundsError {
                         index: 1,
@@ -751,7 +795,8 @@ mod tests {
                 ptr: "/12a",
                 data: json!([]),
                 assign: json!("foo"),
-                expected: Err(AssignError::FailedToParseIndex {
+                expected: Err(Error::FailedToParseIndex {
+                    position: 0,
                     offset: 0,
                     source: ParseIndexError::InvalidCharacter(InvalidCharacterError {
                         source: "12a".into(),
@@ -764,7 +809,8 @@ mod tests {
                 ptr: "/002",
                 data: json!([]),
                 assign: json!("foo"),
-                expected: Err(AssignError::FailedToParseIndex {
+                expected: Err(Error::FailedToParseIndex {
+                    position: 0,
                     offset: 0,
                     source: ParseIndexError::LeadingZeros,
                 }),
@@ -774,7 +820,8 @@ mod tests {
                 ptr: "/+23",
                 data: json!([]),
                 assign: json!("foo"),
-                expected: Err(AssignError::FailedToParseIndex {
+                expected: Err(Error::FailedToParseIndex {
+                    position: 0,
                     offset: 0,
                     source: ParseIndexError::InvalidCharacter(InvalidCharacterError {
                         source: "+23".into(),
@@ -783,21 +830,17 @@ mod tests {
                 }),
                 expected_data: json!([]),
             },
-        ]);
+        ]
+        .into_iter()
+        .enumerate()
+        .for_each(|(i, t)| t.run(i));
     }
 
-    /*
-    ╔══════════════════════════════════════════════════╗
-    ║                       toml                       ║
-    ╚══════════════════════════════════════════════════╝
-    */
-
     #[test]
     #[cfg(feature = "toml")]
     fn assign_toml() {
         use toml::{toml, Table, Value};
-
-        Test::all([
+        [
             Test {
                 data: Value::Table(toml::Table::new()),
                 ptr: "/foo",
@@ -916,7 +959,8 @@ mod tests {
                 data: Value::Array(vec![]),
                 ptr: "/1",
                 assign: "foo".into(),
-                expected: Err(AssignError::OutOfBounds {
+                expected: Err(Error::OutOfBounds {
+                    position: 0,
                     offset: 0,
                     source: OutOfBoundsError {
                         index: 1,
@@ -929,7 +973,8 @@ mod tests {
                 data: Value::Array(vec![]),
                 ptr: "/a",
                 assign: "foo".into(),
-                expected: Err(AssignError::FailedToParseIndex {
+                expected: Err(Error::FailedToParseIndex {
+                    position: 0,
                     offset: 0,
                     source: ParseIndexError::InvalidCharacter(InvalidCharacterError {
                         source: "a".into(),
@@ -938,6 +983,9 @@ mod tests {
                 }),
                 expected_data: Value::Array(vec![]),
             },
-        ]);
+        ]
+        .into_iter()
+        .enumerate()
+        .for_each(|(i, t)| t.run(i));
     }
 }
diff --git a/src/diagnostic.rs b/src/diagnostic.rs
new file mode 100644
index 0000000..69dcb10
--- /dev/null
+++ b/src/diagnostic.rs
@@ -0,0 +1,279 @@
+//! Error reporting data structures and miette integration.
+//!
+
+use alloc::{boxed::Box, string::String};
+use core::{fmt, ops::Deref};
+
+/// Implemented by errors which can be converted into a [`Report`].
+pub trait Diagnostic: Sized {
+    /// The value which caused the error.
+    type Subject: Deref;
+
+    /// Combine the error with its subject to generate a [`Report`].
+    fn into_report(self, subject: impl Into<Self::Subject>) -> Report<Self> {
+        Report::new(self, subject.into())
+    }
+
+    /// The docs.rs URL for this error
+    fn url() -> &'static str;
+
+    /// Returns the label for the given [`Subject`] if applicable.
+    fn labels(&self, subject: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>>;
+}
+
+/// A label for a span within a json pointer or malformed string.
+///
+#[derive(Debug, PartialEq, Eq, Clone)]
+pub struct Label {
+    text: String,
+    offset: usize,
+    len: usize,
+}
+
+impl Label {
+    /// Creates a new instance of a [`Label`] from its parts
+    pub fn new(text: String, offset: usize, len: usize) -> Self {
+        Self { text, offset, len }
+    }
+}
+
+#[cfg(feature = "miette")]
+impl From<Label> for miette::LabeledSpan {
+    fn from(value: Label) -> Self {
+        miette::LabeledSpan::new(Some(value.text), value.offset, value.len)
+    }
+}
+
+/// An enriched error wrapper which captures the original error and the subject
+/// (`String` or `PointerBuf`) which caused it, for reporting purposes.
+///
+/// This type serves two roles:
+///
+/// 1. **[`PointerBuf::parse`]**: Captures the [`ParseError`] along with the
+///    input `String`.
+///
+/// 2. **Reporting:** Provides enriched reporting capabilities, including
+///    (optional) `miette` integration, for `ParseError` and associated  errors
+///    of `assign::Assign` and `resolve::Resolve` implementations
+#[derive(Debug, Clone)]
+pub struct Report<T: Diagnostic> {
+    source: T,
+    subject: T::Subject,
+}
+
+impl<T: Diagnostic> Report<T> {
+    fn new(source: T, subject: T::Subject) -> Self {
+        Self { source, subject }
+    }
+
+    /// The value which caused the error.
+    pub fn subject(&self) -> &<T::Subject as Deref>::Target {
+        &self.subject
+    }
+
+    /// The error which occurred.
+    pub fn original(&self) -> &T {
+        &self.source
+    }
+
+    /// The original parts of the [`Report`].
+    pub fn decompose(self) -> (T, T::Subject) {
+        (self.source, self.subject)
+    }
+
+    /// Consumes the [`Report`] and returns the original error `T`.
+    pub fn into_original(self) -> T {
+        self.source
+    }
+}
+
+impl<T: Diagnostic> core::ops::Deref for Report<T> {
+    type Target = T;
+
+    fn deref(&self) -> &Self::Target {
+        &self.source
+    }
+}
+
+impl<T: Diagnostic + fmt::Display> fmt::Display for Report<T> {
+    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
+        fmt::Display::fmt(&self.source, f)
+    }
+}
+
+#[cfg(feature = "std")]
+impl<T> std::error::Error for Report<T>
+where
+    T: Diagnostic + fmt::Debug + std::error::Error + 'static,
+    T::Subject: fmt::Debug,
+{
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        self.source.source()
+    }
+}
+
+#[cfg(feature = "miette")]
+impl<T> miette::Diagnostic for Report<T>
+where
+    T: Diagnostic + fmt::Debug + std::error::Error + 'static,
+    T::Subject: fmt::Debug + miette::SourceCode,
+{
+    fn url<'a>(&'a self) -> Option<Box<dyn core::fmt::Display + 'a>> {
+        Some(Box::new(T::url()))
+    }
+
+    fn source_code(&self) -> Option<&dyn miette::SourceCode> {
+        Some(&self.subject)
+    }
+
+    fn labels(&self) -> Option<Box<dyn Iterator<Item = miette::LabeledSpan> + '_>> {
+        Some(Box::new(T::labels(self, &self.subject)?.map(Into::into)))
+    }
+}
+
+macro_rules! diagnostic_url {
+    (enum $type:ident) => {
+        $crate::diagnostic::diagnostic_url!("enum", "", $type)
+    };
+    (struct $type:ident) => {
+        $crate::diagnostic::diagnostic_url!("struct", "", $type)
+    };
+    (enum $mod:ident::$type:ident) => {
+        $crate::diagnostic::diagnostic_url!("enum", concat!("/", stringify!($mod)), $type)
+    };
+    (struct $mod:ident::$type:ident) => {
+        $crate::diagnostic::diagnostic_url!("struct", concat!("/", stringify!($mod)), $type)
+    };
+    ($kind:literal, $mod:expr, $type:ident) => {
+        concat!(
+            "https://docs.rs/jsonptr/",
+            env!("CARGO_PKG_VERSION"),
+            "/jsonptr",
+            $mod,
+            "/",
+            $kind,
+            ".",
+            stringify!($type),
+            ".html",
+        )
+    };
+}
+pub(crate) use diagnostic_url;
+
+/// An extension trait for `Result<_, E>`, where `E` is an implementation of
+/// [`Diagnostic`], that converts `E` into [`Report<E>`](`Report`), yielding
+/// `Result<_, Report<E>>`.
+pub trait Diagnose<'s, T> {
+    /// The error type returned from `diagnose` and `diagnose_with`.
+    type Error: Diagnostic;
+
+    /// If the `Result` is an `Err`, converts the error into a [`Report`] with
+    /// the supplied `subject`.
+    ///
+    /// ## Example
+    /// ```
+    /// use core::any::{Any, TypeId};
+    /// use jsonptr::{Pointer, ParseError, Diagnose, Report};
+    /// let subj = "invalid/pointer";
+    /// let err = Pointer::parse(subj).diagnose(subj).unwrap_err();
+    /// assert_eq!(err.type_id(),TypeId::of::<Report<ParseError>>());
+    /// ```
+    #[allow(clippy::missing_errors_doc)]
+    fn diagnose(
+        self,
+        subject: impl Into<<Self::Error as Diagnostic>::Subject>,
+    ) -> Result<T, Report<Self::Error>>;
+
+    /// If the `Result` is an `Err`, converts the error into a [`Report`] with
+    /// the subject returned from `f`
+    ///
+    /// ## Example
+    /// ```
+    /// use core::any::{Any, TypeId};
+    /// use jsonptr::{Pointer, ParseError, Diagnose, Report};
+    /// let subj = "invalid/pointer";
+    /// let err = Pointer::parse(subj).diagnose_with(|| subj).unwrap_err();
+    ///
+    /// assert_eq!(err.type_id(),TypeId::of::<Report<ParseError>>());
+    #[allow(clippy::missing_errors_doc)]
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<Self::Error>>
+    where
+        F: FnOnce() -> S,
+        S: Into<<Self::Error as Diagnostic>::Subject>;
+}
+
+impl<T, E> Diagnose<'_, T> for Result<T, E>
+where
+    E: Diagnostic,
+{
+    type Error = E;
+
+    fn diagnose(
+        self,
+        subject: impl Into<<Self::Error as Diagnostic>::Subject>,
+    ) -> Result<T, Report<Self::Error>> {
+        self.map_err(|error| error.into_report(subject.into()))
+    }
+
+    fn diagnose_with<F, S>(self, f: F) -> Result<T, Report<Self::Error>>
+    where
+        F: FnOnce() -> S,
+        S: Into<<Self::Error as Diagnostic>::Subject>,
+    {
+        self.diagnose(f())
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use crate::{Pointer, PointerBuf};
+    #[test]
+    #[cfg(all(
+        feature = "assign",
+        feature = "miette",
+        feature = "serde",
+        feature = "json"
+    ))]
+    fn assign_error() {
+        let mut v = serde_json::json!({"foo": {"bar": ["0"]}});
+        let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
+        let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+
+        let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
+        let report = ptr.assign(&mut v, "qux").diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+    }
+
+    #[test]
+    #[cfg(all(
+        feature = "resolve",
+        feature = "miette",
+        feature = "serde",
+        feature = "json"
+    ))]
+    fn resolve_error() {
+        let v = serde_json::json!({"foo": {"bar": ["0"]}});
+        let ptr = PointerBuf::parse("/foo/bar/invalid/cannot/reach").unwrap();
+        let report = ptr.resolve(&v).diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+
+        let ptr = PointerBuf::parse("/foo/bar/3/cannot/reach").unwrap();
+        let report = ptr.resolve(&v).diagnose(ptr).unwrap_err();
+        println!("{:?}", miette::Report::from(report));
+    }
+
+    #[test]
+    fn parse_error() {
+        let invalid = "/foo/bar/invalid~3~encoding/cannot/reach";
+        let report = Pointer::parse(invalid).diagnose(invalid).unwrap_err();
+
+        println!("{:?}", miette::Report::from(report));
+
+        let report = PointerBuf::parse("/foo/bar/invalid~3~encoding/cannot/reach").unwrap_err();
+
+        let report = miette::Report::from(report);
+        println!("{report:?}");
+    }
+}
diff --git a/src/index.rs b/src/index.rs
index 0acbb4b..bad40bc 100644
--- a/src/index.rs
+++ b/src/index.rs
@@ -237,7 +237,7 @@ derive_try_from!(String, &String);
 */
 
 /// Indicates that an `Index` is not within the given bounds.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct OutOfBoundsError {
     /// The provided array length.
     ///
@@ -256,7 +256,7 @@ impl fmt::Display for OutOfBoundsError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
-            "index {} out of bounds (limit: {})",
+            "index {} out of bounds (len: {})",
             self.index, self.length
         )
     }
@@ -276,7 +276,7 @@ impl std::error::Error for OutOfBoundsError {}
 */
 
 /// Indicates that the `Token` could not be parsed as valid RFC 6901 array index.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub enum ParseIndexError {
     /// The Token does not represent a valid integer.
     InvalidInteger(ParseIntError),
@@ -295,14 +295,16 @@ impl From<ParseIntError> for ParseIndexError {
 impl fmt::Display for ParseIndexError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            ParseIndexError::InvalidInteger(source) => {
-                write!(f, "failed to parse token as an integer: {source}")
+            ParseIndexError::InvalidInteger(_) => {
+                write!(f, "failed to parse token as an integer")
             }
             ParseIndexError::LeadingZeros => write!(
                 f,
                 "token contained leading zeros, which are disallowed by RFC 6901"
             ),
-            ParseIndexError::InvalidCharacter(err) => err.fmt(f),
+            ParseIndexError::InvalidCharacter(_) => {
+                write!(f, "failed to parse token as an index")
+            }
         }
     }
 }
@@ -319,7 +321,7 @@ impl std::error::Error for ParseIndexError {
 }
 
 /// Indicates that a non-digit character was found when parsing the RFC 6901 array index.
-#[derive(Debug, PartialEq, Eq)]
+#[derive(Debug, Clone, PartialEq, Eq)]
 pub struct InvalidCharacterError {
     pub(crate) source: String,
     pub(crate) offset: usize,
@@ -456,49 +458,6 @@ mod tests {
         assert!(Index::Next.for_len(1).is_err());
     }
 
-    #[test]
-    fn out_of_bounds_error_display() {
-        let err = OutOfBoundsError {
-            length: 5,
-            index: 10,
-        };
-        assert_eq!(err.to_string(), "index 10 out of bounds (limit: 5)");
-    }
-
-    #[test]
-    fn parse_index_error_display() {
-        let err = ParseIndexError::InvalidInteger("not a number".parse::<usize>().unwrap_err());
-        assert_eq!(
-            err.to_string(),
-            "failed to parse token as an integer: invalid digit found in string"
-        );
-        assert_eq!(
-            ParseIndexError::LeadingZeros.to_string(),
-            "token contained leading zeros, which are disallowed by RFC 6901"
-        );
-        assert_eq!(
-            ParseIndexError::InvalidCharacter(InvalidCharacterError {
-                source: "+10".into(),
-                offset: 0
-            })
-            .to_string(),
-            "token contains the non-digit character '+', \
-                which is disallowed by RFC 6901"
-        );
-    }
-
-    #[test]
-    #[cfg(feature = "std")]
-    fn parse_index_error_source() {
-        use std::error::Error;
-        let err = ParseIndexError::InvalidInteger("not a number".parse::<usize>().unwrap_err());
-        assert_eq!(
-            err.source().unwrap().to_string(),
-            "not a number".parse::<usize>().unwrap_err().to_string()
-        );
-        assert!(ParseIndexError::LeadingZeros.source().is_none());
-    }
-
     #[test]
     fn try_from_token() {
         let token = Token::new("3");
diff --git a/src/lib.rs b/src/lib.rs
index 850dd2d..1339c83 100644
--- a/src/lib.rs
+++ b/src/lib.rs
@@ -64,11 +64,17 @@ pub mod resolve;
 #[cfg(feature = "resolve")]
 pub use resolve::{Resolve, ResolveMut};
 
+pub mod diagnostic;
+pub use diagnostic::{Diagnose, Report};
+
 mod pointer;
-pub use pointer::{ParseError, Pointer, PointerBuf};
+pub use pointer::{ParseError, Pointer, PointerBuf, RichParseError};
 
 mod token;
-pub use token::{InvalidEncodingError, Token, Tokens};
+pub use token::{EncodingError, InvalidEncoding, Token, Tokens};
+
+#[allow(deprecated)]
+pub use token::InvalidEncodingError;
 
 pub mod index;
 
diff --git a/src/pointer.rs b/src/pointer.rs
index b31dccf..be0be7a 100644
--- a/src/pointer.rs
+++ b/src/pointer.rs
@@ -1,26 +1,20 @@
-use crate::{token::InvalidEncodingError, Components, Token, Tokens};
+use crate::{
+    diagnostic::{diagnostic_url, Diagnostic, Label, Report},
+    token::EncodingError,
+    Components, InvalidEncoding, Token, Tokens,
+};
 use alloc::{
-    borrow::ToOwned,
+    borrow::{Cow, ToOwned},
     boxed::Box,
     fmt,
     string::{String, ToString},
     vec::Vec,
 };
-use core::{borrow::Borrow, cmp::Ordering, ops::Deref, str::FromStr};
+use core::{borrow::Borrow, cmp::Ordering, iter::once, ops::Deref, str::FromStr};
 use slice::PointerIndex;
 
 mod slice;
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                   Pointer                                    ║
-║                                  ¯¯¯¯¯¯¯¯¯                                   ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// A JSON Pointer is a string containing a sequence of zero or more reference
 /// [`Token`]s, each prefixed by a `'/'` character.
 ///
@@ -211,11 +205,13 @@ impl Pointer {
             )
             .into()
     }
+
     /// Splits the `Pointer` at the given index if the character at the index is
-    /// a separator backslash (`'/'`), returning `Some((head, tail))`. Otherwise,
+    /// a separator slash (`'/'`), returning `Some((head, tail))`. Otherwise,
     /// returns `None`.
     ///
-    /// For the following JSON Pointer, the following splits are possible (0, 4, 8):
+    /// For the following JSON Pointer, the following splits are possible (0, 4,
+    /// 8):
     /// ```text
     /// /foo/bar/baz
     /// ↑   ↑   ↑
@@ -542,7 +538,7 @@ impl Pointer {
     /// See [`PointerBuf::append`] for more details.
     ///
     /// **Note**: this method allocates. If you find yourself calling it more
-    /// than once for a given pointer, consider using [`PointerBuf::append`]
+    /// than  given pointer, consider using [`PointerBuf::append`]
     /// instead.
     ///
     /// ## Examples
@@ -639,6 +635,37 @@ impl<'de: 'p, 'p> serde::Deserialize<'de> for &'p Pointer {
     }
 }
 
+macro_rules! impl_source_code {
+    ($($ty:ty),+) => {
+        $(
+            #[cfg(feature = "miette")]
+            impl miette::SourceCode for $ty {
+                fn read_span<'a>(
+                    &'a self,
+                    span: &miette::SourceSpan,
+                    context_lines_before: usize,
+                    context_lines_after: usize,
+                ) -> Result<Box<dyn miette::SpanContents<'a> + 'a>, miette::MietteError> {
+                    miette::SourceCode::read_span(
+                        self.0.as_bytes(),
+                        span,
+                        context_lines_before,
+                        context_lines_after,
+                    )
+                }
+            }
+        )*
+    };
+}
+
+impl_source_code!(Pointer, &Pointer, PointerBuf);
+
+impl<'p> From<&'p Pointer> for Cow<'p, Pointer> {
+    fn from(value: &'p Pointer) -> Self {
+        Cow::Borrowed(value)
+    }
+}
+
 impl ToOwned for Pointer {
     type Owned = PointerBuf;
 
@@ -862,16 +889,6 @@ impl<'a> IntoIterator for &'a Pointer {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  PointerBuf                                  ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// An owned, mutable [`Pointer`] (akin to `String`).
 ///
 /// This type provides methods like [`PointerBuf::push_back`] and
@@ -905,11 +922,13 @@ impl PointerBuf {
     /// Attempts to parse a string into a `PointerBuf`.
     ///
     /// ## Errors
-    /// Returns a [`ParseError`] if the string is not a valid JSON Pointer.
-    pub fn parse(s: impl Into<String>) -> Result<Self, ParseError> {
+    /// Returns a [`RichParseError`] if the string is not a valid JSON Pointer.
+    pub fn parse(s: impl Into<String>) -> Result<Self, RichParseError> {
         let s = s.into();
-        validate(&s)?;
-        Ok(Self(s))
+        match validate(&s) {
+            Ok(_) => Ok(Self(s)),
+            Err(err) => Err(err.into_report(s)),
+        }
     }
 
     /// Creates a new `PointerBuf` from a slice of non-encoded strings.
@@ -1072,6 +1091,12 @@ impl serde::Serialize for PointerBuf {
     }
 }
 
+impl From<PointerBuf> for Cow<'static, Pointer> {
+    fn from(value: PointerBuf) -> Self {
+        Cow::Owned(value)
+    }
+}
+
 impl From<Token<'_>> for PointerBuf {
     fn from(t: Token) -> Self {
         PointerBuf::from_tokens([t])
@@ -1125,80 +1150,25 @@ impl core::fmt::Display for PointerBuf {
     }
 }
 
-const fn validate(value: &str) -> Result<&str, ParseError> {
-    if value.is_empty() {
-        return Ok(value);
-    }
-    let bytes = value.as_bytes();
-    if bytes[0] != b'/' {
-        return Err(ParseError::NoLeadingBackslash);
-    }
-    let mut ptr_offset = 0; // offset within the pointer of the most recent '/' separator
-    let mut tok_offset = 0; // offset within the current token
+/// Indicates that a [`Pointer`] was unable to be parsed due to not containing
+/// a leading slash (`'/'`).
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub struct NoLeadingSlash;
 
-    let bytes = value.as_bytes();
-    let mut i = 0;
-    while i < bytes.len() {
-        match bytes[i] {
-            b'/' => {
-                // backslashes ('/') separate tokens
-                // we increment the ptr_offset to point to this character
-                ptr_offset = i;
-                // and reset the token offset
-                tok_offset = 0;
-            }
-            b'~' => {
-                // if the character is a '~', then the next character must be '0' or '1'
-                // otherwise the encoding is invalid and `InvalidEncodingError` is returned
-                if i + 1 >= bytes.len() || (bytes[i + 1] != b'0' && bytes[i + 1] != b'1') {
-                    // the pointer is not properly encoded
-                    //
-                    // we use the pointer offset, which points to the last
-                    // encountered separator, as the offset of the error.
-                    // The source `InvalidEncodingError` then uses the token
-                    // offset.
-                    //
-                    // "/foo/invalid~encoding"
-                    //      ^       ^
-                    //      |       |
-                    //  ptr_offset  |
-                    //          tok_offset
-                    //
-                    return Err(ParseError::InvalidEncoding {
-                        offset: ptr_offset,
-                        source: InvalidEncodingError { offset: tok_offset },
-                    });
-                }
-                // already checked the next character, so we skip it
-                i += 1;
-                // incrementing the pointer offset since the next byte has
-                // already been checked
-                tok_offset += 1;
-            }
-            _ => {}
-        }
-        i += 1;
-        // not a separator so we increment the token offset
-        tok_offset += 1;
+impl fmt::Display for NoLeadingSlash {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        write!(
+            f,
+            "json pointer must start with a slash ('/') and is not empty"
+        )
     }
-    Ok(value)
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  ParseError                                  ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯¯                                 ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// Indicates that a `Pointer` was malformed and unable to be parsed.
 #[derive(Debug, PartialEq)]
 pub enum ParseError {
-    /// `Pointer` did not start with a backslash (`'/'`).
-    NoLeadingBackslash,
+    /// `Pointer` did not start with a slash (`'/'`).
+    NoLeadingSlash,
 
     /// `Pointer` contained invalid encoding (e.g. `~` not followed by `0` or
     /// `1`).
@@ -1207,28 +1177,85 @@ pub enum ParseError {
         /// the invalid encoding
         offset: usize,
         /// The source `InvalidEncodingError`
-        source: InvalidEncodingError,
+        source: EncodingError,
     },
 }
 
+impl ParseError {
+    /// Offset of the partial pointer starting with the token that contained the
+    /// invalid encoding
+    pub fn offset(&self) -> usize {
+        match self {
+            Self::NoLeadingSlash => 0,
+            Self::InvalidEncoding { offset, .. } => *offset,
+        }
+    }
+    /// Length of the invalid encoding
+    pub fn invalid_encoding_len(&self, subject: &str) -> usize {
+        match self {
+            Self::NoLeadingSlash => 0,
+            Self::InvalidEncoding { offset, .. } => {
+                if *offset < subject.len() - 1 {
+                    2
+                } else {
+                    1
+                }
+            }
+        }
+    }
+}
+
+impl Diagnostic for ParseError {
+    type Subject = String;
+
+    fn url() -> &'static str {
+        diagnostic_url!(struct ParseError)
+    }
+
+    fn labels(&self, subject: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
+        let offset = self.complete_offset();
+        let len = self.invalid_encoding_len(subject);
+        let text = match self {
+            ParseError::NoLeadingSlash => "must start with a slash ('/')",
+            ParseError::InvalidEncoding { .. } => "'~' must be followed by '0' or '1'",
+        }
+        .to_string();
+        Some(Box::new(once(Label::new(text, offset, len))))
+    }
+}
+
+#[cfg(feature = "miette")]
+impl miette::Diagnostic for ParseError {}
+
 impl fmt::Display for ParseError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         match self {
-            Self::NoLeadingBackslash { .. } => {
+            Self::NoLeadingSlash { .. } => {
                 write!(
                     f,
-                    "json pointer is malformed as it does not start with a backslash ('/')"
+                    "json pointer failed to parse; does not start with a slash ('/') and is not empty"
+                )
+            }
+            Self::InvalidEncoding { offset, .. } => {
+                write!(
+                    f,
+                    "json pointer failed to parse; the first token in the partial-pointer starting at offset {offset} is malformed"
                 )
             }
-            Self::InvalidEncoding { source, .. } => write!(f, "{source}"),
         }
     }
 }
 
 impl ParseError {
-    /// Returns `true` if this error is `NoLeadingBackslash`
+    #[deprecated(note = "renamed to `is_no_leading_slash`", since = "0.7.0")]
+    /// Returns `true` if this error is `NoLeadingSlash`
     pub fn is_no_leading_backslash(&self) -> bool {
-        matches!(self, Self::NoLeadingBackslash { .. })
+        matches!(self, Self::NoLeadingSlash { .. })
+    }
+
+    /// Returns `true` if this error is `NoLeadingSlash`
+    pub fn is_no_leading_slash(&self) -> bool {
+        matches!(self, Self::NoLeadingSlash { .. })
     }
 
     /// Returns `true` if this error is `InvalidEncoding`    
@@ -1250,7 +1277,7 @@ impl ParseError {
     /// ```
     pub fn pointer_offset(&self) -> usize {
         match *self {
-            Self::NoLeadingBackslash { .. } => 0,
+            Self::NoLeadingSlash { .. } => 0,
             Self::InvalidEncoding { offset, .. } => offset,
         }
     }
@@ -1270,7 +1297,7 @@ impl ParseError {
     /// ```
     pub fn source_offset(&self) -> usize {
         match self {
-            Self::NoLeadingBackslash { .. } => 0,
+            Self::NoLeadingSlash { .. } => 0,
             Self::InvalidEncoding { source, .. } => source.offset,
         }
     }
@@ -1296,20 +1323,13 @@ impl std::error::Error for ParseError {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
             Self::InvalidEncoding { source, .. } => Some(source),
-            Self::NoLeadingBackslash => None,
+            Self::NoLeadingSlash => None,
         }
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                              ReplaceTokenError                               ║
-║                             ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                              ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+/// A rich error type that includes the original string that failed to parse.
+pub type RichParseError = Report<ParseError>;
 
 /// Returned from [`PointerBuf::replace`] when the provided index is out of
 /// bounds.
@@ -1330,15 +1350,71 @@ impl fmt::Display for ReplaceError {
 #[cfg(feature = "std")]
 impl std::error::Error for ReplaceError {}
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Tests                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+const fn validate(value: &str) -> Result<&str, ParseError> {
+    if value.is_empty() {
+        return Ok(value);
+    }
+    if let Err(err) = validate_bytes(value.as_bytes(), 0) {
+        return Err(err);
+    }
+    Ok(value)
+}
+
+const fn validate_bytes(bytes: &[u8], offset: usize) -> Result<(), ParseError> {
+    if bytes[0] != b'/' && offset == 0 {
+        return Err(ParseError::NoLeadingSlash);
+    }
+
+    let mut ptr_offset = offset; // offset within the pointer of the most recent '/' separator
+    let mut tok_offset = 0; // offset within the current token
+
+    let mut i = offset;
+    while i < bytes.len() {
+        match bytes[i] {
+            b'/' => {
+                ptr_offset = i;
+                // and reset the token offset
+                tok_offset = 0;
+            }
+            b'~' => {
+                // if the character is a '~', then the next character must be '0' or '1'
+                // otherwise the encoding is invalid and `InvalidEncodingError` is returned
+                if i + 1 >= bytes.len() || (bytes[i + 1] != b'0' && bytes[i + 1] != b'1') {
+                    // the pointer is not properly encoded
+                    //
+                    // we use the pointer offset, which points to the last
+                    // encountered separator, as the offset of the error.
+                    // The source `InvalidEncodingError` then uses the token
+                    // offset.
+                    //
+                    // "/foo/invalid~encoding"
+                    //      ^       ^
+                    //      |       |
+                    //  ptr_offset  |
+                    //          tok_offset
+                    //
+                    return Err(ParseError::InvalidEncoding {
+                        offset: ptr_offset,
+                        source: EncodingError {
+                            offset: tok_offset,
+                            source: InvalidEncoding::Tilde,
+                        },
+                    });
+                }
+                // already checked the next character, so we skip it
+                i += 1;
+                // incrementing the pointer offset since the next byte has
+                // already been checked
+                tok_offset += 1;
+            }
+            _ => {}
+        }
+        i += 1;
+        // not a separator so we increment the token offset
+        tok_offset += 1;
+    }
+    Ok(())
+}
 
 #[cfg(test)]
 mod tests {
@@ -1438,23 +1514,6 @@ mod tests {
         assert!(p.starts_with(q));
     }
 
-    #[test]
-    fn parse_error_is_no_leading_backslash() {
-        let err = ParseError::NoLeadingBackslash;
-        assert!(err.is_no_leading_backslash());
-        assert!(!err.is_invalid_encoding());
-    }
-
-    #[test]
-    fn parse_error_is_invalid_encoding() {
-        let err = ParseError::InvalidEncoding {
-            offset: 0,
-            source: InvalidEncodingError { offset: 1 },
-        };
-        assert!(!err.is_no_leading_backslash());
-        assert!(err.is_invalid_encoding());
-    }
-
     #[test]
     fn parse() {
         let tests = [
@@ -1469,26 +1528,35 @@ mod tests {
             ("/foo/bar/baz/~10", Ok("/foo/bar/baz/~10")),
             ("/foo/bar/baz/~11", Ok("/foo/bar/baz/~11")),
             ("/foo/bar/baz/~1/~0", Ok("/foo/bar/baz/~1/~0")),
-            ("missing-slash", Err(ParseError::NoLeadingBackslash)),
+            ("missing-slash", Err(ParseError::NoLeadingSlash)),
             (
                 "/~",
                 Err(ParseError::InvalidEncoding {
                     offset: 0,
-                    source: InvalidEncodingError { offset: 1 },
+                    source: EncodingError {
+                        offset: 1,
+                        source: InvalidEncoding::Tilde,
+                    },
                 }),
             ),
             (
                 "/~2",
                 Err(ParseError::InvalidEncoding {
                     offset: 0,
-                    source: InvalidEncodingError { offset: 1 },
+                    source: EncodingError {
+                        offset: 1,
+                        source: InvalidEncoding::Tilde,
+                    },
                 }),
             ),
             (
                 "/~a",
                 Err(ParseError::InvalidEncoding {
                     offset: 0,
-                    source: InvalidEncodingError { offset: 1 },
+                    source: EncodingError {
+                        offset: 1,
+                        source: InvalidEncoding::Tilde,
+                    },
                 }),
             ),
         ];
@@ -1513,25 +1581,6 @@ mod tests {
         assert!(err.source().is_none());
     }
 
-    #[test]
-    #[cfg(feature = "std")]
-    fn parse_error_source() {
-        use std::error::Error;
-        let err = Pointer::parse("/foo/invalid~encoding").unwrap_err();
-        assert!(err.source().is_some());
-        let source = err.source().unwrap();
-        assert!(source.is::<InvalidEncodingError>());
-
-        let err = Pointer::parse("no-leading/slash").unwrap_err();
-        assert!(err.source().is_none());
-    }
-
-    #[test]
-    fn pointerbuf_as_pointer_returns_pointer() {
-        let ptr = PointerBuf::parse("/foo/bar").unwrap();
-        assert_eq!(ptr.as_ptr(), ptr);
-    }
-
     #[test]
     fn pointer_buf_clear() {
         let mut ptr = PointerBuf::from_tokens(["foo", "bar"]);
@@ -1601,12 +1650,6 @@ mod tests {
         assert_eq!(ptr, "");
     }
 
-    #[test]
-    fn display_replace_token_error() {
-        let err = ReplaceError { index: 3, count: 2 };
-        assert_eq!(format!("{err}"), "index 3 is out of bounds (2)");
-    }
-
     #[test]
     fn pop_front_works_with_empty_strings() {
         {
@@ -1705,16 +1748,6 @@ mod tests {
         assert_eq!(ptr, into);
     }
 
-    #[test]
-    fn default() {
-        let ptr = PointerBuf::default();
-        assert_eq!(ptr, "");
-        assert_eq!(ptr.count(), 0);
-
-        let ptr = <&Pointer>::default();
-        assert_eq!(ptr, "");
-    }
-
     #[test]
     #[cfg(all(feature = "serde", feature = "json"))]
     fn to_json_value() {
@@ -1807,7 +1840,7 @@ mod tests {
     fn replace_token_out_of_bounds() {
         let mut ptr = PointerBuf::from_tokens(["foo", "bar"]);
         assert!(ptr.replace(2, "baz").is_err());
-        assert_eq!(ptr, PointerBuf::from_tokens(["foo", "bar"])); // Ensure original pointer is unchanged
+        assert_eq!(ptr, PointerBuf::from_tokens(["foo", "bar"])); // Ensure subjectal pointer is unchanged
     }
 
     #[test]
@@ -1904,6 +1937,7 @@ mod tests {
     #[test]
     #[cfg(feature = "json")]
     fn into_value() {
+        use alloc::string::ToString;
         use serde_json::Value;
         let ptr = Pointer::from_static("/foo/bar");
         let value: Value = ptr.into();
@@ -1930,7 +1964,7 @@ mod tests {
 
     #[quickcheck]
     fn qc_pop_and_push(mut ptr: PointerBuf) -> bool {
-        let original_ptr = ptr.clone();
+        let subjectal_ptr = ptr.clone();
         let mut tokens = Vec::with_capacity(ptr.count());
         while let Some(token) = ptr.pop_back() {
             tokens.push(token);
@@ -1941,7 +1975,7 @@ mod tests {
         for token in tokens.drain(..) {
             ptr.push_front(token);
         }
-        if ptr != original_ptr {
+        if ptr != subjectal_ptr {
             return false;
         }
         while let Some(token) = ptr.pop_front() {
@@ -1953,7 +1987,7 @@ mod tests {
         for token in tokens {
             ptr.push_back(token);
         }
-        ptr == original_ptr
+        ptr == subjectal_ptr
     }
 
     #[quickcheck]
@@ -2080,10 +2114,6 @@ mod tests {
 
         let invalid = serde_json::from_str::<&Pointer>("\"foo/bar\"");
         assert!(invalid.is_err());
-        assert_eq!(
-            invalid.unwrap_err().to_string(),
-            "failed to parse json pointer\n\ncaused by:\njson pointer is malformed as it does not start with a backslash ('/') at line 1 column 9"
-        );
     }
 
     #[test]
@@ -2266,13 +2296,6 @@ mod tests {
             assert_eq!(intersection, base);
         }
     }
-    #[test]
-    fn parse_error_display() {
-        assert_eq!(
-            ParseError::NoLeadingBackslash.to_string(),
-            "json pointer is malformed as it does not start with a backslash ('/')"
-        );
-    }
 
     #[test]
     fn into_iter() {
@@ -2315,9 +2338,15 @@ mod tests {
 
     #[test]
     fn from_box_to_buf() {
-        let original = PointerBuf::parse("/foo/bar/0").unwrap();
-        let boxed: Box<Pointer> = original.clone().into();
+        let subjectal = PointerBuf::parse("/foo/bar/0").unwrap();
+        let boxed: Box<Pointer> = subjectal.clone().into();
         let unboxed = boxed.into_buf();
-        assert_eq!(original, unboxed);
+        assert_eq!(subjectal, unboxed);
+    }
+
+    #[test]
+    fn quick_miette_spike() {
+        let err = PointerBuf::parse("hello-world").unwrap_err();
+        println!("{:?}", miette::Report::from(err));
     }
 }
diff --git a/src/resolve.rs b/src/resolve.rs
index 1f981d1..5dba4fd 100644
--- a/src/resolve.rs
+++ b/src/resolve.rs
@@ -34,19 +34,12 @@
 //!
 //!
 use crate::{
+    diagnostic::{diagnostic_url, Diagnostic, Label},
     index::{OutOfBoundsError, ParseIndexError},
-    Pointer, Token,
+    Pointer, PointerBuf, Token,
 };
-
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                   Resolve                                    ║
-║                                  ¯¯¯¯¯¯¯¯¯                                   ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+use alloc::{boxed::Box, string::ToString};
+use core::iter::once;
 
 /// A trait implemented by types which can resolve a reference to a value type
 /// from a path represented by a JSON [`Pointer`].
@@ -65,16 +58,6 @@ pub trait Resolve {
     fn resolve(&self, ptr: &Pointer) -> Result<&Self::Value, Self::Error>;
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                 ResolveMut                                   ║
-║                                ¯¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 /// A trait implemented by types which can resolve a mutable reference to a
 /// value type from a path represented by a JSON [`Pointer`].
 pub trait ResolveMut {
@@ -93,19 +76,13 @@ pub trait ResolveMut {
     fn resolve_mut(&mut self, ptr: &Pointer) -> Result<&mut Self::Value, Self::Error>;
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                 ResolveError                                 ║
-║                                ¯¯¯¯¯¯¯¯¯¯¯¯¯¯                                ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
+// TODO: should ResolveError be deprecated?
+/// Alias for [`Error`].
+pub type ResolveError = Error;
 
 /// Indicates that the `Pointer` could not be resolved.
 #[derive(Debug, PartialEq, Eq)]
-pub enum ResolveError {
+pub enum Error {
     /// `Pointer` could not be resolved because a `Token` for an array index is
     /// not a valid integer or dash (`"-"`).
     ///
@@ -118,14 +95,16 @@ pub enum ResolveError {
     /// assert!(ptr.resolve(&data).unwrap_err().is_failed_to_parse_index());
     /// ```
     FailedToParseIndex {
+        /// Position (index) of the token which failed to parse as an [`Index`](crate::index::Index)
+        position: usize,
         /// Offset of the partial pointer starting with the invalid index.
         offset: usize,
         /// The source `ParseIndexError`
         source: ParseIndexError,
     },
 
-    /// `Pointer` could not be resolved due to an index being out of bounds
-    /// within an array.
+    /// A [`Token`] within the [`Pointer`] contains an [`Index`] which is out of
+    /// bounds.
     ///
     /// ## Example
     /// ```rust
@@ -135,6 +114,8 @@ pub enum ResolveError {
     /// let ptr = Pointer::from_static("/foo/1");
     /// assert!(ptr.resolve(&data).unwrap_err().is_out_of_bounds());
     OutOfBounds {
+        /// Position (index) of the token which failed to parse as an [`Index`](crate::index::Index)
+        position: usize,
         /// Offset of the partial pointer starting with the invalid index.
         offset: usize,
         /// The source `OutOfBoundsError`
@@ -152,6 +133,8 @@ pub enum ResolveError {
     /// assert!(ptr.resolve(&data).unwrap_err().is_not_found());
     /// ```
     NotFound {
+        /// Position (index) of the token which was not found.
+        position: usize,
         /// Offset of the pointer starting with the `Token` which was not found.
         offset: usize,
     },
@@ -169,12 +152,14 @@ pub enum ResolveError {
     /// assert!(err.is_unreachable());
     /// ```
     Unreachable {
+        /// Position (index) of the token which was unreachable.
+        position: usize,
         /// Offset of the pointer which was unreachable.
         offset: usize,
     },
 }
 
-impl ResolveError {
+impl Error {
     /// Offset of the partial pointer starting with the token which caused the
     /// error.
     pub fn offset(&self) -> usize {
@@ -186,6 +171,16 @@ impl ResolveError {
         }
     }
 
+    /// Position (index) of the token which caused the error.
+    pub fn position(&self) -> usize {
+        match self {
+            Self::FailedToParseIndex { position, .. }
+            | Self::OutOfBounds { position, .. }
+            | Self::NotFound { position, .. }
+            | Self::Unreachable { position, .. } => *position,
+        }
+    }
+
     /// Returns `true` if this error is `FailedToParseIndex`; otherwise returns
     /// `false`.
     pub fn is_unreachable(&self) -> bool {
@@ -211,27 +206,59 @@ impl ResolveError {
     }
 }
 
-impl core::fmt::Display for ResolveError {
+impl Diagnostic for Error {
+    type Subject = PointerBuf;
+
+    fn url() -> &'static str {
+        diagnostic_url!(enum assign::Error)
+    }
+
+    fn labels(&self, origin: &Self::Subject) -> Option<Box<dyn Iterator<Item = Label>>> {
+        let position = self.position();
+        let token = origin.get(position)?;
+        let offset = if self.offset() + 1 < origin.as_str().len() {
+            self.offset() + 1
+        } else {
+            self.offset()
+        };
+        let len = token.encoded().len();
+        let text = match self {
+            Error::FailedToParseIndex { .. } => "not an array index".to_string(),
+            Error::OutOfBounds { source, .. } => source.to_string(),
+            Error::NotFound { .. } => "not found in value".to_string(),
+            Error::Unreachable { .. } => "unreachable".to_string(),
+        };
+        Some(Box::new(once(Label::new(text, offset, len))))
+    }
+}
+
+impl core::fmt::Display for Error {
     fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
         match self {
             Self::FailedToParseIndex { offset, .. } => {
-                write!(f, "failed to parse index at offset {offset}")
+                write!(f, "resolve failed: json pointer token at offset {offset} failed to parse as an index")
             }
             Self::OutOfBounds { offset, .. } => {
-                write!(f, "index at offset {offset} out of bounds")
+                write!(
+                    f,
+                    "resolve failed: json pointer token at offset {offset} is out of bounds"
+                )
             }
             Self::NotFound { offset, .. } => {
-                write!(f, "pointer starting at offset {offset} not found")
+                write!(
+                    f,
+                    "resolve failed: json pointer token at {offset} was not found in value"
+                )
             }
             Self::Unreachable { offset, .. } => {
-                write!(f, "pointer starting at offset {offset} is unreachable")
+                write!(f, "resolve failed: json pointer token at {offset} is unreachable (previous token resolved to a scalar or null value)")
             }
         }
     }
 }
 
 #[cfg(feature = "std")]
-impl std::error::Error for ResolveError {
+impl std::error::Error for Error {
     fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
         match self {
             Self::FailedToParseIndex { source, .. } => Some(source),
@@ -241,27 +268,18 @@ impl std::error::Error for ResolveError {
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  json impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "json")]
 mod json {
-    use super::{parse_index, Pointer, Resolve, ResolveError, ResolveMut};
+    use super::{parse_index, Error, Pointer, Resolve, ResolveMut};
     use serde_json::Value;
 
     impl Resolve for Value {
         type Value = Value;
-        type Error = ResolveError;
+        type Error = Error;
 
         fn resolve(&self, mut ptr: &Pointer) -> Result<&Value, Self::Error> {
             let mut offset = 0;
+            let mut position = 0;
             let mut value = self;
             while let Some((token, rem)) = ptr.split_front() {
                 let tok_len = token.encoded().len();
@@ -270,19 +288,28 @@ mod json {
                     Value::Array(v) => {
                         let idx = token
                             .to_index()
-                            .map_err(|source| ResolveError::FailedToParseIndex { offset, source })?
+                            .map_err(|source| Error::FailedToParseIndex {
+                                position,
+                                offset,
+                                source,
+                            })?
                             .for_len(v.len())
-                            .map_err(|source| ResolveError::OutOfBounds { offset, source })?;
+                            .map_err(|source| Error::OutOfBounds {
+                                position,
+                                offset,
+                                source,
+                            })?;
                         Ok(&v[idx])
                     }
 
                     Value::Object(v) => v
                         .get(token.decoded().as_ref())
-                        .ok_or(ResolveError::NotFound { offset }),
+                        .ok_or(Error::NotFound { position, offset }),
                     // found a leaf node but the pointer hasn't been exhausted
-                    _ => Err(ResolveError::Unreachable { offset }),
+                    _ => Err(Error::Unreachable { position, offset }),
                 }?;
                 offset += 1 + tok_len;
+                position += 1;
             }
             Ok(value)
         }
@@ -290,61 +317,67 @@ mod json {
 
     impl ResolveMut for Value {
         type Value = Value;
-        type Error = ResolveError;
+        type Error = Error;
 
-        fn resolve_mut(&mut self, mut ptr: &Pointer) -> Result<&mut Value, ResolveError> {
+        fn resolve_mut(&mut self, mut ptr: &Pointer) -> Result<&mut Value, Error> {
             let mut offset = 0;
+            let mut position = 0;
             let mut value = self;
             while let Some((token, rem)) = ptr.split_front() {
                 let tok_len = token.encoded().len();
                 ptr = rem;
                 value = match value {
                     Value::Array(array) => {
-                        let idx = parse_index(token, array.len(), offset)?;
+                        let idx = parse_index(token, array.len(), position, offset)?;
                         Ok(&mut array[idx])
                     }
                     Value::Object(v) => v
                         .get_mut(token.decoded().as_ref())
-                        .ok_or(ResolveError::NotFound { offset }),
+                        .ok_or(Error::NotFound { position, offset }),
                     // found a leaf node but the pointer hasn't been exhausted
-                    _ => Err(ResolveError::Unreachable { offset }),
+                    _ => Err(Error::Unreachable { position, offset }),
                 }?;
                 offset += 1 + tok_len;
+                position += 1;
             }
             Ok(value)
         }
     }
 }
-fn parse_index(token: Token, array_len: usize, offset: usize) -> Result<usize, ResolveError> {
+fn parse_index(
+    token: Token,
+    array_len: usize,
+    position: usize,
+    offset: usize,
+) -> Result<usize, Error> {
     token
         .to_index()
-        .map_err(|source| ResolveError::FailedToParseIndex { offset, source })?
+        .map_err(|source| Error::FailedToParseIndex {
+            position,
+            offset,
+            source,
+        })?
         .for_len(array_len)
-        .map_err(|source| ResolveError::OutOfBounds { offset, source })
+        .map_err(|source| Error::OutOfBounds {
+            position,
+            offset,
+            source,
+        })
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                  toml impl                                   ║
-║                                 ¯¯¯¯¯¯¯¯¯¯¯                                  ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(feature = "toml")]
 mod toml {
-    use super::{Resolve, ResolveError, ResolveMut};
+    use super::{Error, Resolve, ResolveMut};
     use crate::Pointer;
     use toml::Value;
 
     impl Resolve for Value {
         type Value = Value;
-        type Error = ResolveError;
+        type Error = Error;
 
         fn resolve(&self, mut ptr: &Pointer) -> Result<&Value, Self::Error> {
             let mut offset = 0;
+            let mut position = 0;
             let mut value = self;
             while let Some((token, rem)) = ptr.split_front() {
                 let tok_len = token.encoded().len();
@@ -353,19 +386,28 @@ mod toml {
                     Value::Array(v) => {
                         let idx = token
                             .to_index()
-                            .map_err(|source| ResolveError::FailedToParseIndex { offset, source })?
+                            .map_err(|source| Error::FailedToParseIndex {
+                                position,
+                                offset,
+                                source,
+                            })?
                             .for_len(v.len())
-                            .map_err(|source| ResolveError::OutOfBounds { offset, source })?;
+                            .map_err(|source| Error::OutOfBounds {
+                                position,
+                                offset,
+                                source,
+                            })?;
                         Ok(&v[idx])
                     }
 
                     Value::Table(v) => v
                         .get(token.decoded().as_ref())
-                        .ok_or(ResolveError::NotFound { offset }),
+                        .ok_or(Error::NotFound { position, offset }),
                     // found a leaf node but the pointer hasn't been exhausted
-                    _ => Err(ResolveError::Unreachable { offset }),
+                    _ => Err(Error::Unreachable { position, offset }),
                 }?;
                 offset += 1 + tok_len;
+                position += 1;
             }
             Ok(value)
         }
@@ -373,10 +415,12 @@ mod toml {
 
     impl ResolveMut for Value {
         type Value = Value;
-        type Error = ResolveError;
+        type Error = Error;
 
-        fn resolve_mut(&mut self, mut ptr: &Pointer) -> Result<&mut Value, ResolveError> {
+        fn resolve_mut(&mut self, mut ptr: &Pointer) -> Result<&mut Value, Error> {
             let mut offset = 0;
+            let mut position = 0;
+
             let mut value = self;
             while let Some((token, rem)) = ptr.split_front() {
                 let tok_len = token.encoded().len();
@@ -385,154 +429,85 @@ mod toml {
                     Value::Array(array) => {
                         let idx = token
                             .to_index()
-                            .map_err(|source| ResolveError::FailedToParseIndex { offset, source })?
+                            .map_err(|source| Error::FailedToParseIndex {
+                                position,
+                                offset,
+                                source,
+                            })?
                             .for_len(array.len())
-                            .map_err(|source| ResolveError::OutOfBounds { offset, source })?;
+                            .map_err(|source| Error::OutOfBounds {
+                                position,
+                                offset,
+                                source,
+                            })?;
                         Ok(&mut array[idx])
                     }
                     Value::Table(v) => v
                         .get_mut(token.decoded().as_ref())
-                        .ok_or(ResolveError::NotFound { offset }),
+                        .ok_or(Error::NotFound { position, offset }),
                     // found a leaf node but the pointer hasn't been exhausted
-                    _ => Err(ResolveError::Unreachable { offset }),
+                    _ => Err(Error::Unreachable { position, offset }),
                 }?;
                 offset += 1 + tok_len;
+                position += 1;
             }
             Ok(value)
         }
     }
 }
 
-/*
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-╔══════════════════════════════════════════════════════════════════════════════╗
-║                                                                              ║
-║                                    Tests                                     ║
-║                                   ¯¯¯¯¯¯¯                                    ║
-╚══════════════════════════════════════════════════════════════════════════════╝
-░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
-*/
-
 #[cfg(test)]
 mod tests {
-    use super::{Resolve, ResolveError, ResolveMut};
+    use super::{Error, Resolve, ResolveMut};
     use crate::{
         index::{OutOfBoundsError, ParseIndexError},
         Pointer,
     };
     use core::fmt;
 
-    #[cfg(feature = "std")]
-    #[test]
-    fn resolve_error_source() {
-        use std::error::Error;
-        let err = ResolveError::FailedToParseIndex {
-            offset: 0,
-            source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
-        };
-        assert!(err.source().is_some());
-
-        let err = ResolveError::OutOfBounds {
-            offset: 0,
-            source: OutOfBoundsError {
-                index: 1,
-                length: 0,
-            },
-        };
-        assert!(err.source().is_some());
-
-        let err = ResolveError::NotFound { offset: 0 };
-        assert!(err.source().is_none());
-
-        let err = ResolveError::Unreachable { offset: 0 };
-        assert!(err.source().is_none());
-    }
-
-    #[test]
-    fn resolve_error_display() {
-        let err = ResolveError::FailedToParseIndex {
-            offset: 0,
-            source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
-        };
-        assert_eq!(format!("{err}"), "failed to parse index at offset 0");
-
-        let err = ResolveError::OutOfBounds {
-            offset: 0,
-            source: OutOfBoundsError {
-                index: 1,
-                length: 0,
-            },
-        };
-        assert_eq!(format!("{err}"), "index at offset 0 out of bounds");
-
-        let err = ResolveError::NotFound { offset: 0 };
-
-        assert_eq!(format!("{err}"), "pointer starting at offset 0 not found");
-
-        let err = ResolveError::Unreachable { offset: 0 };
-        assert_eq!(
-            format!("{err}"),
-            "pointer starting at offset 0 is unreachable"
-        );
-    }
-
     #[test]
-    fn resolve_error_offset() {
-        let err = ResolveError::FailedToParseIndex {
+    fn resolve_error_is_unreachable() {
+        let err = Error::FailedToParseIndex {
+            position: 0,
             offset: 0,
             source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
         };
-        assert_eq!(err.offset(), 0);
+        assert!(!err.is_unreachable());
 
-        let err = ResolveError::OutOfBounds {
+        let err = Error::OutOfBounds {
+            position: 0,
             offset: 0,
             source: OutOfBoundsError {
                 index: 1,
                 length: 0,
             },
         };
-        assert_eq!(err.offset(), 0);
-
-        let err = ResolveError::NotFound { offset: 0 };
-        assert_eq!(err.offset(), 0);
-
-        let err = ResolveError::Unreachable { offset: 0 };
-        assert_eq!(err.offset(), 0);
-    }
+        assert!(!err.is_unreachable());
 
-    #[test]
-    fn resolve_error_is_unreachable() {
-        let err = ResolveError::FailedToParseIndex {
+        let err = Error::NotFound {
+            position: 0,
             offset: 0,
-            source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
         };
         assert!(!err.is_unreachable());
 
-        let err = ResolveError::OutOfBounds {
+        let err = Error::Unreachable {
+            position: 0,
             offset: 0,
-            source: OutOfBoundsError {
-                index: 1,
-                length: 0,
-            },
         };
-        assert!(!err.is_unreachable());
-
-        let err = ResolveError::NotFound { offset: 0 };
-        assert!(!err.is_unreachable());
-
-        let err = ResolveError::Unreachable { offset: 0 };
         assert!(err.is_unreachable());
     }
 
     #[test]
     fn resolve_error_is_not_found() {
-        let err = ResolveError::FailedToParseIndex {
+        let err = Error::FailedToParseIndex {
+            position: 0,
             offset: 0,
             source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
         };
         assert!(!err.is_not_found());
 
-        let err = ResolveError::OutOfBounds {
+        let err = Error::OutOfBounds {
+            position: 0,
             offset: 0,
             source: OutOfBoundsError {
                 index: 1,
@@ -541,22 +516,30 @@ mod tests {
         };
         assert!(!err.is_not_found());
 
-        let err = ResolveError::NotFound { offset: 0 };
+        let err = Error::NotFound {
+            position: 0,
+            offset: 0,
+        };
         assert!(err.is_not_found());
 
-        let err = ResolveError::Unreachable { offset: 0 };
+        let err = Error::Unreachable {
+            position: 0,
+            offset: 0,
+        };
         assert!(!err.is_not_found());
     }
 
     #[test]
     fn resolve_error_is_out_of_bounds() {
-        let err = ResolveError::FailedToParseIndex {
+        let err = Error::FailedToParseIndex {
+            position: 0,
             offset: 0,
             source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
         };
         assert!(!err.is_out_of_bounds());
 
-        let err = ResolveError::OutOfBounds {
+        let err = Error::OutOfBounds {
+            position: 0,
             offset: 0,
             source: OutOfBoundsError {
                 index: 1,
@@ -565,22 +548,30 @@ mod tests {
         };
         assert!(err.is_out_of_bounds());
 
-        let err = ResolveError::NotFound { offset: 0 };
+        let err = Error::NotFound {
+            position: 0,
+            offset: 0,
+        };
         assert!(!err.is_out_of_bounds());
 
-        let err = ResolveError::Unreachable { offset: 0 };
+        let err = Error::Unreachable {
+            position: 0,
+            offset: 0,
+        };
         assert!(!err.is_out_of_bounds());
     }
 
     #[test]
     fn resolve_error_is_failed_to_parse_index() {
-        let err = ResolveError::FailedToParseIndex {
+        let err = Error::FailedToParseIndex {
+            position: 0,
             offset: 0,
             source: ParseIndexError::InvalidInteger("invalid".parse::<usize>().unwrap_err()),
         };
         assert!(err.is_failed_to_parse_index());
 
-        let err = ResolveError::OutOfBounds {
+        let err = Error::OutOfBounds {
+            position: 0,
             offset: 0,
             source: OutOfBoundsError {
                 index: 1,
@@ -589,10 +580,16 @@ mod tests {
         };
         assert!(!err.is_failed_to_parse_index());
 
-        let err = ResolveError::NotFound { offset: 0 };
+        let err = Error::NotFound {
+            position: 0,
+            offset: 0,
+        };
         assert!(!err.is_failed_to_parse_index());
 
-        let err = ResolveError::Unreachable { offset: 0 };
+        let err = Error::Unreachable {
+            position: 0,
+            offset: 0,
+        };
         assert!(!err.is_failed_to_parse_index());
     }
 
@@ -699,13 +696,19 @@ mod tests {
             Test {
                 ptr: "/object/bool/unresolvable",
                 data,
-                expected: Err(ResolveError::Unreachable { offset: 12 }),
+                expected: Err(Error::Unreachable {
+                    position: 2,
+                    offset: 12,
+                }),
             },
             // 12
             Test {
                 ptr: "/object/not_found",
                 data,
-                expected: Err(ResolveError::NotFound { offset: 7 }),
+                expected: Err(Error::NotFound {
+                    position: 1,
+                    offset: 7,
+                }),
             },
         ]);
     }
@@ -799,25 +802,31 @@ mod tests {
             Test {
                 ptr: "/object/bool/unresolvable",
                 data,
-                expected: Err(ResolveError::Unreachable { offset: 12 }),
+                expected: Err(Error::Unreachable {
+                    position: 2,
+                    offset: 12,
+                }),
             },
             Test {
                 ptr: "/object/not_found",
                 data,
-                expected: Err(ResolveError::NotFound { offset: 7 }),
+                expected: Err(Error::NotFound {
+                    position: 1,
+                    offset: 7,
+                }),
             },
         ]);
     }
     struct Test<'v, V> {
         ptr: &'static str,
-        expected: Result<&'v V, ResolveError>,
+        expected: Result<&'v V, Error>,
         data: &'v V,
     }
 
     impl<'v, V> Test<'v, V>
     where
-        V: Resolve<Value = V, Error = ResolveError>
-            + ResolveMut<Value = V, Error = ResolveError>
+        V: Resolve<Value = V, Error = Error>
+            + ResolveMut<Value = V, Error = Error>
             + Clone
             + PartialEq
             + fmt::Display
diff --git a/src/token.rs b/src/token.rs
index 0447d20..fe574a2 100644
--- a/src/token.rs
+++ b/src/token.rs
@@ -70,11 +70,16 @@ impl<'a> Token<'a> {
     /// ## Errors
     /// Returns `InvalidEncodingError` if the input string is not a valid RFC
     /// 6901 (`~` must be followed by `0` or `1`)
-    pub fn from_encoded(s: &'a str) -> Result<Self, InvalidEncodingError> {
+    pub fn from_encoded(s: &'a str) -> Result<Self, EncodingError> {
         let mut escaped = false;
         for (offset, b) in s.bytes().enumerate() {
             match b {
-                b'/' => return Err(InvalidEncodingError { offset }),
+                b'/' => {
+                    return Err(EncodingError {
+                        offset,
+                        source: InvalidEncoding::Slash,
+                    })
+                }
                 ENC_PREFIX => {
                     escaped = true;
                 }
@@ -83,13 +88,19 @@ impl<'a> Token<'a> {
                 }
                 _ => {
                     if escaped {
-                        return Err(InvalidEncodingError { offset });
+                        return Err(EncodingError {
+                            offset,
+                            source: InvalidEncoding::Tilde,
+                        });
                     }
                 }
             }
         }
         if escaped {
-            return Err(InvalidEncodingError { offset: s.len() });
+            return Err(EncodingError {
+                offset: s.len(),
+                source: InvalidEncoding::Slash,
+            });
         }
         Ok(Self { inner: s.into() })
     }
@@ -345,26 +356,77 @@ impl<'t> Tokens<'t> {
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
 */
 
+#[deprecated(since = "0.7.0", note = "renamed to `EncodingError`")]
+/// Deprecated alias for [`EncodingError`].
+pub type InvalidEncodingError = EncodingError;
+
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                                EncodingError                                 ║
+║                               ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                                ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
 /// A token within a json pointer contained invalid encoding (`~` not followed
 /// by `0` or `1`).
 ///
 #[derive(Debug, PartialEq, Eq)]
-pub struct InvalidEncodingError {
+pub struct EncodingError {
     /// offset of the erroneous `~` from within the `Token`
     pub offset: usize,
+    /// the specific encoding error
+    pub source: InvalidEncoding,
 }
 
-impl fmt::Display for InvalidEncodingError {
+#[cfg(feature = "std")]
+impl std::error::Error for EncodingError {
+    fn source(&self) -> Option<&(dyn std::error::Error + 'static)> {
+        Some(&self.source)
+    }
+}
+
+impl fmt::Display for EncodingError {
     fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
         write!(
             f,
-            "json pointer is malformed due to invalid encoding ('~' not followed by '0' or '1')"
+            "token contains invalid encoding at offset {}",
+            self.offset
         )
     }
 }
 
+/*
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+╔══════════════════════════════════════════════════════════════════════════════╗
+║                                                                              ║
+║                               InvalidEncoding                                ║
+║                              ¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯¯                               ║
+╚══════════════════════════════════════════════════════════════════════════════╝
+░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
+*/
+
+/// Represents the specific type of invalid encoding error.
+#[derive(Debug, PartialEq, Eq, Clone, Copy)]
+pub enum InvalidEncoding {
+    /// `~` not followed by `0` or `1`
+    Tilde,
+    /// non-encoded `/` found in token
+    Slash,
+}
+
+impl fmt::Display for InvalidEncoding {
+    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
+        match self {
+            InvalidEncoding::Tilde => write!(f, "tilde (~) not followed by 0 or 1"),
+            InvalidEncoding::Slash => write!(f, "slash (/) found in token"),
+        }
+    }
+}
 #[cfg(feature = "std")]
-impl std::error::Error for InvalidEncodingError {}
+impl std::error::Error for InvalidEncoding {}
 
 /*
 ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░
@@ -378,7 +440,7 @@ impl std::error::Error for InvalidEncodingError {}
 
 #[cfg(test)]
 mod tests {
-    use crate::{assign::AssignError, index::OutOfBoundsError, Pointer};
+    use crate::Pointer;
 
     use super::*;
     use quickcheck_macros::quickcheck;
@@ -408,53 +470,6 @@ mod tests {
         assert_eq!(Token::new("a/b").encoded(), "a~1b");
     }
 
-    #[test]
-    fn assign_error_display() {
-        let err = AssignError::FailedToParseIndex {
-            offset: 3,
-            source: ParseIndexError::InvalidInteger("a".parse::<usize>().unwrap_err()),
-        };
-        assert_eq!(
-            err.to_string(),
-            "assignment failed due to an invalid index at offset 3"
-        );
-
-        let err = AssignError::OutOfBounds {
-            offset: 3,
-            source: OutOfBoundsError {
-                index: 3,
-                length: 2,
-            },
-        };
-
-        assert_eq!(
-            err.to_string(),
-            "assignment failed due to index at offset 3 being out of bounds"
-        );
-    }
-
-    #[test]
-    #[cfg(feature = "std")]
-    fn assign_error_source() {
-        use std::error::Error;
-        let err = AssignError::FailedToParseIndex {
-            offset: 3,
-            source: ParseIndexError::InvalidInteger("a".parse::<usize>().unwrap_err()),
-        };
-        assert!(err.source().is_some());
-        assert!(err.source().unwrap().is::<ParseIndexError>());
-
-        let err = AssignError::OutOfBounds {
-            offset: 3,
-            source: OutOfBoundsError {
-                index: 3,
-                length: 2,
-            },
-        };
-
-        assert!(err.source().unwrap().is::<OutOfBoundsError>());
-    }
-
     #[test]
     fn from_encoded() {
         assert_eq!(Token::from_encoded("~1").unwrap().encoded(), "~1");
@@ -478,14 +493,6 @@ mod tests {
         token == decoded
     }
 
-    #[test]
-    fn invalid_encoding_error_display() {
-        assert_eq!(
-            Token::from_encoded("~").unwrap_err().to_string(),
-            "json pointer is malformed due to invalid encoding ('~' not followed by '0' or '1')"
-        );
-    }
-
     #[test]
     fn tokens() {
         let pointer = Pointer::from_static("/a/b/c");