Dataset Schema: Getting Your Data Found in Dataset Search

Dataset schema is the schema.org Dataset type, added to a dataset's landing page as JSON-LD so that Google Dataset Search and other crawlers can identify what the data is, who produced it, how it is licensed and where to download it. Two properties are required, name and description. Everything else is recommended, and the recommended properties are where discoverability is won or lost.

This matters most to people who publish data rather than sell products: universities, statistical agencies, research groups, open-data portals, nonprofits and companies releasing benchmark files. A dataset is not a page type that ordinary web search understands well. A CSV has no headline, no readable summary and no obvious author. Markup turns a bare file and a loosely written page into a record that a dataset-specific index can filter by topic, format, licence, coverage and date.

The rest of this post covers the properties worth filling in, how to describe downloads and licensing, how the page has to be published for the markup to be used, and the mistakes that quietly keep datasets out of the index.

What Dataset Search Reads and Why It Needs Markup

Google Dataset Search is a separate search interface from the main results page. It indexes descriptions of datasets, not the data files themselves. When it finds a page carrying Dataset structured data, it extracts the metadata, groups records that describe the same dataset, and shows a summary with links back to the source. The data is never copied into Google; the landing page stays the destination.

Google's documentation describes Dataset markup as the way to make datasets eligible for this experience, and notes that datasets can also surface in regular search features. Nothing guarantees either outcome. Markup makes a page eligible and legible; it does not promise a listing, a position or a particular display. Treat it the way you would treat any structured data: a clear statement of facts the page already makes visibly, not a lever.

There is also a practical reason beyond Google. Schema.org Dataset is a widely shared vocabulary, and other harvesters, repositories and research tooling read the same properties. A landing page with clean Dataset markup is useful to every crawler that understands the vocabulary, which is why research libraries and government portals were early adopters.

The rule that governs everything below is that the markup must describe what a visitor can actually see on the page. If the JSON-LD claims a licence, a coverage period or a file format that the visible page never mentions, you have created a mismatch that is both a guideline problem and a trust problem for anyone relying on the record.

The Properties That Carry the Weight

The two required properties are name and description. The name should be the title a researcher would recognise, specific enough to distinguish this dataset from its siblings: "Hourly Air Quality Readings, Monthly Extracts, 2015 to 2022" rather than "Air Quality Data". Google's guidance for the description is a summary of the dataset, between 50 and 5000 characters. Use that room to state what was measured, how many records there are, what each row represents and what the data cannot be used for.

After those two, the properties below do most of the work. Not every one applies to every dataset, and filling a property with guesses is worse than leaving it out.

• creator: the person or organisation responsible, typed as Person or Organization, with a url or identifier such as an ORCID iD or ROR ID where one exists. Dataset Search surfaces authorship, and unnamed datasets are harder to trust and to cite.
• license: a URL to the licence text, for example a Creative Commons deed or an open-data licence. A plain-text phrase like "free to use" is not machine-readable and does not tell a reuser what they may do.
• keywords: a short list of topic terms, in the vocabulary your field actually uses. This is metadata for filtering, not a place to repeat the title ten times.
• temporalCoverage and spatialCoverage: the period the data covers, in ISO 8601 form such as 2015-01-01/2022-12-31, and the place it describes, either as a name or as a Place with geographic coordinates or a shape. These let someone searching for regional or historical data find you.
• variableMeasured: the quantities or columns in the data. For a survey or sensor table this is the closest thing to a schema for the content itself, and it is often what lets a researcher decide in seconds whether the dataset has the field they need.
• measurementTechnique: how the values were obtained, such as a survey instrument, sensor type or processing method. Useful for judging fitness for purpose.
• identifier: a persistent identifier, most commonly a DOI written as a full https URL. It helps Google and others recognise that two records describe the same dataset.
• isAccessibleForFree: true or false, stated honestly, so that users are not sent to a login wall they did not expect.
• citation, funder, version, dateModified and url: provenance and versioning details that make a record citable and let users see whether they are looking at the latest release.

Describing Downloads With Distribution

The distribution property is how you tell a crawler where the actual files are. It takes one or more DataDownload objects, each with a contentUrl pointing at the file and an encodingFormat naming its type, such as text/csv, application/json or application/zip. If the same data is published as CSV and as a Parquet file, list two DataDownload entries rather than hiding one behind the other.

Be realistic about what a distribution entry means. It should point at something a visitor can retrieve, or at a stable access point for it. If the data sits behind a request form or an API key, say so in the description and set isAccessibleForFree accordingly, and do not list a contentUrl that only returns an error page. Google's documentation also covers datasets that are not directly downloadable, so a landing page that explains how to obtain the data can still be valid; what it cannot be is misleading about access.

For datasets split into many files, such as one file per year, you have two reasonable options. Describe the whole collection as one Dataset and list the files in distribution, or describe the collection with hasPart pointing to child Dataset records, with each child having isPartOf referencing the parent. The second approach suits cases where each part has its own coverage, identifier or licence. Whichever you choose, keep the relationship consistent, because inconsistent parent and child records are a common source of duplicate listings.

Licensing, Provenance and Citation

