Model Cards: How to Document a Machine Learning Model So Others Use It Safely

Model cards are short, structured documents that travel with a machine learning model and explain what it does, how it was tested, where it works well and where it should not be used. They give anyone who picks up the model, from a colleague to a customer, the context they need to use it responsibly. This guide explains where model cards came from, what a good one contains, and how to write your first one in about an hour using a simple template.

Where model cards came from

The idea was set out in the 2019 paper Model Cards for Model Reporting by Margaret Mitchell and colleagues, presented at the FAT* conference on fairness, accountability and transparency. The authors argued that trained models were being released without a standard way to explain their performance characteristics, even as they were used in sensitive areas.

Their proposal was a short document to accompany each released model. Two elements stand out. First, a model card should report benchmarked evaluation across a variety of conditions, including results broken down by relevant groups and their intersections, not just one overall score. Second, it should spell out the intended use context, so readers know where the model belongs and where it does not. The paper illustrated the format with two examples: a smile-detection model and a toxic-comment classifier.

Why model cards are worth the effort

• They prevent misuse by accident. Most harmful uses of a model are not malicious; someone simply applies it to data it was never tested on. A clear “out-of-scope uses” section catches many of these.
• They make hand-offs easier. When the person who trained a model moves on, the card keeps the knowledge about its data, limits and quirks.
• They support review. Product, legal, security and ethics reviewers can read one page instead of reverse-engineering a notebook.
• They make models easier to find and compare. On public model hubs, structured metadata lets people filter by task, language or dataset.

What a good model card contains

Hugging Face’s model card documentation, which builds on the Mitchell paper, says a card should describe the model, its intended uses and potential limitations including biases and ethical considerations, the training parameters and experimental information, the datasets used, and the evaluation results. Turning that into practical sections gives you the following outline.

1. Model details

Name, version, date, owner or team, model type and architecture, and a one-paragraph plain-language summary of what the model does. Include a contact route for questions.

2. Intended use

State the primary use cases and the intended users. Be specific: “ranking incoming support tickets for English-language customers” is more useful than “text classification”.

3. Out-of-scope uses

List the uses you have not tested or would advise against. This is often the most valuable section in the whole card, because it is the one that stops someone from making an expensive mistake.

4. Training data

Describe where the data came from, the time period it covers, how it was labelled, and any known gaps. If you cannot share the data itself, describe it well enough that a reader can judge whether it resembles their own.

5. Evaluation

Report the metrics you used, the test data, and the results. Following the original paper, break results down by the groups and conditions that matter for the use case, such as language, region, device type or image quality. Note the decision threshold if the model outputs probabilities.

6. Limitations, risks and recommendations

Be honest about where performance drops, which inputs confuse the model, and what a responsible deployment should include, such as human review for low-confidence predictions.

7. How to use the model

A short code snippet or API example, the expected input format, and any pre-processing steps. Small details, such as image size or text normalisation, cause many silent failures.

Model cards on Hugging Face

If you publish models on the Hugging Face Hub, the model card is the repository’s README.md file. According to the documentation, it combines human-readable Markdown with a block of YAML metadata at the top. That metadata can record fields such as the language, the datasets used, the library, the base model for fine-tuned versions, the pipeline task, and structured evaluation results under model-index. Filling in the metadata helps people find your model when they filter the Hub, and it keeps evaluation numbers in a machine-readable form.

Even if your models never leave your company, borrowing this structure is a good idea: keep the card in the same repository as the model code, version it alongside the model, and update it every time you retrain.

How to write your first model card in an hour

1. Copy the seven-section outline above into a MODEL_CARD.md or README.md next to the model.
2. Write the intended use and out-of-scope sections first. They take the least research and deliver the most value.
3. Pull evaluation numbers from your latest test run rather than from memory, and add a breakdown for at least one relevant grouping.
4. Ask someone outside the team to read it. If they cannot explain what the model is for and when not to use it, revise the card.
5. Add a “last updated” date and a changelog line, and make updating the card part of your release checklist.

A short example of model cards in practice

Here is how the key sections might read for an internal ticket-triage model:

• Intended use: ranks new English-language support tickets by urgency for the support team’s queue. A person always makes the final call.
• Out of scope: tickets in other languages; legal or billing disputes; any automated action taken without human review.
• Training data: labelled tickets from the past two years, with urgency marked by senior support staff.
• Evaluation: precision and recall for the “urgent” class on a held-out month, reported separately for web-form and email tickets.
• Known limitations: lower recall on very short tickets; performance not yet measured on chat transcripts.

Five lines like these already answer most of the questions a new user would ask.

Who should write and own model cards

The person who trained the model should write the first draft, because they know the data and the evaluation best. But a card works better as a shared document than as one engineer’s notes:

• The model owner keeps the technical sections accurate and updates them on every retrain.
• The product owner checks that the intended and out-of-scope uses match how the model is actually being used.
• A reviewer from outside the team reads the card before release and flags anything unclear or missing.

Agree who signs off a card before a model ships, in the same way you agree who approves a code change. That one rule keeps model cards from becoming an afterthought.

Common mistakes to avoid

• Only reporting the best number. A single headline metric hides weak spots. Include breakdowns.
• Writing for experts only. The people most likely to misuse a model are those who did not build it. Use plain language.
• Letting the card go stale. An out-of-date card is worse than none, because readers trust it.
• Leaving out what you did not test. “Not evaluated on X” is useful information.

Model cards pair naturally with group-by-group fairness checks; see our AI ethics and bias hub for practical methods. The machine learning hub covers the evaluation basics a card reports on.

Key takeaways

Model cards are one-page records that explain what a model is for, how it was trained and tested, and where it falls short. The original research recommends evaluation broken down by relevant groups and a clear statement of intended use, and platforms such as Hugging Face build on that with a standard README and metadata format. Start with intended and out-of-scope uses, report results honestly with breakdowns, keep the card next to the model, and update it every time the model changes.

Written by the TechZone AI Editorial desk.