BirdLife Schema

Language-agnostic data contract schemas for the BirdLife open-source ecosystem.

Overview

This repository defines the canonical data shapes for bird observation and biodiversity data across all BirdLife community tools. Built on Apache Avro for schema evolution and interoperability.

Namespace: tech.birdlife.schema

Resolution API

Need deterministic IDs without running your own registry? Use the Resolution API:

# Taxon → always same UUID for same scientific name
curl "https://birdlife.tech/api/v1/taxon/resolve?name=Erithacus+rubecula"

# Location → deduplicated by coordinates (~11m precision)
curl -X POST https://birdlife.tech/api/v1/location/resolve \
  -H "Content-Type: application/json" \
  -d '{"name": "Minsmere", "latitude": 52.2456, "longitude": 1.6234}'

All API responses are validated against this schema.

Installation

# Install globally for CLI access
npm install -g birdlife-schema

# Or install locally in your project
npm install birdlife-schema

CLI Usage

Validate data against a schema

# Validate a single file
birdlife-schema validate taxon my-taxon.json

# Validate with JSON output (for CI/scripts)
birdlife-schema validate observation data.json --json

Output:

Validating my-taxon.json against taxon schema...

✓ Valid: 1 record(s)

Error example:

Validating bad-data.json against taxon schema...

✗ Invalid: 1 record(s)

  Record 0 (123):
    - slug: expected "string"
    - taxonRank: expected enum value

List available entities

birdlife-schema list

Generate JSON Schema from Avro

birdlife-schema generate

Programmatic Usage (Node.js)

const avro = require('avsc');
const fs = require('fs');

// Load the schema
const taxonSchema = require('birdlife-schema/avro/taxon.avsc');
const type = avro.Type.forSchema(taxonSchema);

// Validate data
const myData = {
  taxonID: "8f14e45f-ceea-467f-a8f8-5c8e1c8d0a3b",
  slug: "erithacus-rubecula",
  scientificName: "Erithacus rubecula",
  taxonRank: "SPECIES"
};

if (type.isValid(myData)) {
  console.log('Valid!');
} else {
  console.log('Invalid');
}

JSON Schema (for web apps)

JSON Schema versions are auto-generated for use in web applications:

// Use with any JSON Schema validator (ajv, etc.)
const taxonJsonSchema = require('birdlife-schema/json-schema/taxon.json');

Core Entities (Tier 1)

| Entity | Description | Schema | |--------|-------------|--------| | Taxon | Species taxonomy (aligned with Darwin Core) | avro / json | | Observation | Bird sighting occurrence record | avro / json | | Location | Geographic location data | avro / json | | Observer | Privacy-conscious observer identity | avro / json | | Protocol | Survey methodology | avro / json | | Evidence | Supporting documentation (photos, audio) | avro / json |

See examples/ for valid JSON instances of each entity.

Extensions

Add custom fields to any entity using the extensions map:

{
  "taxonID": "...",
  "scientificName": "Erithacus rubecula",
  "extensions": {
    "myapp.nestingStatus": "confirmed",
    "myapp.broodSize": 4
  }
}

Rules:

• Keys must be namespaced: namespace.fieldName
• Pattern: ^[a-z][a-z0-9_]*\.[a-zA-Z][a-zA-Z0-9_]*$

See extensions/registry.md to register your namespace.

Foundation

This schema builds on established biodiversity standards:

• Darwin Core — International standard for biodiversity data
• GBIF — Global Biodiversity Information Facility compatibility
• eBird — Citizen science data model alignment

See mappings/ for field-level mappings to these standards.

Documentation

• DATA_CONTRACT_SPECIFICATION.md — Full design document
• governance.md — Schema change process
• alignment-guide.md — Tool integration guide

License

This project is licensed under the MIT License — see LICENSE for details.

Third-Party Attribution

This schema incorporates terms from Darwin Core, a standard maintained by Biodiversity Information Standards (TDWG).

Darwin Core is licensed under the Creative Commons Attribution 4.0 International License (CC BY 4.0).

© Biodiversity Information Standards (TDWG)

Community

• Website: birdlife.tech
• Matrix: #birdlife-schema:matrix.org
• Email: [email protected]

Contributing

Schema changes require review. See governance.md for the change process.

Part of the BirdLife Tools open-source conservation toolkit.