# Model cards

A model card is a short document describing a model's intended use, data, evaluation, limitations and risks, so users can judge whether it fits their needs.

## Overview

A model card is a short, structured document that describes a machine learning model: what it does, who built it, what data it learned from, how it was evaluated, where it works well, where it does not, and what risks users should know about. It travels with the model, so anyone deciding whether to use it can judge its fitness for their purpose without reading the code or the training logs.

An everyday picture: the nutrition and allergy label on packaged food. It does not tell you how the factory works, but it tells you what is inside, how much, and who should avoid it. A model card is that label for an AI model. A hospital, a bank or a developer picking a model from a hub can see quickly whether it was tested on people like their users, what it should not be used for and how it performed across different groups.

Model cards are now common practice. Model hubs display them for every model, cloud platforms offer templates, large model releases come with detailed cards or system cards, and regulations increasingly expect similar documentation. Their value depends entirely on honesty and specificity: a card that lists only strengths is marketing, not documentation.

## What it is

The original proposal defined a set of sections that most templates still follow, with some additions.

| Section | What it records |
|---|---|
| Model details | Name, version, date, developers, model type, licence, contact |
| Intended use | The primary uses and users, and uses that are out of scope |
| Factors | Groups, environments and conditions that may affect performance, such as demographic groups or image quality |
| Metrics | Which measures were used and why, with decision thresholds and uncertainty |
| Evaluation data | Datasets used for testing, why they were chosen and how they were processed |
| Training data | Sources, size, collection and filtering, as far as can be shared |
| Quantitative analyses | Results overall and broken down by the factors above |
| Ethical considerations | Sensitive data, risks of harm, mitigations taken |
| Caveats and recommendations | Known limitations and advice for users |

Modern cards often add sections on environmental impact (compute and emissions), safety evaluations, how to get started, and links to related documentation such as datasheets for the training data.

## Where it came from

Model cards were proposed in the paper "Model Cards for Model Reporting" by Margaret Mitchell, Timnit Gebru and colleagues, mostly at Google, first posted in October 2018 and presented at the ACM Conference on Fairness, Accountability and Transparency in 2019. The paper argued that models should ship with documentation of performance across different conditions and groups, and showed example cards for a smile detection model and a text toxicity model. A companion idea from the same period, "Datasheets for Datasets", proposed similar documentation for training data.

The idea spread quickly. Google published cards for some of its cloud models and released a Model Card Toolkit. Hugging Face made the model card, written as the repository's README with structured metadata, the default page for every model on its hub. Cloud platforms such as [SageMaker](/tools/sagemaker) added model card features. Large language model developers began publishing longer "system cards" covering safety testing.

Regulation has followed the same direction. The [EU AI Act](/tools/eu-ai-act) requires technical documentation for high-risk AI systems and documentation obligations for providers of general-purpose AI models. A model card is not automatically sufficient for these duties, but it is a natural starting point.

## How it works

### Step 1: decide the audience

A card for engineers choosing a model differs from one for a risk committee or the public. Many teams write one card with a plain summary at the top and technical detail below.

### Step 2: gather facts during development

The best cards are written alongside the work, not at the end. Experiment trackers such as [MLflow](/tools/mlflow) or [Weights & Biases](/tools/weights-and-biases) hold data versions, metrics and parameters that feed the card directly.

### Step 3: define intended and out-of-scope use

This is often the most important section. It states plainly what the model is for, who should use it and which uses are unsupported, for example "not for decisions about individual employment".

### Step 4: evaluate across factors

Results are reported overall and for relevant subgroups and conditions, with uncertainty where possible. A model with 94 per cent accuracy overall but 78 per cent on one group must say so.

### Step 5: document limitations and risks

Known failure modes, sensitivity to input quality, risks of misuse and mitigations are written in concrete terms.

### Step 6: publish, version and maintain

The card is stored with the model and versioned with it. Each new model version gets an updated card. On a model hub, structured metadata at the top of the card makes licence, language and tasks searchable.

```markdown
---
license: apache-2.0
language: en
tags: [text-classification]
---
Ticket Router v3

Intended use: routes English support tickets to one of 12 queues. Not for legal or medical triage.
```

## Key concepts and terms

| Term | Meaning |
|---|---|
| Intended use | The purposes and users a model was designed and tested for |
| Out-of-scope use | Uses the developers advise against or did not test |
| Factor | A condition or group that may change performance |
| Disaggregated evaluation | Reporting results separately for each group or condition |
| Datasheet | Documentation describing a dataset's origin, content and limits |
| System card | Extended documentation for a whole AI system, often including safety testing |
| Card metadata | Structured fields, such as licence and tags, read by tools and hubs |
| Caveat | A known limitation users must take into account |
| Provenance | Where data and model components came from |
| Versioning | Keeping a separate card for each model version |

