Comprehend or Look Up: A Criterion for YAML vs JSON After AI Started Writing Files
Abstract
Choosing between YAML and JSON is usually settled by asking who writes the file. Hand-maintained configuration gets YAML, because YAML holds comments and tolerates loose hand-editing; machine-generated state gets JSON, because JSON parses identically everywhere and has no optional syntax to get wrong. The rule is sound, and it worked for a long time, but it worked for a reason that has quietly stopped holding. Authorship predicted readership: files people wrote were files people read. Once an assistant drafts a file that only humans will ever read, the two come apart, and a criterion built on authorship starts giving wrong answers. The better question is what the human reader is doing with the file. Reading to comprehend needs comments, ordering, and whitespace. Reading to look up a value needs none of them. Machine writing still matters, but as a threat to comments rather than as the thing that decides whether comments are wanted.
The Standard Criterion
Most projects settle the question by sorting files into two piles. On one side sit the files a person maintains by hand: linter settings, CI definitions, deployment manifests. These get YAML. On the other side sit the files a program emits: lockfiles, caches, indexes, audit logs. These get JSON or JSON Lines.
The reasoning is straightforward. YAML permits comments, and comments are how a maintainer explains a setting whose purpose is not obvious from its name. YAML also forgives the things hands get wrong — a trailing comma, an unquoted string — which matters when the edit is made at 2 a.m. between two other tasks. JSON offers neither, and in exchange gives a grammar with no optional parts, parsers in every standard library, and no dependency to install.
A repository I work in had drifted into exactly this split without anyone writing the rule down. Configuration files were YAML. A deduplication index, a thread index, a term list for speech recognition, and an append-only provenance log were all JSON or JSONL. Six files, two piles, no policy document. The convention had assembled itself because the criterion was doing real work.
Why Authorship Stopped Predicting Readership
I recently added a small file to that repository. Its job was to record which version of a document had been sent out, on what date, to which recipients, and with what checksum for the attachment. Nineteen lines. I wrote it in YAML with a short header comment explaining what belonged in the file and, more importantly, what did not.
Then the file’s owner asked a question I could not answer with my own rule. The file was written by an assistant and would be maintained by one. By the authorship criterion it belonged in the machine pile, and machine-written files get JSON. Yet JSON was obviously the wrong choice, and I could not say why without abandoning the criterion I had just used to justify the decision.
His answer was that the criterion is not who writes the file but whether a person reads it.
That is right, and the reason it is right is worth stating precisely. A comment does nothing for the person writing it. At the moment of writing, the author already knows why the field is there; that is what it means to be the author. A comment is a message addressed forward in time to someone who will open the file without that context. Whether a format can carry comments is therefore a question about the file’s readers. Filing it under authorship works only as long as the author and the reader are the same population, which is what the old rule silently assumed.
Assistants break the assumption in a specific direction. They produce documents intended for human comprehension without a human having composed them. The number of such files is going up. Any heuristic that infers a file’s purpose from how it came into existence will degrade at the same rate.
Reading to Comprehend, Reading to Look Up
“Does a person read it” is closer, but on its own it is too coarse, and the repository contains its own counter-example.
One of the JSONL files there is a provenance log: one record per factual claim in a document, each recording where the claim came from and how strongly it is attested. People do read it. It is cited by name in the document it supports, and when a number is disputed that file is where the dispute gets settled. By a plain readership criterion it should be YAML. It should not be, and the reason is what the reading consists of. Nobody opens a provenance log at the first line and works downward to understand it. They arrive with a claim in hand and search for the matching record. The reading is a lookup against a stream of homogeneous records, and JSON Lines is the right shape for that: one self-contained object per line, greppable, appendable, parseable in any language without a dependency.
So the criterion needs one more cut. What matters is not whether a person reads the file but what the reading is for.
| Reading is for | What it needs | Format |
|---|---|---|
| Comprehension — what is this file, what belongs in it, why is this field here | Comments, meaningful ordering, whitespace | YAML |
| Lookup — retrieve this checksum, find the record matching this claim | Stable parsing, no dependency, uniform records | JSON / JSONL |
Under this test the release-state file resolves cleanly. Its header comment records a decision: the file does not list what changed between versions, because git diff between two tags already answers that question and answers it correctly forever. Copying a change list into the file would create a second source of truth that drifts the moment someone edits the document and forgets the file — and nothing would catch the drift. That reasoning is the most valuable thing in the file, and it is precisely the part JSON cannot hold. The file exists to be understood, not merely queried.
Machine Writing Is a Risk, Not a Criterion
Machine writing does not drop out of the analysis. It changes role.
Readership determines whether comments have value. Machine writing determines whether they survive. Most YAML serializers, including the standard Python one, discard comments entirely on round-trip: the data is preserved perfectly, the explanation vanishes, and no error is raised. A build step that reads the file, updates one field, and writes it back will strip the header on its first run, and nothing in the output will indicate that anything was lost.
This gives an ordering rather than a competition between two rules. Ask first whether a human reads the file for comprehension. If not, comments have no value and the question does not arise. If so, ask whether a program will ever rewrite the file in place. If it will, either move to JSON and put the explanation in a README, or keep YAML and constrain the program to append rather than rewrite. Deciding format by machine-writability alone inverts the order and answers a question about risk before establishing whether there is anything at risk.
This is also the axis on which the present question differs from format transparency, which asks whether a reader — increasingly a machine one — can recover semantic content from the bytes at all. YAML and JSON both pass that test completely. The choice between them is settled one level down, among formats that are already transparent, by what the human reader intends to do next.
Conclusion
The old rule was not wrong. It was a proxy that worked while authorship and readership travelled together, and it is coming apart because assistants now write documents for people to read. Replacing it costs nothing, because the replacement was the thing the proxy was standing in for: comments serve readers, so ask about readers.
Two questions, in order. Does a person read this file to understand it, or to retrieve a value from it? If to understand it, will a program ever rewrite it? The first question decides the format. The second decides whether that choice needs defending against a serializer that will quietly discard the reason the file was written that way.