Method

How the climate taxonomy became a FAIR vocabulary, in plain words. The whole method is one R script, build_fair.R, in the repository. Running it again rebuilds everything on this site.

Starting point

The taxonomy already existed as version 5: a master spreadsheet, checked and built into one JSON file with 739 concepts, their definitions and sources, synonyms, parent terms, typed relations, and the rules that say when a term counts as adaptation or mitigation. Each concept had a stable identifier such as CRK_102. What it did not have was a web address, a standard format, a licence, or a published way to change it.

What we did

1. Copied the source files into this repository. Copies only; the originals stay where they are. source/SOURCES.md lists each file, where it came from, its date and its checksum.
2. Gave every term a web address. The identifier stays the same; the address is the identifier after terms/. The address is provisional and will become https://w3id.org/cgiar/climate-taxonomy/ID later.
3. Translated each field into SKOS, the web standard for vocabularies: the term becomes the preferred label, synonyms become alternative labels, the definition and its source are kept, the parent becomes the broader term, the facet becomes a collection, and the condition under which a term counts becomes a scope note. The typed relations (addresses, produces, and so on) have no SKOS equivalent, so they are defined in a small companion file.
4. Kept the retired identifiers. The 23 identifiers retired in version 5 are still in the vocabulary, marked deprecated and pointing to their successor, so old reports stay readable.
5. Wrote the vocabulary in three formats: Turtle and JSON-LD for machines, CSV for spreadsheets.
6. Made one web page per term, plus this site. Each page shows the term for a reader and embeds the same data for a machine.
7. Checked the result with a second script, qa/check_skos.R: unique identifiers, a label and a definition for every term, every parent and relation target exists, no loops in the hierarchy, and the files parse back correctly. Nineteen checks, all passing.
8. Published. The site is served by GitHub Pages from the repository. Each version is a tagged release with the files attached, and a test deposit was made in Zenodo Sandbox to try the citation step.

Files created

What the documents say

LICENSE.md

Proposes CC BY 4.0: anyone may copy, share and build on the vocabulary, including commercially, as long as they credit the source and say if they changed it. Marked as proposed until the custodian confirms. Explains why attribution rather than public domain: many definitions cite IPCC, AGROVOC, FAO, WMO or UNFCCC and that credit should stay visible. States that Lexicon icons are not part of the vocabulary and not covered.

GOVERNANCE.md

Names the custodian (the Climate Adaptation Activator team). Says anyone in CGIAR may propose to add, change, merge or retire a term, through a term request form. Describes the five screening questions (is it already here, is it one concept, does it have a sourced definition, is it used, where does it sit). Sets the rules that never change: identifiers are never reused, retired terms are deprecated not deleted, a definition may improve without the identifier moving. Explains numbered releases.

CITATION.cff

A small machine readable file that GitHub reads to show a "Cite this repository" button: title, version, date, authors, licence, and the test DOI.

CHANGELOG.md

Generated from the version 4 to version 5 comparison files: how many terms were added, retired, renamed or redefined, and the lists of added, retired and renamed terms.

source/SOURCES.md

For each copied file: where it came from, when, and its checksum, so a copy can always be traced and refreshed.

A worked example of the request route

To show the route working, one term request was run end to end on 23 September 2026: issue #1, Climate-resilient agriculture. It was proposed with the form, screened against the five questions in a public comment, and refused: the concept is already covered by Climate resilience (which has "climate-resilient" as a synonym) and Climate-smart agriculture, and the label is a compound of the two rather than one concept. The requester was pointed to those two terms. The decision is logged in governance/decisions.csv. Because nothing in the vocabulary changed, no new version was made. An accepted request follows the same steps and then adds: edit the source, rebuild, check, release. Under fifteen minutes from proposal to logged decision.

What is provisional

The web address (a permanent namespace comes next), the licence (CC BY 4.0, proposed), the DOI (a test one), and registration in a vocabulary repository. None of these change a term identifier.

Next steps, not done yet

1. Confirm the licence and the custodian with the taxonomy lead. Everything else below can then stop being marked provisional.
2. Register a permanent namespace at w3id.org (one pull request to their repository). Then change one line in the script and rebuild; all term identifiers stay the same and the old addresses redirect.
3. Make a real release (version 5.0.0, not draft) and deposit it in the real Zenodo, which gives a permanent DOI for the vocabulary and one per version.
4. Register in AgroPortal (agroportal.lirmm.fr), the vocabulary repository for agriculture. This is where people in this field look for vocabularies. It gives search, browsing, version history, and a place to record mappings to AGROVOC. The Turtle file is what gets submitted.
5. Add mappings to other vocabularies: which of our terms equal or are close to terms in AGROVOC, and later in the MELIAF taxonomy. In SKOS these are exactMatch, closeMatch and broadMatch links. This is the one FAIR test still open that is not about registration.
6. Serve machine formats at the term address itself. Today a term address returns a web page with the data embedded. Better practice is that the same address returns Turtle or JSON-LD when a program asks for it. The w3id redirect rules can do this.
7. Record the vocabulary in CGIAR systems: a CGSpace record pointing to the DOI, and CLARISA so that PRMS and other tools can reference it.
8. Complete examples of use. 157 of 739 terms have a real CGIAR example sentence. The tagging results can supply the rest.
9. Move the hosting to wherever the MELIAF build-shop decides, once that is known. With the permanent namespace in place nothing that cites a term breaks.

Using the same method for another vocabulary

Replace the JSON file in source/, adjust the list of fields at the top of build_fair.R, and run it. The matching, the pages, the checks and the publishing steps stay the same. This is the method the MELIAF build-shop can reuse for the next domain vocabulary.