## A worked example

This scenario is illustrative. A clinic network builds a model that flags chest X-rays for urgent radiologist review.

1. **Model details:** convolutional network, version 2.1, trained in September 2026, licence internal, owner the imaging team.
2. **Intended use:** prioritising the review queue for adult chest X-rays in the network's hospitals. Out of scope: diagnosis without a radiologist, children under 16, images from portable machines older than 2015.
3. **Data:** 210,000 images from five hospitals over six years, labelled by two radiologists each, with disagreements resolved by a third.
4. **Results:** sensitivity 0.93 and specificity 0.81 overall. Broken down, sensitivity is 0.95 for fixed machines and 0.86 for portable machines, and similar across sex and age bands from 16 to 80. Over 80, it falls to 0.88.
5. **Limitations:** lower performance on portable images and the oldest patients; not tested on images from outside the network.
6. **Recommendations:** use only as a prioritisation aid; monitor sensitivity monthly; re-evaluate before any new hospital joins.

A reviewer reading this card can see at once that a new site using mostly portable machines needs its own evaluation first.

## Strengths and limitations

**Strengths:**

- Makes a model's purpose, limits and risks visible to non-developers.
- Encourages disaggregated evaluation, which surfaces hidden weaknesses.
- Supports informed model selection on hubs and in procurement.
- Provides a base for governance and regulatory documentation.
- Cheap to produce compared with the cost of misuse.

**Limitations:**

- Quality depends on honesty; there is no automatic check.
- Cards can become out of date when models are retrained.
- Training data details may be withheld for commercial or privacy reasons.
- A card describes a model, not the full system it is used in.
- Readers may treat a card as a guarantee rather than a description.

## How it compares with alternatives

| Document | Focus | Relationship to model cards |
|---|---|---|
| Model card | One model's use, data, results and limits | The core document |
| Datasheet for datasets | A dataset's origin and contents | Feeds the training data section |
| System card | A whole AI system, including safety | Broader, often for large models |
| Regulatory technical documentation | Legal obligations, for example under the EU AI Act | Can reuse much of a model card |
| [Data catalog](/tools/data-catalog) entry | Discovery of data assets | Links datasets to models |

## Practical guidance and best practices

1. Write the card during development, using tracked metadata, not from memory at the end.
2. State out-of-scope uses as clearly as intended uses.
3. Report results by relevant subgroups and conditions, with uncertainty.
4. Use plain language in the summary so non-specialists can understand it.
5. Version the card with the model and update it on every release.
6. Include known failure examples, not only aggregate metrics.
7. Link to datasheets, evaluation reports and monitoring dashboards.
8. Have someone outside the building team review the card before publication.

## Common mistakes

- Listing only headline metrics without any subgroup breakdown.
- Leaving "limitations" empty or filling it with generic phrases.
- Copying a template and never updating it after retraining.
- Omitting out-of-scope uses, so users assume anything is allowed.
- Describing training data vaguely when more detail could safely be shared.
- Treating the card as legal compliance in itself.

## Frequently asked questions

### Who should write a model card?

The team that built the model, because it knows the data and evaluation best, with input from people who understand the domain, risks and audience. A review by someone outside the team improves clarity and honesty.

### How long should a model card be?

Long enough to answer what the model is for, how it was tested and where it fails. Many good cards are one to three pages, with links to detailed reports. Large general-purpose models often need much longer documentation.

### Is a model card required by law?

Not as such. But laws such as the EU AI Act require documentation for certain AI systems and general-purpose models, and a model card can supply much of that content. Check the specific obligations that apply to your case.

### What is the difference between a model card and a system card?

A model card describes one model. A system card describes a whole system, such as a chat assistant built from models, filters and tools, and often focuses on safety testing and mitigations.

### Where are model cards stored?

Usually next to the model: in the model repository, the registry or the hub page. On Hugging Face, the card is the README file of the model repository, with metadata at the top.

## Glossary

- Disaggregated metrics: results reported separately for each subgroup.
- Model hub: a website that hosts models and their cards, such as [Hugging Face](/tools/hugging-face).
- Front matter: structured metadata at the top of a card file.
- Sensitivity: the share of true positive cases a model correctly flags.
- Specificity: the share of true negative cases a model correctly clears.
- Governance: the processes that decide how models are approved and used.
- Provenance: the documented origin of data and models.

## Summary

A model card is a concise, structured description of a model's purpose, data, evaluation, limitations and risks, so that users can decide whether it suits their needs. Proposed by Mitchell, Gebru and colleagues in 2018 and now standard on model hubs and cloud platforms, cards also underpin governance and regulatory documentation such as that required under the [EU AI Act](/tools/eu-ai-act). Their value comes from specific, honest content, especially clear out-of-scope uses and results broken down by group, kept up to date with every model version.