odcs 0.9.1

# Getting Started

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

New to ODCS? Read [What is ODCS?](what-is-odcs.md) 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](https://github.com/bitol-io/open-data-contract-standard).

## Step 1 — Install

Choose Rust or Python (or both):

```bash
# 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](../project/release-status.md).

Verify either CLI:

```bash
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](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`:

```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:

```bash
odcs validate contract.yaml
```

### If you cloned this repository

```bash
odcs validate examples/minimal.odcs.yaml
```

Expected output on success:

```text
valid
```

On failure you see structured diagnostics:

```text
[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:

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

Single-file `validate` does not load other contracts. See [CI/CD integration](ci-cd.md#cross-file-and-fqn-relationships) and [Local registry](registry.md).

## Step 3 — Inspect a contract

```bash
# 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](api-guide.md) 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

```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

```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](api-guide.md).

## Step 5 — Explore more examples

The [examples catalog](../examples.md) includes contracts with SLA, team, servers, relationships, and quality rules.

## What to read next

| Goal | Document |
|------|----------|
| Choose the right API | [api-guide.md](api-guide.md) |
| CLI flags and JSON output | [cli.md](cli.md) |
| Local registry | [registry.md](registry.md) |
| Compatibility diff | [compatibility.md](compatibility.md) |
| Rust API reference | [rust.md](rust.md) |
| Python API reference | [python.md](python.md) |
| Author a contract | [authoring.md](authoring.md) |
| Error codes and remediation | [diagnostics.md](diagnostics.md) |
| CI/CD integration | [ci-cd.md](ci-cd.md) |
| Upgrade guide | [migration.md](migration.md) |
| Fix a broken contract | [tutorials/fix-invalid-contract.md](tutorials/fix-invalid-contract.md) |
| Troubleshoot errors | [troubleshooting.md](troubleshooting.md) |
| Common questions | [faq.md](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](../implementation/non-goals.md).