Front matter as the agent's index
The spec requires exactly one field. That restraint is a design decision worth taking seriously, and it says something about what metadata is actually for.
I once watched a team spend two full days designing metadata for an internal documentation system. By the end they had twenty-three fields. Owner, team, status, tier, criticality, last-reviewed, review-cadence, tags, related-systems, data-classification, and so on down a list that everybody agreed was reasonable in isolation.
Six months later I looked at what was actually in those fields across four hundred documents. Owner was populated and roughly half wrong, because people changed teams. Status was set to “draft” on documents that had been the definitive reference for a year. Last-reviewed was a lie in the specific way that dates are lies: somebody had bumped it during a compliance push without reading anything. Tags were a folksonomy with eleven spellings of “authentication.” Everything else was empty or copied from the template.
The Open Knowledge Format requires one field: type. After watching that team, and several like them, I think that is the single best decision in the spec, and it is worth understanding why one field can be more useful than twenty-three.
Metadata decays faster than prose
Here is the thing nobody says out loud about structured metadata: it rots faster than the document it describes.
Prose has a self-correcting property. When somebody reads a paragraph that is wrong, the wrongness is visible in context, and there is a reasonable chance they fix it or complain. Metadata has no such property. Nobody reads front matter. It sits above the content, gets skipped by every human eye, and its wrongness is invisible until something automated depends on it and produces a nonsensical result.
Worse, metadata fields create an obligation at write time that has no corresponding payoff at read time for the person filling them in. The author fills in criticality: tier-2 because the template demands it, guesses, and moves on. The guess is now a fact in your system.
So the rule I would offer, which the spec implicitly endorses by requiring almost nothing: a metadata field should exist only if something automated reads it, and if a wrong value would be noticed. Everything else is theatre with a maintenance bill.
Twenty-three fields
- Filled in from a template, mostly guessed
- Nothing reads most of them
- Wrong values are invisible
- Adding a concept feels like paperwork
- Decays silently and completely
One required field
- Answerable without thinking
- Read on every retrieval
- A wrong value shows up in behaviour
- Adding a concept costs one line
- Stays true because it is used
Why type is the right single field
If you get exactly one field, which one do you want?
Not owner: it changes constantly and can be derived from version control history better than it can be declared. Not status: it is a project management concept smuggled into a knowledge base, and “draft” is where documents go to live forever. Not tags: tags are a search feature, and a search feature is not a schema.
type earns the slot because it is the only field that changes how the reader should behave.
Consider what an agent does differently on encountering documents of different kinds. A metric definition is an authority: if it says churn excludes trial accounts, that is not advice, it is the answer, and disagreeing with it is a bug. A runbook is a procedure: it should be followed in order, and deviating is a decision that needs justification. A decision record is history: it explains why something is the way it is, may have been superseded, and should not be treated as a current instruction. A table description is a reference: consult the relevant part, ignore the rest.
Those are four genuinely different reading modes. Without a declared type, the model infers the genre from tone and formatting, which works most of the time and fails in exactly the cases where the document is unusual, which are exactly the cases that matter.
The spec does not hand you a vocabulary of types, which is the second restrained decision and the one that will annoy people. There is no canonical list. You pick your own values, and two organisations will pick differently.
I have gone back and forth on whether that is a gap or a feature, and I have landed on feature, narrowly. A fixed vocabulary would be wrong for somebody: a data platform team and a payments team and a games studio do not have the same categories of knowledge, and a spec that shipped a list would either be too short to be useful or too long to be learnable. Leaving it open means the vocabulary emerges from use. The cost is that portability between organisations is weaker than the word “standard” implies, which I said in the first piece of this series and will keep saying.
Front matter as the thing you read first
The functional argument for front matter, distinct from the metadata argument, is about ordering.
An agent working on a change does not read your whole knowledge base. It cannot, at any interesting scale, and it should not, because loading two hundred documents to answer one question makes the answer worse rather than better. It has to select. Selection needs something cheap to evaluate across many candidates.
That is what front matter is for, and it is why the field lives at the top of the file rather than in a sidecar or an index elsewhere. You can read the first few lines of five hundred files very cheaply. You cannot read five hundred files. Front matter is the part of a document you can afford to look at everywhere.
Notice what this loop is not. It is not embedding every chunk and asking for the nearest neighbours. There is a whole article later in this series about when curated structure beats semantic search, so I will not litigate it here, but the shape above is a different animal: it is navigation, not similarity. And navigation is auditable in a way that similarity is not, because you can ask afterwards which files were selected and why, and get an answer a person can check.
What I would add, carefully, and what I would not
Since the spec requires one field and permits others, every team will extend. Here is how I would think about it, using the rule from earlier: does something read it, and would a wrong value be noticed?
Fields that usually pass that test: a short human-readable title if the path is terse, because it improves the scan step. Some notion of what the concept supersedes or replaces, because otherwise a retired definition looks exactly like a current one. A pointer to where the authoritative source lives when the document is a summary of something else (a schema file, a config, a contract), because that is the field a validator can actually check.
Fields that usually fail it: status, because everything is draft forever. Free-text tags, because they fragment. Owner as a name, because people move and version control already knows who touched it. Review dates, because they get bumped rather than earned, and a date that is bumped rather than earned is worse than no date, since it converts “we do not know if this is current” into “somebody says this is current.”
That last example generalises into the theme of this entire series. Any field that asserts freshness without being derived from something that cannot be faked is a drift generator. If you want a document to carry a claim about its own currency, that claim has to come from a check, not from a human typing a date. This is precisely the argument GroundTruth makes about ticket status, transposed one level: a record that a person has to remember to update is a record that will be wrong, and the more official it looks, the more damage it does when it is.
Where this breaks down
One field means very little machine-checkable structure. I have spent this article praising restraint, so let me argue the other side properly. With only type required, and no defined vocabulary for it, there is almost nothing a generic tool can do with an arbitrary OKF directory beyond “these are markdown files.” Every useful behaviour depends on conventions your organisation invented, which means tooling is not really portable even though the files are. That is a genuine limitation of v0.1 and I would not paper over it.
Emergent vocabularies fragment exactly the way tags do. The argument I made against free-text tags applies uncomfortably well to an undefined type field. Nothing stops runbook, run-book, Runbook and operational-procedure coexisting in one repository. The saving grace is that there are few enough types that a person notices, whereas tags proliferate past the point of noticing. But this needs a convention and probably a validator, and again, that is on you.
Front matter is only cheap if the directory is small enough to scan. The scan-select-load loop above works nicely for a few hundred concepts. At tens of thousands it does not, and you are back to building an index, at which point you have a system again and some of the no-platform purity evaporates. The format does not tell you where that threshold is. My guess is that most teams hit it later than they fear, but it exists.
The spec is v0.1 and extensions written today may conflict with what it standardises later. If you invent a supersedes field and the spec later defines one with different semantics, you own a migration. Keep custom fields few and easy to rewrite, and prefer putting information in the prose where a reader can use it over inventing a field only your scripts understand.
And the maintenance point, once more. Every field you add is a field that can be wrong. A knowledge base with rich, stale metadata is more dangerous than one with thin, accurate metadata, because automation trusts fields more literally than it trusts prose. If you cannot say what reads a field and how you would notice it being wrong, do not add it.
The takeaway
Front matter is not a place to describe a document. It is the part of a document that can be read everywhere, which makes it the index an agent navigates by. That is why it belongs at the top of the file, and why it should stay small enough that nobody skips it.
Requiring exactly one field is a bet that the useful metadata is the metadata something reads, and that everything else is a maintenance liability collected in the name of completeness. Based on how metadata actually behaves over time, that bet looks right.
The next piece takes the other structural claim in the spec seriously: that ordinary markdown links turn a directory into a graph, and what that graph can and cannot do for an agent trying to understand a change.