Designing Datasets for LLM Consumption: 7 Rules We Learned the Hard Way

YJTOON has shipped a few hundred reference datasets. Most of the early ones were re-edits of existing tables from RFCs and standards bodies. The rewrites taught us a few things.

1. Name columns the way a model would search for them

If a column could plausibly be called id, identifier, or code, pick one and document it. Models are pattern matchers; ambiguity costs you an extra grounding round per query.

2. Units in the column name or type tag, not in a README

timeout_ms beats timeout + a separate units document. size[bytes] is unambiguous even when truncated.

3. Stable row order is not a feature

Consumers will sort, hash, and diff. Add an explicit ordinal or a sort key column instead of relying on insertion order.

4. Provenance per row, not per file

Even a source_url column with one repeated value is better than a top-of-file comment. Row-level provenance survives transforms.

5. Avoid mixed cardinalities

If a column is "sometimes a list, sometimes a scalar," the parser will win, the model will lose. Pick one and document the empty case.

6. Cap the human-readable excerpt

Long free-text cells burn tokens and confuse grounding. If a description is longer than ~240 characters, link out instead of embedding.

7. Treat the dataset as a public API

Once it is in a model's context, every column name and every value is part of the surface. Renames are breaking changes. Document them.

These are not laws. They are the bias we apply when a dataset feels wrong but we cannot yet say why.