jon.recoil.org
RFC6901 JSON Pointer implementation in OCaml using jsont
Update root.opam dependencies and sync changes
- Update root.opam with external dependencies for monorepo build
- Sync dune/boot/libs.ml changes
- Sync ocaml-json-pointer doc updates
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
+1
-1
doc/index.html
+1
-1
doc/index.html
···
1
-
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>tutorial (tutorial)</title><meta charset="utf-8"><link rel="stylesheet" href="odoc.css"><meta name="generator" content="odoc 3.1.0"><meta name="viewport" content="width=device-width,initial-scale=1.0"><script src="highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script><script async src="x-ocaml.js" src-worker="x-ocaml.worker.js" src-load="libs.js" crossorigin="anonymous"></script><style>
1
+
<!DOCTYPE html><html xmlns="http://www.w3.org/1999/xhtml"><head><title>tutorial (tutorial)</title><meta charset="utf-8"><link rel="stylesheet" href="odoc.css"><meta name="generator" content="odoc %%VERSION%%"><meta name="viewport" content="width=device-width,initial-scale=1.0"><script src="highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script><script async src="x-ocaml.js" src-worker="x-ocaml.worker.js" src-load="libs.js" crossorigin="anonymous"></script><style>
2
2
body {
3
3
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
4
4
max-width: 900px;
+1
-1
doc/odoc.css
+1
-1
doc/odoc.css
+1
-1
doc/tutorial.html
+1
-1
doc/tutorial.html
···
1
1
<!DOCTYPE html>
2
-
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>tutorial (tutorial)</title><meta charset="utf-8"/><link rel="stylesheet" href="odoc.css"/><meta name="generator" content="odoc 3.1.0"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">Index</a> » tutorial</nav><header class="odoc-preamble"><h1 id="json-pointer-tutorial"><a href="#json-pointer-tutorial" class="anchor"></a>JSON Pointer Tutorial</h1><p>This tutorial introduces JSON Pointer as defined in <a href="https://www.rfc-editor.org/rfc/rfc6901">RFC 6901</a>, and demonstrates the <code>json-pointer</code> OCaml library through interactive examples.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#json-pointer-vs-json-path">JSON Pointer vs JSON Path</a></li><li><a href="#setup">Setup</a></li><li><a href="#what-is-json-pointer?">What is JSON Pointer?</a></li><li><a href="#syntax:-reference-tokens">Syntax: Reference Tokens</a><ul><li><a href="#the-index-type">The Index Type</a></li><li><a href="#invalid-syntax">Invalid Syntax</a></li></ul></li><li><a href="#evaluation:-navigating-json">Evaluation: Navigating JSON</a><ul><li><a href="#the-root-pointer">The Root Pointer</a></li><li><a href="#object-member-access">Object Member Access</a></li><li><a href="#array-index-access">Array Index Access</a></li><li><a href="#empty-string-as-key">Empty String as Key</a></li><li><a href="#keys-with-special-characters">Keys with Special Characters</a></li><li><a href="#other-special-characters-(no-escaping-needed)">Other Special Characters (No Escaping Needed)</a></li><li><a href="#error-conditions">Error Conditions</a></li><li><a href="#array-index-rules">Array Index Rules</a></li></ul></li><li><a href="#the-end-of-array-marker:---and-type-safety">The End-of-Array Marker: <code>-</code> and Type Safety</a><ul><li><a href="#navigation-vs-append-pointers">Navigation vs Append Pointers</a></li><li><a href="#why-two-pointer-types?">Why Two Pointer Types?</a></li><li><a href="#creating-append-pointers-programmatically">Creating Append Pointers Programmatically</a></li></ul></li><li><a href="#mutation-operations">Mutation Operations</a><ul><li><a href="#add">Add</a></li><li><a href="#ergonomic-mutation-with-any">Ergonomic Mutation with <code>any</code></a></li><li><a href="#remove">Remove</a></li><li><a href="#replace">Replace</a></li><li><a href="#move">Move</a></li><li><a href="#copy">Copy</a></li><li><a href="#test">Test</a></li></ul></li><li><a href="#escaping">Escaping Special Characters</a><ul><li><a href="#the-library-handles-escaping-automatically">The Library Handles Escaping Automatically</a></li><li><a href="#escaping-in-action">Escaping in Action</a></li><li><a href="#unescaping">Unescaping</a></li><li><a href="#the-order-matters!">The Order Matters!</a></li></ul></li><li><a href="#uri-fragment-encoding">URI Fragment Encoding</a></li><li><a href="#building-pointers-programmatically">Building Pointers Programmatically</a><ul><li><a href="#pointer-navigation">Pointer Navigation</a></li></ul></li><li><a href="#jsont-integration">Jsont Integration</a><ul><li><a href="#typed-access-with-path">Typed Access with <code>path</code></a></li><li><a href="#default-values-with-~absent">Default Values with <code>~absent</code></a></li><li><a href="#nested-path-extraction">Nested Path Extraction</a></li><li><a href="#comparison:-raw-vs-typed-access">Comparison: Raw vs Typed Access</a></li><li><a href="#updates-with-polymorphic-pointers">Updates with Polymorphic Pointers</a></li></ul></li><li><a href="#summary">Summary</a><ul><li><a href="#key-points-on-json-pointer-vs-json-path">Key Points on JSON Pointer vs JSON Path</a></li></ul></li></ul></nav></div><div class="odoc-content"><h2 id="json-pointer-vs-json-path"><a href="#json-pointer-vs-json-path" class="anchor"></a>JSON Pointer vs JSON Path</h2><p>Before diving in, it's worth understanding the difference between JSON Pointer and JSON Path, as they serve different purposes:</p><p><b>JSON Pointer</b> (<a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a>) is an <em>indicator syntax</em> that specifies a <em>single location</em> within JSON data. It always identifies at most one value.</p><p><b>JSON Path</b> is a <em>query syntax</em> that can <em>search</em> JSON data and return <em>multiple</em> values matching specified criteria.</p><p>Use JSON Pointer when you need to address a single, specific location (like JSON Schema's <code>$ref</code>). Use JSON Path when you might need multiple results (like Kubernetes queries).</p><p>The <code>json-pointer</code> library implements JSON Pointer and integrates with the <code>Jsont.Path</code> type for representing navigation indices.</p><h2 id="setup"><a href="#setup" class="anchor"></a>Setup</h2><p>First, let's set up our environment. In the toplevel, you can load the library with <code>#require "json-pointer.top";;</code> which will automatically install pretty printers.</p><pre class="language-ocaml"><code># Json_pointer_top.install ();;
2
+
<html xmlns="http://www.w3.org/1999/xhtml"><head><title>tutorial (tutorial)</title><meta charset="utf-8"/><link rel="stylesheet" href="odoc.css"/><meta name="generator" content="odoc %%VERSION%%"/><meta name="viewport" content="width=device-width,initial-scale=1.0"/><script src="highlight.pack.js"></script><script>hljs.initHighlightingOnLoad();</script></head><body class="odoc"><nav class="odoc-nav"><a href="index.html">Up</a> – <a href="index.html">Index</a> » tutorial</nav><header class="odoc-preamble"><h1 id="json-pointer-tutorial"><a href="#json-pointer-tutorial" class="anchor"></a>JSON Pointer Tutorial</h1><p>This tutorial introduces JSON Pointer as defined in <a href="https://www.rfc-editor.org/rfc/rfc6901">RFC 6901</a>, and demonstrates the <code>json-pointer</code> OCaml library through interactive examples.</p></header><div class="odoc-tocs"><nav class="odoc-toc odoc-local-toc"><ul><li><a href="#json-pointer-vs-json-path">JSON Pointer vs JSON Path</a></li><li><a href="#setup">Setup</a></li><li><a href="#what-is-json-pointer?">What is JSON Pointer?</a></li><li><a href="#syntax:-reference-tokens">Syntax: Reference Tokens</a><ul><li><a href="#the-index-type">The Index Type</a></li><li><a href="#invalid-syntax">Invalid Syntax</a></li></ul></li><li><a href="#evaluation:-navigating-json">Evaluation: Navigating JSON</a><ul><li><a href="#the-root-pointer">The Root Pointer</a></li><li><a href="#object-member-access">Object Member Access</a></li><li><a href="#array-index-access">Array Index Access</a></li><li><a href="#empty-string-as-key">Empty String as Key</a></li><li><a href="#keys-with-special-characters">Keys with Special Characters</a></li><li><a href="#other-special-characters-(no-escaping-needed)">Other Special Characters (No Escaping Needed)</a></li><li><a href="#error-conditions">Error Conditions</a></li><li><a href="#array-index-rules">Array Index Rules</a></li></ul></li><li><a href="#the-end-of-array-marker:---and-type-safety">The End-of-Array Marker: <code>-</code> and Type Safety</a><ul><li><a href="#navigation-vs-append-pointers">Navigation vs Append Pointers</a></li><li><a href="#why-two-pointer-types?">Why Two Pointer Types?</a></li><li><a href="#creating-append-pointers-programmatically">Creating Append Pointers Programmatically</a></li></ul></li><li><a href="#mutation-operations">Mutation Operations</a><ul><li><a href="#add">Add</a></li><li><a href="#ergonomic-mutation-with-any">Ergonomic Mutation with <code>any</code></a></li><li><a href="#remove">Remove</a></li><li><a href="#replace">Replace</a></li><li><a href="#move">Move</a></li><li><a href="#copy">Copy</a></li><li><a href="#test">Test</a></li></ul></li><li><a href="#escaping">Escaping Special Characters</a><ul><li><a href="#the-library-handles-escaping-automatically">The Library Handles Escaping Automatically</a></li><li><a href="#escaping-in-action">Escaping in Action</a></li><li><a href="#unescaping">Unescaping</a></li><li><a href="#the-order-matters!">The Order Matters!</a></li></ul></li><li><a href="#uri-fragment-encoding">URI Fragment Encoding</a></li><li><a href="#building-pointers-programmatically">Building Pointers Programmatically</a><ul><li><a href="#pointer-navigation">Pointer Navigation</a></li></ul></li><li><a href="#jsont-integration">Jsont Integration</a><ul><li><a href="#typed-access-with-path">Typed Access with <code>path</code></a></li><li><a href="#default-values-with-~absent">Default Values with <code>~absent</code></a></li><li><a href="#nested-path-extraction">Nested Path Extraction</a></li><li><a href="#comparison:-raw-vs-typed-access">Comparison: Raw vs Typed Access</a></li><li><a href="#updates-with-polymorphic-pointers">Updates with Polymorphic Pointers</a></li></ul></li><li><a href="#summary">Summary</a><ul><li><a href="#key-points-on-json-pointer-vs-json-path">Key Points on JSON Pointer vs JSON Path</a></li></ul></li></ul></nav></div><div class="odoc-content"><h2 id="json-pointer-vs-json-path"><a href="#json-pointer-vs-json-path" class="anchor"></a>JSON Pointer vs JSON Path</h2><p>Before diving in, it's worth understanding the difference between JSON Pointer and JSON Path, as they serve different purposes:</p><p><b>JSON Pointer</b> (<a href="https://datatracker.ietf.org/doc/html/rfc6901">RFC 6901</a>) is an <em>indicator syntax</em> that specifies a <em>single location</em> within JSON data. It always identifies at most one value.</p><p><b>JSON Path</b> is a <em>query syntax</em> that can <em>search</em> JSON data and return <em>multiple</em> values matching specified criteria.</p><p>Use JSON Pointer when you need to address a single, specific location (like JSON Schema's <code>$ref</code>). Use JSON Path when you might need multiple results (like Kubernetes queries).</p><p>The <code>json-pointer</code> library implements JSON Pointer and integrates with the <code>Jsont.Path</code> type for representing navigation indices.</p><h2 id="setup"><a href="#setup" class="anchor"></a>Setup</h2><p>First, let's set up our environment. In the toplevel, you can load the library with <code>#require "json-pointer.top";;</code> which will automatically install pretty printers.</p><pre class="language-ocaml"><code># Json_pointer_top.install ();;
3
3
- : unit = ()
4
4
# open Json_pointer;;
5
5
# let parse_json s =