OAE Data Protocol Schemas

⚠️ Alpha Software: These schemas are under active development and may change without notice. We do not currently guarantee backwards compatibility between versions. Once the schemas stabilize, we will establish a formal release process with semantic versioning to support clients and integrators who need stability guarantees.

The OAE Data Management Protocol outlines recommendations for producing consistent data and metadata for Ocean Alkalinity Enhancement (OAE) research projects.

This repository provides machine-readable schemas and data standards for the protocol. It focuses on formal specifications for metadata about OAE projects, experiments, datasets, and individual data variables within datasets themselves (including instrument, analysis, and calibration metadata).

Creating Metadata: The easiest way to produce a valid metadata file is the OAE Metadata Builder — a web app that walks you through each section and exports a JSON file validated against these schemas. Excel templates from the v1.0 protocol launch (August 25, 2025) remain available in templates/excel and on the protocol website.

Beta Testing: Organizations and researchers interested in testing the software tooling under development should contact data@carbontosea.org.

What's Inside

This repository contains LinkML schema definitions that can generate:

• JSON Schema for data validation and form generation
• Python dataclasses for programmatic data handling
• TypeScript definitions for web tooling
• Documentation (what you're reading now!)
• Support for multiple serialization formats (JSON, YAML, RDF, etc.)

Documentation

📖 schema.oaedata.org

Using the Schemas

The generated schemas are available in:

• project/jsonschema/ - JSON Schema definitions (including *.validation.schema.json for runtime validation)
• project/typescript/ - TypeScript definitions
• src/oae_data_protocol/datamodel/ - Python dataclasses (dataclass + Pydantic)

Repository Structure

├── src/
│   └── oae_data_protocol/
│       ├── schema/          # LinkML schema definitions (edit these!)
│       └── datamodel/       # Generated Python dataclasses
├── project/                 # Generated project files (don't edit)
├── examples/                # Example data files
├── tests/                   # Python tests
└── docs/                    # Generated documentation

Development

Installation

Requires uv and just.

# Clone the repository
git clone https://github.com/submarine-mrv/oae-data-protocol.git
cd oae-data-protocol

# Install dependencies
just install

# Generate schema artifacts
just gen-all

Common Commands

just                   # Show all available commands
just gen-project       # Regenerate Python dataclasses, JSON Schema, TypeScript
just gen-all           # Full build: gen-project + validation schema + version injection
just test              # Run tests
just lint              # Lint LinkML schemas
just testdoc           # Build and serve documentation locally

Working with Schemas

The schema files in src/oae_data_protocol/schema/ are the source of truth. Edit these files and run just gen-all to regenerate all derived artifacts.

Project Status

Current Status: Alpha development

We're actively developing and refining these schemas based on real-world usage and community feedback. Breaking changes may occur as we work toward a stable v1.0 release of these schemas which will have parity with v1.0.0 of the protocol.

Credits & Acknowledgments

This project is built with:

• LinkML for schema definitions
• linkml-project-copier for project structure

Development of the OAE Data Protocol and its corresponding technical tooling has been made possible with funding and steering support from Carbon To Sea.

License

See LICENSE for details.