Licence information is the property that most separates a usable dataset record from a merely visible one. Researchers filtering for reusable data often need to know in advance whether they can redistribute it, adapt it or use it commercially. A licence URL answers that without a click-through to a PDF.

Put the licence in two places: the license property in the markup, and plain visible text on the page. If the data combines material under different terms, describe the dominant licence in markup and explain the exceptions in the visible page, because a single property cannot express a mixed arrangement. Do not mark a dataset as openly licensed when only part of it is.

Provenance works the same way. Use creator for who produced the data, funder for who paid for it, sameAs for other authoritative records of the same dataset, such as a repository entry, and citation for the paper that describes it. These links let a reader, and a crawler, trace the dataset back to something established.

A point that catches publishers who use repositories: if your dataset lives in an institutional repository or a DOI-minting service, the repository page may already carry Dataset markup. Check what it emits before adding your own copy on a separate site. Two landing pages for one dataset compete, and the goal is a single canonical description that the DOI resolves to.

A Worked JSON-LD Example

Here is the structure for a fictional municipal dataset, described in prose so you can map it onto your own. The JSON-LD block sits in the head or body of the landing page, typed as Dataset, with the context set to schema.org.

The name reads "City Bike Share Trips, 2019 to 2023". The description says the dataset contains one row per completed trip, with start and end stations, timestamps, duration and user type, that personal identifiers have been removed, and that stations opened after a given month appear only from that point. The creator is the city's transport department as an Organization with its website. The license is a URL to a Creative Commons Attribution deed. The temporalCoverage is 2019-01-01/2023-12-31, and the spatialCoverage is the city name.

The distribution lists two DataDownload entries: a CSV per year bundled in a zip archive, and a JSON API endpoint, each with an encodingFormat. The variableMeasured array names trip duration, start station, end station and user type. An identifier holds the dataset's DOI as a URL, and isAccessibleForFree is true.

Everything in that description is also written in visible text on the page: a summary, a licence statement, a coverage note, a table of fields and download buttons. That duplication is deliberate. The markup is a structured copy of the page, and if a reader cannot find a fact on the page, it probably should not be in the markup.

Publishing the Page So the Markup Gets Used

Markup only helps if the page can be crawled, rendered and indexed. The landing page must not be blocked in robots.txt, must not carry a noindex directive, and should return a normal 200 response. If the markup is injected by JavaScript, it needs to survive rendering, which you can confirm by inspecting the rendered HTML in a URL inspection tool rather than the raw source.

Give each dataset its own stable landing page with a canonical URL, instead of listing dozens of datasets on one scrolling catalogue page. A catalogue can still exist for humans, but the description of each dataset belongs on an address that can be linked, cited and indexed separately. For a catalogue of many items, an XML sitemap listing the landing pages helps discovery, especially for new additions that nothing links to yet.

If you publish a catalogue page that lists many datasets, you can describe it with a DataCatalog and link each dataset back with includedInDataCatalog. That is optional, but it gives aggregators a clear way to see that your datasets belong to one publisher.

Test the markup before you publish and again afterward. Google's Rich Results Test and the Schema Markup Validator will flag syntax errors and missing required properties. Search Console can also report on Dataset structured data for pages it has processed, which helps you notice when a template change silently breaks the JSON-LD across hundreds of pages. A template is the right level to fix: generate the JSON-LD from your repository or database fields so it cannot drift from the data.

Common Mistakes That Keep Datasets Out

The same handful of errors account for most failed implementations. Go through this list against your own landing pages.

• Marking up a page that is not a dataset. A blog post about data, a news article with a chart or a product page is not a Dataset. The type is for the collection of data itself.
• Thin descriptions. A description that repeats the title, or a single short sentence, gives nobody a reason to click and gives Google little to work with. Write for a researcher deciding whether to spend an afternoon on the file.
• Markup that contradicts the page. Different coverage dates, a licence that does not match the visible statement or download links that no longer work.
• Hiding the landing page behind a login or a script-only viewer. If crawlers cannot reach a stable, readable page, there is nothing to index.
• Duplicating one dataset across several sites without a clear canonical source, or creating a new landing page for every version instead of a versioned page with a clear current release.
• Stuffing keywords into name, description or keywords. It reads badly in a dataset-specific interface where people scan many similar records side by side.
• Letting records go stale. If the data is updated but dateModified, version and temporal coverage are never changed, the record misleads the people who filter by date.

Is It Worth It for Your Data?

The return on Dataset markup depends on whether your audience searches for data at all. For a research group, a statistical office or an open-data portal, dataset discovery is often the main way strangers find and cite the work, and the effort is an afternoon of template work. For a company that publishes a single benchmark file to support a report, it is still cheap and worthwhile if the file is meant to be cited.

For data that is private, paywalled without any public description, or only useful inside one product, the markup has little to offer, and you should not pretend otherwise by marking up a marketing page as a dataset.

Because there is no published figure for how often any given dataset is found, measure it the usual way: watch impressions and clicks for the landing pages in Search Console, watch referrals from datasets-related sources in your analytics, and track citations and downloads. If a template update improves the completeness of your records, those numbers will tell you over a few weeks whether anyone noticed.