skos-xl

SKOS-XL Skill

Skill for building and working with SKOS (Simple Knowledge Organization System) and SKOS-XL vocabularies, with first-class support for Darwin Core integration following the TDWG TAG SKOS-XL patterns.

Setup

1. Install Python 3.9+

python --version

2. Install dependencies

cd /path/to/skos-xl
pip install -r requirements.txt

One dependency: `rdflib` — handles all RDF formats (Turtle, RDF/XML, JSON-LD, N-Triples) and the SKOS namespace natively.

3. (Optional) Sync W3C schema files

Downloads the official SKOS/SKOS-XL RDF/OWL schemas and TDWG TAG examples:

python scripts/sync.py

Usage

1. Explain SKOS, SKOS-XL, and CTA properties

General SKOS overview:

python scripts/explain.py

Explain a specific SKOS term:

python scripts/explain.py --term broader
python scripts/explain.py --term prefLabel
python scripts/explain.py --term exactMatch

List all SKOS terms:

python scripts/explain.py --list

SKOS-XL overview (when to use XL vs plain SKOS):

python scripts/explain.py --xl

Explain a specific SKOS-XL term:

python scripts/explain.py --xl --term Label
python scripts/explain.py --xl --term literalForm
python scripts/explain.py --xl --list

Traditional Knowledge (CTA) properties overview:

python scripts/explain.py --cta
python scripts/explain.py --cta --list
python scripts/explain.py --cta --term accessLevel
python scripts/explain.py --cta --term sourcePeople
python scripts/explain.py --cta --term nagoyaStatus

2. Validate a SKOS vocabulary file

Validates Turtle, RDF/XML, JSON-LD, N-Triples, or N3 files.

Standard checks (always run):

1. File parses as valid RDF
2. Contains at least one skos:ConceptScheme
3. All skos:Concept instances linked via skos:inScheme
4. Each concept has skos:prefLabel (or skosxl:prefLabel)
5. No duplicate prefLabel in the same language within a scheme (S14)
6. No disjointness violations (Concept / ConceptScheme / Collection)
7. skos:related not used between broader/narrower concepts (S27)
8. SKOS-XL: each skosxl:Label has exactly one skosxl:literalForm

CTA checks (--cta flag, Traditional Knowledge / CARE / Nagoya):

1. ConceptScheme has dct:rightsHolder (CARE Authority)
2. ConceptScheme has dct:license (TK Label recommended)
3. Each skosxl:Label has etno:accessLevel
4. Labels in non-standard languages have prov:wasAttributedTo or etno:sourcePeople
5. Labels with accessLevel = restricted/sacred have etno:validatedBy or prov:wasAttributedTo

python scripts/validate.py vocab.ttl
python scripts/validate.py vocab.ttl --verbose
python scripts/validate.py vocab.ttl --cta
python scripts/validate.py vocab.ttl --cta --verbose
python scripts/validate.py vocab.rdf --format xml

Exit code 0 on success, 1 if errors are found (suitable for CI pipelines).

3. Generate a SKOS vocabulary template

Four templates are available:

Basic vocabulary (plain SKOS):

python scripts/generate.py my_vocab

Basic vocabulary with SKOS-XL labels:

python scripts/generate.py my_vocab --xl

Darwin Core controlled vocabulary (e.g. for basisOfRecord):

python scripts/generate.py basisOfRecord --template dwc-vocab

Taxonomic name vocabulary (TDWG TAG NameThing pattern, SKOS-XL):

python scripts/generate.py my_names --template dwc-names

Traditional Knowledge vocabulary (CTA / EtnoTermos pattern, CARE + Nagoya, SKOS-XL):

python scripts/generate.py etnotermos --template etno-tk
python scripts/generate.py etnotermos --template etno-tk --lang pt --dir ./output

Change output format and language:

python scripts/generate.py my_vocab --format jsonld --lang pt
python scripts/generate.py my_vocab --format rdfxml --dir ./output
python scripts/generate.py my_vocab --base http://vocab.example.org/myVocab

Supported formats: turtle (default), rdfxml, jsonld, nt, n3

4. Convert vocabulary format or label style

Convert RDF serialization format:

python scripts/convert.py vocab.rdf --to-format turtle
python scripts/convert.py vocab.ttl --to-format jsonld --output vocab.jsonld

Upgrade plain SKOS labels to SKOS-XL (adds URI resources for each label):

python scripts/convert.py vocab.ttl --to-xl

Downgrade SKOS-XL labels to plain SKOS (extracts literalForm literals back to skos:prefLabel):

