Introducing Fairspec

Introduction

Fairspec is an open standard for exchanging FAIR data, together with the software that implements it. It describes what a dataset contains, how its tables are shaped, who produced it and under what licence it can be reused — in plain JSON that a person can write by hand, a pipeline can generate and a CI job can validate.

Tip

The FAIR principles say data should be Findable, Accessible, Interoperable and Reusable. Fairspec turns those principles into a file format a machine can act on.

Why another standard

Datasets are published constantly and described inconsistently. The metadata that makes one reusable — column types, units, provenance, licence — usually lives in a README, a paper or somebody's memory.

Fairspec deliberately builds on two standards that already exist rather than competing with them, and gives each one a clear job:

• Metadata follows DataCite. A dataset's citation metadata — titles, creators, publisher, licence, identifiers — uses DataCite Metadata Schema 4.6, so a Fairspec dataset carries the same fields a repository needs to mint a DOI
• Data is described in JSON Schema. Table Schema and Data Schema, which describe the columns of a table and the structure of JSON data, are compatible with JSON Schema 2020-12, so the JSON Schemas you already use to validate your data work in Fairspec out of the box

Five specifications

The standard is split into five small specifications, each describing one layer of data publishing:

• Dataset — a dataset and its resources, with DataCite-compatible metadata and integrity hashes
• Table Schema — columns, types, constraints, primary and foreign keys for tabular data
• Data Schema — the structure of JSON data, compatible with JSON Schema
• File Dialect — how to read a file: CSV, TSV, JSON, JSONL, Parquet, Arrow, XLSX, ODS or SQLite
• Catalog — a JSON Lines feed for syncing collections of datasets

Every descriptor points at a versioned profile through $schema, so a validator always knows which version of the standard it is reading:

{
  "$schema": "https://fairspec.org/profiles/latest/dataset.json",
  "titles": [{ "title": "Club members" }],
  "resources": [
    {
      "data": "members.csv",
      "tableSchema": {
        "primaryKey": ["id"],
        "properties": {
          "id": { "type": "integer" },
          "joined": { "type": "string", "format": "date" }
        }
      }
    }
  ]
}

Software first

A standard is only as useful as the tools that implement it, so Fairspec ships with them:

• Python — pip install fairspec, built on Polars DataFrames — docs
• TypeScript — npm install fairspec, for Node, Deno, Bun and, for metadata, the browser — docs
• Rust — a single prebuilt fairspec binary with no runtime to install — docs
• MCP server — lets an AI assistant validate datasets, infer schemas and query tables — docs
• Desktop — a visual application for macOS, Windows and Linux; your files never leave your machine — docs

The Python and TypeScript libraries run one shared conformance suite, so a descriptor that is valid in one is valid in the other.

Performance

Fairspec validates data on Polars, the same columnar engine in all three implementations. We benchmarked it validating a generated 10 GB CSV (19.4M rows, 41 columns, 795M cells) against its Table Schema, alongside other complete validators — tools that check every cell and report each failing one. Each tool was capped at 10 GB of memory:

That is about 5× faster than the fastest rival. dataframely, Great Expectations, pandera (polars) and pointblank ran out of memory before finishing. Measured on 2026-10-28 on an AMD Ryzen 5 PRO 7545U with 32 GB of RAM; the benchmark is in the repository, so you can run it yourself.

Trying it from the terminal

Every package ships the same fairspec command. Infer a schema from a CSV file, validate the file against it, and query it with SQL:

fairspec table infer-schema members.csv --json > schema.json
fairspec table validate members.csv --schema schema.json
fairspec table query members.csv "SELECT name, score FROM self WHERE score > 80"

On macOS and Linux, the prebuilt binary is one command away:

curl -fsSL https://fairspec.org/install.sh | sh

To give an AI assistant the same abilities, add the MCP server to its configuration:

{
  "mcpServers": {
    "fairspec": {
      "command": "npx",
      "args": ["fairspec@latest", "mcp"]
    }
  }
}

What's next

Fairspec is in active development and open source under the MIT license. We are looking for feedback from anyone who publishes, curates or consumes research data. Please try it, open an issue, and star it on GitHub to help the project grow — https://github.com/datisthq/fairspec