A Format I Was Already Using
Blog post #64
Since April I have kept a personal health wiki. Blood work, supplements, what my gut does and does not tolerate, my daughter’s legs, my wife’s iron. It is a folder of markdown files. I dictate notes into a raw/ folder, an AI compiles them into wiki/, and I never edit the wiki by hand. That rule has held for five months.
Today started with kefir. I had a glass at ten in the evening from a carton that had been open a few days, and my stomach objected. I asked whether the carton mattered. It does. Kefir keeps fermenting in the fridge, so an opened carton is fizzier and higher in histamine than a fresh one. The answer went into the wiki like everything else.
Then I asked whether the wiki should follow Google’s Open Knowledge Format, which came out over the summer.
What shipped
The wiki now conforms to OKF v0.2. Thirteen documents, zero errors, a small checker script that says so.
OKF is Google Cloud’s attempt to standardise the thing people have been building for a year: a directory of markdown files with YAML frontmatter, meant to be read by agents without a translation step. The spec fits on a page. One field is mandatory, type. Two filenames are reserved, index.md and log.md. Everything else is a concept document.
The migration was one afternoon. Frontmatter on every article, a change log rebuilt from git history, the to-do list broken out of the index because the spec says an index is links and nothing else.
The part that was already done
There was very little to do. The wiki already had an index with one-line summaries. Every article ended with a sources section listing the raw files it was compiled from, and articles linked to each other with ordinary markdown links.
None of that came from a spec. It came from wanting to answer “where did this claim come from” six months later. Google apparently felt the same pressure, because their format encodes the same three things. It turns out the thing I had been doing has a name.
The field I did not fill in
OKF has a verified field. It records that a human looked at a document and confirmed it, with a name and a date. It is optional. You could stamp it on everything and nobody would stop you.
I stamped it on three documents out of thirteen.
Those three are the ones I had corrected. In August the wiki said I was taking Niferex for my iron. I was not. That was my wife’s box. Mine was SiderAL, a different form, a different dose, and the difference mattered for a question about whether coffee blocks it. I caught that and fixed it, and the fix is a human review event, so those documents carry verified: human:stefan.
The other ten do not. I dictated the raw notes that fed them, but dictating is not reviewing. The compiled article can draw a conclusion I would not draw, or be wrong in a way I have not noticed yet. Marking it verified because the input was mine would make the field mean nothing.
So the wiki now records, in a machine-readable way, that most of it has not been checked. That is the honest state, and it is the one I want. The next time I ask it a question, it can tell me the answer rests on unreviewed material, and I have written that into its instructions.
There is a similar field, stale_after, for content with an expiry date. My ferritin is due to be retested in November. My vitamin D level was measured in summer and will not hold in January. Two documents got a date. The rest got nothing, because I could not name a real one, and a made-up date is worse than none.
Decisions made
I skipped about half the spec. There is a whole section on attested computations, receipts, executors, proof that a number came from a particular query. It is built for finance teams querying BigQuery. It has no bearing on a folder about my digestion.
I also left out the resource field on every article. It is meant to point at the underlying asset a document describes, a table, an endpoint. A health article has no underlying asset. It is the asset. Leaving it blank produced thirteen warnings in the checker until I wrote down why, and then it produced none.
Tooling & process
Afterwards I joked that the project was now Google-certified and would look good on my CV.
It is not certified. There is no certification. The spec has a conformance section, and I wrote a sixty-line script that checks my files against it, and that is the entire ceremony. Google publishes the format and takes no position on who follows it.
The phrasing that survives an interview is the accurate one: a personal knowledge base in Google’s Open Knowledge Format, with automated conformance checking. It is a smaller claim. It is also one where the interesting part is visible, which is that I set the trust fields honestly instead of setting them everywhere.
What’s unclear
Whether the format lasts. It is at 0.2 and moved repositories once already. If it changes, the frontmatter changes, and the wiki has a script for that too.
Also whether the kefir thing holds up. The advice was to drink it in the morning, from a fresh carton, in smaller amounts. I will find out this week, and it will go in the wiki, unverified.
— Stefan