python scripts/convert.py vocab_xl.ttl --from-xl

Combine operations (upgrade labels + change format):

python scripts/convert.py vocab.ttl --to-xl --to-format jsonld

5. Sync reference files

Downloads W3C SKOS/SKOS-XL schemas and TDWG TAG Turtle examples:

python scripts/sync.py

Traditional Knowledge (CTA) Vocabularies

Overview

Traditional Knowledge Associated with Biodiversity (CTA — Conhecimento Tradicional Associado à Biodiversidade) requires a vocabulary architecture that is:

• Polyglot — multiple indigenous languages, each with individual metadata
• Governed — per-label access control (public / restricted / community-only / sacred)
• Attributed — provenance traceable to the originating people (CARE principles)
• Compliant — aligned with the Nagoya Protocol on Access and Benefit-Sharing

SKOS-XL is the correct choice because access restrictions live at the label level, not at the concept level. The scientific name of a plant may be public while the sacred ritual name is restricted — granularity impossible with skos:prefLabel literals.

CARE Principles

Access levels (etno:accessLevel)

Generate the template

python scripts/generate.py etnotermos --template etno-tk --lang pt

This creates a Turtle file with:

• skos:ConceptScheme with dct:rightsHolder and dct:license (TK Label)
• Ethnotaxonomic top-level categories (not western-science categories)
• Jatobá (Hymenaea courbaril) concept with labels in Portuguese, Guarani Mbya (@gnm), and Latin — each with full CARE metadata
• Ayahuasca concept with a sacred label in Huni Kuĩ (@hux) alongside a public Spanish label — demonstrating per-label access control
• prov:Agent resources for each indigenous people
• Darwin Core dwc:vernacularName bridge on each Concept

Validate CTA compliance

python scripts/validate.py etnotermos.ttl --cta --verbose

Explain CTA properties

python scripts/explain.py --cta
python scripts/explain.py --cta --term accessLevel
python scripts/explain.py --cta --term sourcePeople
python scripts/explain.py --cta --term nagoyaStatus
python scripts/explain.py --cta --list

Key references

• CARE Principles for Indigenous Data Governance
• Nagoya Protocol — CBD
• Local Contexts TK Labels
• ISO 639-3 (indigenous language codes)
• VocBench 3 — SKOS-XL editor used by FAO/Agrovoc
• EtnoTermos — JBRJ

Darwin Core Integration

SKOS is the recommended representation for Darwin Core controlled vocabularies. Two patterns are supported by this skill:

Pattern 1 — Controlled vocabulary for DwC term values

Used for terms like basisOfRecord, occurrenceStatus, sex, lifeStage, establishmentMeans, degreeOfEstablishment, habitat:

python scripts/generate.py basisOfRecord --template dwc-vocab

Each concept maps to the authoritative TDWG IRI via skos:exactMatch.

Pattern 2 — Taxonomic name vocabulary (TDWG TAG NameThing)

Reference: tdwg/tag/skos-xl

Used for scientific names. Labels become skosxl:Label resources carrying parsed nomenclatural components:

• skosxl:literalForm — full name string (e.g. "Dicranum braunii Müll. Hal."@la)
• tnc:canonicalName — genus + epithet without authorship
• tnc:genus, tnc:specificEpithet, tnc:authorship
• skosxl:labelRelation subproperties for basionyms and orthographic variants

This resolves the dwc: / dwciri: namespace split: SKOS-XL Labels provide a single IRI-addressable resource that bridges both.

python scripts/generate.py bryophytes --template dwc-names

Key DwC Terms That Benefit from SKOS Vocabularies

References

• SKOS terms reference — 4 classes, 28 properties
• SKOS-XL terms reference — 1 class, 5 properties
• SKOS & SKOS-XL Quick Reference Guide — patterns, examples, DwC integration
• SKOS Core schema — official W3C RDF/OWL (after sync.py)
• SKOS-XL schema — official W3C RDF/OWL (after sync.py)
• TDWG TAG NameThing — Turtle example (after sync.py)
• Traditional Knowledge properties — CTA/CARE metadata properties

Related Skills

[darwin-core](../darwin-core/) — Use alongside this skill to package and validate occurrence data. Darwin Core defines the fields; SKOS defines the controlled vocabularies for the values. The dwc-vocab template generates SKOS representations of any Darwin Core controlled term.

[DataProvenance](../DataProvenance/) — Normative reference for the prov: terms (prov:wasAttributedTo, prov:Agent, qualification, prov:hadPrimarySource) already used by this skill's Traditional Knowledge (CTA) template, for provenance trails deeper than the template covers.