AoAH Day 16: Vibesplaining JSON Pointers using OCaml/Javascript / Dec 2025
After the successful
I decided to build a JMAP email client implementation in
OCaml that I need for myself Being a professor is not accurately measured by research or teaching outputs, but by how overloaded your INBOX is.
OCaml has superb tooling to help with this; it can not only compile to efficient native code but also to JavaScript and WASM that runs standalone in the browser. I turned to my colleagues
Today's work resulted in an ocaml-json-pointer (RFC6901) implementation along with an interactive notebook tutorial that bundles the entire OCaml compiler toolchain alongside it. There's even another one for Yaml just to illustrate how easy this is to replicate once we've built the first one.
Why do we need to vibesplain specifications?
I first began by informally scanning the JMAP RFCs with a cup of tea, and noticing that it needed support for something called JSON Pointer. I know nothing about this, and so I used my Claude Internet RFC skill to sketch out an OCaml implementation based on the specification.
This is straightforward, but I didn't know how to evaluate the generated interface for fitness since I'm not familiar with the topic. Ideally, I could use the coding agent to explain JMAP pointers to me by using the generated OCaml code illustratively so I could do a code review of its output at the same time as educating myself. For this to work, we would have to machine check the generated documentation and code to make sure it all compiles. This seems like a really good use to put coding agents to!
I dub vibesplaining as using an agent to generate executable code and an executable tutorial that can be interacted with by the prompter in order to assist with both understanding the code and iterating on the implementation.
When writing Real World OCaml about a decade ago, we built it using a tool called mdx that allowed for embedding OCaml sections within a Markdown document. Mdx can compile these markdown documents by executing the embedded OCaml, and promote the outputs directly into the document itself. You can see an example in the Guided Tour chapter where every single OCaml phrase has been machine generated.
Executable OCaml documentation within OCaml comments
Upon consulting
I had never even looked at the tooling for this aspect of odoc, but
(mdx
(files index.mld bib.mli)
(libraries bib bytesrw astring))
This stanza handles the build logic for odoc and mdx to interface and extract executable code out of interfaces files like:
(** ...
Use {! decode} to read your Bibtex data and {! encode} to write
it. For example, here is a little program to format a Bibtex file
from a string.
{@ocaml[
open Bytesrw
let format s =
let reader = Bytes.Reader.of_string s in
let writer = Bytes.Writer.of_out_channel Out_channel.stdout in
Bib.encode (Bib.decode reader) writer
]}
You can then use it with something like:
{@ocaml[
# format "@string{ hello=world }";;
@string{
hello=world
}
- : unit = ()
]}
OCaml inception right here! The # at the start of the fragment indicates that it's an OCaml toplevel phrase, otherwise it's library code.
Vibesplaining a JSON pointer tutorial
I used this expert knowledge to then vibesplain up a tutorial.mld, which is a standalone ocamldoc fragment that explains JSON Pointers to me. Here's an illustrative fragment:
From RFC 6901, Section 1:
{i JSON Pointer defines a string syntax for identifying a specific value
within a JavaScript Object Notation (JSON) document.}
In other words, JSON Pointer is an addressing scheme for locating values
inside a JSON structure. Think of it like a filesystem path, but for JSON
documents instead of files.
For example, given this JSON document:
{x@ocaml[
# let users_json = parse_json {|{
"users": [
{"name": "Alice", "age": 30},
{"name": "Bob", "age": 25}
]
}|};;
val users_json : Jsont.json =
{"users":[{"name":"Alice","age":30},{"name":"Bob","age":25}]}
]x}
The JSON Pointer [/users/0/name] refers to the string ["Alice"]:
{@ocaml[
# let ptr = of_string_nav "/users/0/name";;
val ptr : nav t = [Mem "users"; Nth 0; Mem "name"]
# get ptr users_json;;
- : Jsont.json = "Alice"
]}
This tutorial is not only available in the code repo, but it's also present in the generated HTML library documentation for the JSON Pointer library as well. It will, for example, appear on the central ocaml.org if this package is ever submitted to the official package repository.
Interactive vibesplaining with JavaScript
However, the tutorial would be even useful to me if it was fully interactive so
I can mess around with it while learning the codebase.
Being a webcomponent, using x-ocaml is as simple as including a script header and adding
an <x-ocaml> tag with the OCaml code. The only extra thing I needed was to create a Dockerfile to install my local library
into a separate opam switch and then run the x-ocaml shell script to generate the libraries blob.
We still need to compile our odoc source tutorial into HTML with the right x-ocaml tags.
$ odoc compile <file.mld>
$ odoc html-generate page-file.odoc -o .
$ odoc support-files -o
I then used my <x-ocaml> tags. I've published this as a odoc-xo binary. This then sit inside some dune rules in my JSON Pointer repository to automate the conversion from mld to interactive Javascript. You can see the promotion rules here; I'll wrap them into a Claude skill later this week.
You can browse the interactive tutorial
here for JSON Pointer, which I
found very useful to exploring the specification interactively. I did have a
quick go at compiling my earlier
Reflections
There are still a few tooling rough edges to smooth out here, but nothing that can't be automated with a Claude skill and some more binaries like odoc-xo. In
More generally, what I find fascinating about agentic skills is that once you apply a template somewhere, it can be reused very quickly. It took me a few hours and a lot of input from
These tutorials aren't high quality writing, especially compared to one where I've really thought it through and spent time on for specific teaching outcomes. However, agent generated "vibesplained" tutorials can also be very personalised even if not redistributed. For example, I want to know about recent advances in TCP, and so I am feeding the agent my mirage-tcpip stack and the latest RFCs, and requesting a tutorial about new concepts that I might have missed in recent years. Having the capability to provide contexts and generate executable tutorial notebooks is a new capability I've discovered today.
This does, of course, depend on having a high quality baseline of documentation in my dependent libraries, and of exemplar human-written rules and documentation. Thank you to