darwin-core

Darwin Core Skill

Skill for working with Darwin Core and its related standards maintained by TDWG:

• DwC-A — Darwin Core Archive (star-schema ZIP format; existing tooling)
• DwC-CM — Darwin Core Conceptual Model (ratified 2026-05-26; semantics of class relationships)
• DwC-DP — Darwin Core Data Package (ratified 2026-05-26; relational tabular format extending Frictionless Data)

Setup

1. Install Python 3.9+

Make sure Python 3.9 or later is installed:

python --version

2. Install dependencies

cd /path/to/darwin-core
pip install -r requirements.txt

3. (Optional) Sync references

To download the latest Darwin Core term definitions:

python scripts/sync.py

Usage

1. Explain the Darwin Core standard

General overview:

python scripts/explain.py

Explain a specific term:

python scripts/explain.py --term occurrenceID
python scripts/explain.py --term decimalLatitude

List all available terms:

python scripts/explain.py --list

2. Validate a Darwin Core Archive

Validates a DwC-A (.zip) checking structure, terms, and data:

python scripts/validate.py occurrences.zip

Detailed validation:

python scripts/validate.py occurrences.zip --verbose

3. Generate a DwC-A template

Creates a basic Darwin Core Archive structure:

python scripts/generate_template.py my_project --dir ./output

Generate with Event core (default: Occurrence):

python scripts/generate_template.py my_project --core event --dir ./output

Generate with Taxon core:

python scripts/generate_template.py my_project --core taxon --dir ./output

4. Map CSV columns to DwC terms

Analyzes a CSV and suggests mappings to Darwin Core terms:

python scripts/map_columns.py data.csv

Generate a new CSV with DwC headers:

python scripts/map_columns.py data.csv --output mapped.csv

Interactive mode (confirm each suggestion):

python scripts/map_columns.py data.csv --interactive

5. Sync references

Updates term definitions and extensions from official sources:

python scripts/sync.py

References

• Complete Darwin Core term list — 216 terms
• Detailed term metadata — 457 unique terms with full definitions
• DwC Extensions guide — All GBIF-registered extensions
• Darwin Core Text Guide — Official DwC-A spec (meta.xml format)
• Darwin Core Conceptual Model — DwC-CM classes and relationships (ratified 2026-05-26)
• Darwin Core Data Package Guide — DwC-DP spec, descriptor format, table schemas (ratified 2026-05-26)

Known Darwin Core Extensions

This skill knows about all GBIF-registered extensions (https://rs.gbif.org/extensions.html), including:

See references/EXTENSIONS.md for full details.

Darwin Core Conceptual Model (DwC-CM)

Ratified 2026-05-26. Provides semantics of relationships between DwC classes — the missing piece since Darwin Core's inception. Technology-agnostic (relational DB, document DB, graph DB all valid).

Full reference: references/CONCEPTUAL_MODEL.md

DwC-CM Classes (quick reference)

Key design points:

• Occurrence, Survey, OrganismInteraction are specializations of Event — not combinable in one Event
• Events nest (parent/child); one child has only one parent
• MaterialSample omitted from DwC-CM; use MaterialEntity (derived from another MaterialEntity)
• OrganismInteraction has by (actor) and with (target) links to Occurrence
• NucleotideAnalysis → Identification → inferred Occurrence (for eDNA/metabarcoding)

Darwin Core Data Package (DwC-DP)

Ratified 2026-05-26. Extends Frictionless Data Package spec as the reference implementation of DwC-CM. Replaces DwC-A's star-schema constraint with arbitrary relational FK graphs.

Full reference: references/DATA_PACKAGE_GUIDE.md

File structure

datapackage.json   # Required descriptor
eml.xml            # Optional EML metadata
event.csv          # One or more DwC-DP table CSV files
occurrence.csv
...

Descriptor (datapackage.json) required fields

{
  "profile": "http://rs.tdwg.org/dwc-dp/1.0/dwc-dp-profile.json",
  "resources": [
    {
      "name": "event",
      "path": "event.csv",
      "profile": "tabular-data-resource",
      "mediatype": "text/csv",
      "schema": {
        "fields": [...],
        "primaryKey": ["eventID"],
        "foreignKeys": [
          {
            "fields": "parentEventID",
            "predicate": "happened during",
            "reference": { "resource": "", "fields": "eventID" }
          }
        ]
      }
    }
  ]
}

Rules

• Table name MUST be a reserved name from the profile (event, occurrence, agent, etc.)
• Field descriptors MUST include name, title, description, type, dcterms:isVersionOf
• foreignKeys.predicate documents relationship semantics (e.g., "happened during", "conducted by")
• Self-referencing FK: "resource": ""
• Compression: gzip only (.gz); datapackage.json always at root, never individually compressed
• Copy field descriptors from http://rs.tdwg.org/dwc-dp/1.0/table-schemas for guaranteed compliance

Key URLs

• Profile: http://rs.tdwg.org/dwc-dp/1.0/dwc-dp-profile.json
• Table schemas: http://rs.tdwg.org/dwc-dp/1.0/table-schemas
• Designer: https://gbif.github.io/dwc-dp/designer/
• QRG: https://gbif.github.io/dwc-dp/qrg/

DwC-DP vs DwC-A

Related Skills

[skos-xl](../skos-xl/) — Use alongside this skill to define the controlled vocabularies for Darwin Core term values (e.g. basisOfRecord, occurrenceStatus, habitat) as SKOS RDF. Also supports the TDWG TAG NameThing pattern for representing taxonomic names with full nomenclatural provenance.

[DataProvenance](../DataProvenance/) — Use alongside this skill to record the lineage of a DwC-A/DwC-DP dataset: which activity (import, georeferencing, QC pass) generated or transformed which records, and which agent (collector, data manager, institution) is responsible, following the W3C PROV model.