Getting Started¶

This guide gets you from zero to a validated ODCS contract in about five minutes.

New to ODCS? Read What is ODCS? first.

What you need to know¶

ODCS (Open Data Contract Standard) defines machine-readable data contracts — schemas, quality rules, SLAs, ownership, and more.
This repository (odcs / pyodcs) is a reference implementation that parses and validates ODCS documents. It is not the specification itself.
The normative standard lives at bitol-io/open-data-contract-standard.

Step 1 — Install¶

Choose Rust or Python (or both):

# Rust CLI
cargo install odcs

# Python package + CLI
pip install pyodcs

Both resolve to 0.9.0 from registries today; 0.9.1 after the next publish. To pin explicitly: cargo install odcs --version 0.9.1 --locked or pip install pyodcs==0.9.1. See Release status.

Verify either CLI:

odcs version
pyodcs version

Both report crateVersion 0.9.1 (from source/main) or 0.9.0 (from registries until v0.9.1 ships) and upstreamSpecVersion 3.1.0.

See installation.md for prerequisites, from-source setup, and troubleshooting.

Step 2 — Validate a contract¶

If you installed from crates.io or PyPI¶

Save this minimal contract as contract.yaml:

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

Then validate:

odcs validate contract.yaml

If you cloned this repository¶

odcs validate examples/minimal.odcs.yaml

Expected output on success:

valid

On failure you see structured diagnostics:

[error] odcs:invalid-kind: expected kind 'DataContract', got 'WrongKind'
  at: kind

Exit codes: 0 = valid, 1 = validation error, 2 = parse or I/O failure.

Multiple contracts in one repo?¶

If relationships use fully-qualified names (provider-id/schema/column), validate with dependencies:

odcs registry index ./contracts/
odcs validate consumer.yaml --registry ./contracts/

Single-file validate does not load other contracts. See CI/CD integration and Local registry.

Step 3 — Inspect a contract¶

# Use the same path you validated in Step 2
odcs inspect contract.yaml
# or, from a repo checkout:
odcs inspect examples/minimal.odcs.yaml

Prints a short summary: id, name, version, schema count, quality rule count.

Step 4 — Use from code¶

Choose the entry point that matches your needs. See API decision guide for the full table.

Goal	Rust	Errors
Parse + validate; diagnostics only	`parse_and_validate()`	`DiagnosticReport`
Parse then validate separately	`parse()` then `validate()`	`ParseResult`, then `DiagnosticReport`
Typed contract or fail	`parse_strict()` or `into_contract()`	`Result<DataContract, DiagnosticReport>`
Read from file	`parse_file()`	`miette::Result` for I/O; `DiagnosticReport` for validation

Rust¶

use odcs::{parse, DocumentFormat};

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

let result = parse(yaml, DocumentFormat::Yaml);
let contract = result.into_contract().expect("valid contract");
println!("contract id: {}", contract.id);

Python¶

import pyodcs

content = open("contract.yaml", "rb").read()
report = pyodcs.parse_and_validate(content, format="yaml")
assert pyodcs.is_valid(report)
print(pyodcs.inspect(pyodcs.parse(content, format="yaml")["contract"]))

For step-by-step parse then validate, see API decision guide.

Step 5 — Explore more examples¶

The examples catalog includes contracts with SLA, team, servers, relationships, and quality rules.

What to read next¶

Goal	Document
Choose the right API	api-guide.md
CLI flags and JSON output	cli.md
Local registry	registry.md
Compatibility diff	compatibility.md
Rust API reference	rust.md
Python API reference	python.md
Author a contract	authoring.md
Error codes and remediation	diagnostics.md
CI/CD integration	ci-cd.md
Upgrade guide	migration.md
Fix a broken contract	tutorials/fix-invalid-contract.md
Troubleshoot errors	troubleshooting.md
Common questions	faq.md

What this tool does not do¶

Execute data quality checks against live data
Run ETL or pipeline transformations
Host a contract registry server

See ../implementation/non-goals.md.