odcs — Rust & Python reference implementation for ODCS

Validate Open Data Contract Standard (ODCS) documents — machine-readable contracts that describe datasets (schemas, quality rules, SLAs, ownership, and server metadata) — with a deterministic parser, validator, and CLI.

This tool checks that your contract document is well-formed and conforms to ODCS v3.1.0. It does not execute quality checks against live data.

Use this repository if you want to:

• validate ODCS v3.1.0 contracts in CI/CD
• parse contracts into a typed object model (Rust or Python)
• get structured diagnostics with stable odcs:* error codes

Status: Alpha pre-1.0 (0.4.0) — schema-complete default validation for ODCS v3.1.0; see ROADMAP.md and the documentation.

This repository implements the standard; it is not the ODCS specification itself.

Installation

Prerequisites

• Rust: 1.75+ (for the odcs crate and CLI)
• Python: 3.9+ (for the pyodcs package)

Rust CLI

cargo install odcs
odcs version

Python

pip install pyodcs
pyodcs version

From source

git clone https://github.com/eddiethedean/odcs.git && cd odcs
cargo build --release
cargo install --path . --locked

# Python editable install
python -m venv .venv && source .venv/bin/activate
pip install maturin pytest
maturin develop --features python --locked

See the installation guide (source) for troubleshooting.

Quick start

Save a minimal contract as contract.yaml:

version: "1.0.0"
apiVersion: "v3.1.0"
kind: "DataContract"
id: "hello-contract"
status: "draft"
schema:
  - name: customers
    properties:
      - name: customer_id
        logicalType: string
        required: true

Rust CLI

odcs validate contract.yaml
# valid

odcs validate contract.yaml --json
odcs inspect contract.yaml
odcs diagnostics contract.yaml

From a repository checkout (includes examples/):

odcs validate examples/minimal.odcs.yaml
cargo run -- validate examples/minimal.odcs.yaml

Rust library

use odcs::{parse, validate, DocumentFormat};

let yaml = br#"
version: "1.0.0"
apiVersion: "v3.1.0"
kind: "DataContract"
id: "hello-contract"
status: "draft"
schema:
  - name: customers
    properties:
      - name: customer_id
        logicalType: string
        required: true
"#;

let result = parse(yaml, DocumentFormat::Yaml);
let contract = result.into_contract().expect("valid contract");
let report = validate(&contract);
assert!(report.is_valid());

Python

import pyodcs

content = open("contract.yaml", "rb").read()
report = pyodcs.parse_and_validate(content, format="yaml")
assert pyodcs.is_valid(report)

result = pyodcs.parse(content, format="yaml")
print(pyodcs.inspect(result["contract"]))

Documentation

Full docs: odcs.readthedocs.io

Pipeline

ODCS Document → Parser → Canonical Object Model → Validator → Diagnostics

Execution, pipeline composition, and transformation semantics are out of scope. See non-goals (source).

Ecosystem

ODCS defines what data is.
DTCS defines how data changes.
DPCS defines how transformations compose.

See Relationship to DTCS (source).

Repository layout

odcs/
├── docs/user/              # User guides (install, CLI, Rust, Python, diagnostics)
├── docs/implementation/    # Maintainer / implementation guides
├── examples/               # Sample data contracts
├── python/pyodcs/          # Python package source
├── src/                    # Rust library and CLI
└── tests/fixtures/         # Integration test fixtures

Contributing

See CONTRIBUTING.md. When implementation guidance conflicts with the upstream ODCS specification, the upstream specification wins.

License

Apache License 2.0. See LICENSE.