An open format for identification keys
Taxonomic knowledge as data, not prose.
Clavis is a JSON format for identification keys. It stores which taxa a key separates, which traits can be observed, and how often each taxon shows each trait. Any viewer can turn that into a key; any tool can read it back. Developed at the Norwegian Biodiversity Information Centre and published in PLOS ONE.
// one statement: ravens are always all black { "id": "statement:raven_all_black", "taxon": "taxon:corvus_corax", "character": "character:plumage", "value": "state:all_black", "frequency": 1 }
The core unit of a Clavis key. A whole key is a list of these, plus the taxa, characters and states they point to.
The format
Four building blocks
A Clavis file is plain JSON validated against a published schema. Everything a key knows is expressed with four kinds of object. There are no branches and no fixed order of questions: a user answers whatever they can observe, and the candidate list shrinks.
Taxa
What the key distinguishes. A flat list or a tree (family → genus → species), each taxon optionally linked to an external taxonomy service by ID.
Characters
The questions. Each is about exactly one observable trait, such as "Body length" or "Iris color", and can carry images and a description.
States
The answers to a character: "pale" / "dark", or numeric bins with units like "under 40 cm". States are exclusive by default; a character can be flagged non-exclusive.
Statements
The scores. One per taxon–character–state, with a frequency from 0 to 1: how often that taxon shows that state. 0.05 means rare, not never.
Polythetic, not dichotomous
A printed key forces one path. In Clavis every character is independent, so a specimen with a missing tail or a torn wing is still identifiable by the traits that are there.
Inheritance, no overrides
A trait that holds for every member of a group is stated once on the group. A member may not restate a character its parent already answers; the file is invalid if it does. That keeps keys small and keeps contradictions out.
Sparse by design
Unknown or irrelevant combinations are simply left unscored. A viewer only asks questions that still separate the remaining candidates, so users see a handful of relevant questions instead of a wall of them.
Try a key
Dragonflies, in the Clavis viewer
This is the open web viewer running a published key: the 55 dragonflies and damselflies of Norway, machine-translated from the Norwegian original. Answer in any order; the viewer only asks what still separates the remaining candidates. The same component runs in the editor and in the national species app.
Key: Øyenstikkere (Odonata, Norway), English demo translation, CC BY 4.0, from the Clavis keys collection. Images load from Artsdatabanken.
What the format carries
More than a matrix
Clavis was designed to hold everything a real, publishable key needs, at a level of detail beyond earlier key formats, while staying easy to validate and easy to write by hand.
Frequencies
Every statement carries a value from 0 to 1. Variation, rarity and "usually" are data, not footnotes.
Numerical values
Characters can take measurements with any unit and step size, not just categorical states.
Multilingual
A key declares its languages as ISO 639-1 codes. Titles, descriptions, URLs and even images can differ per language.
Hierarchical taxa
Taxa nest to any depth. Sub-endpoints let a species split further into sexes, life stages or forms.
External services
Taxa reference registers such as NorTaxa or GBIF by ID, so names stay current and keys can be combined.
Geography
The region a key is valid for, as machine-readable GeoJSON and as a name.
Logical premises
A character can depend on earlier answers: only ask about wing venation once the user has said there are wings.
User requirements
A statement can declare what the user needs: a hand lens, a microscope, a specimen in hand.
Media
Images and other media on the key, on taxa, characters and states, with credits and licences.
Descriptions
Short, extended and external descriptions on taxa and characters, for viewers that want to teach as well as identify.
Follow-up keys
An endpoint can hand over to another key, so large groups can be built up from smaller, maintained pieces.
Provenance
Creators, contributors, publisher, source, licence, dates and a stable identifier are part of the file, not the website around it.
Tools
Make it, show it, serve it
Open source, MIT licensed, and built to be used independently of each other. The format is the contract between them.
Viewer
Clavis viewer for the web
A React component that takes any valid Clavis JSON and renders a working key: questions, images, candidate list, endpoints. It is what runs inside the editor and inside the Norwegian species-identification app. Drop it into your own site with one import.
npm install @artsdatabanken/clavis-viewer-web import { ClavisViewer } from "@artsdatabanken/clavis-viewer-web"; <ClavisViewer clavis={key} lang="en" />
Editor
Clavis editor
A browser interface for making keys without touching JSON. Build the taxon tree, define characters and states, score the matrix, attach images, and test the key live in the viewer as you go. Wired to the Norwegian taxonomy register for names and IDs; export gives you the Clavis file.
Schema
Clavis JSON Schema
The format itself, as a versioned JSON Schema. Validate a key with any standard validator before publishing it. The paper describes every element; the schema is the authority.
Keys
A growing collection
Published Clavis keys, CC BY 4.0, ready to load into any viewer. From dragonflies to cold-water corals.
Server
Key routing
A small Express service that serves each key by its stable identifier: the JSON at /key/<uuid>, the standalone viewer at /viewer, and the editor at /editor. One Docker image, one URL scheme, the same key in every interface.
Pipeline
clavis-pipeline
Skills, agents and scripts that let an AI agent turn books and other sources into a checked Clavis key, with every statement traced to a quote. See From books to keys.
Pipeline
From books to keys
An open, agentic pipeline that turns field guides, scanned books, Word documents and existing keys into a checked Clavis key, with every statement traced back to a quote in the source.
Most curated identification knowledge still sits in printed books, in prose. The pipeline is a set of skills and scripts that an AI coding agent follows from start to finish: give it a taxon and its sources, and it delivers a key a taxonomist can review and edit. It is tested in Claude Code; other agents that read AGENTS.md should work but are untested.
The strict structure of Clavis is what makes this checkable. Agents do the reading; scripts do the counting. A run is not done until measured gates pass: every quote is found word for word in its book, every claim ends up in the key or is skipped with a reason, every species pair the sources can separate is separated, and nothing is lost in the merge. Judgment calls are logged so an expert can dispute them without rerunning anything.
Tested with Opus 5.5 running the job and Sonnet 5.5 for the agents. A 24-taxon key from five printed field guides and a matrix key took 73 minutes, about USD 56 at API prices; a 47-taxon key from one Word document took 46 minutes, about USD 19. On a subscription that is a few dollars. Reports from other models and harnesses, including local ones, are welcome.
Clone https://github.com/Artsdatabanken/clavis-pipeline, read its AGENTS.md, and make a Clavis key for <taxon> from <sources>.
- 1Species listTaken from the national taxonomy register, with accepted names and synonyms.
- 2PrepareText from each source, one file per taxon in reading order, figures cut out. Scanned books are OCR'd.
- 3HarvestOne agent per source lists every observable claim, taxon by taxon, with a verbatim quote and page. It never sees a key.
- 4DigitizeCharacters and states are designed from the claims; every statement records the claims it rests on. Measurements stay numerical ranges.
- 5AuditA fresh agent checks the key against the claims and the claims against the book, and fixes what it finds.
- 6MergeSources are combined by meaning, not wording. A round-trip proves every source statement survives or is logged as removed.
- 7Make it usableEvery state must be answerable by one person with one specimen and the guide. Fine shades merge only if no species pair loses its last way apart.
- 8GatesMeasured checks and a token and cost report. The run loops until the required gates pass.