odcs 0.2.0

Reference implementation of the Open Data Contract Standard (ODCS)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94

# ODCS — Open Data Contract Standard

Reference Rust implementation for the [Open Data Contract Standard](https://github.com/bitol-io/open-data-contract-standard).

**Status:** Pre-release skeleton  
**Upstream ODCS version:** 3.1.0  
**Reference implementation:** 0.2.0 (Phase 1 — Skeleton)

See [ROADMAP.md](ROADMAP.md) for milestone status.

## Overview

[SPEC.md](SPEC.md) defines the upstream specification policy for this repository. The published ODCS specification remains the normative standard; this crate provides an idiomatic Rust API, deterministic validation, diagnostics, and CLI tooling aligned with upstream semantics.

This repository contains:

| Path | Purpose |
|------|---------|
| [SPEC.md](SPEC.md) | Upstream specification policy and synchronization workflow |
| [docs/](docs/) | Documentation index |
| [docs/implementation/](docs/implementation/) | Reference implementation design and build guides |
| [src/](src/) | Rust crate source (`odcs`) |
| [python/](python/) | Python package source (`pyodcs` on PyPI) |
| [examples/](examples/) | Sample ODCS data contracts |
| [tests/](tests/) | Integration tests and fixtures |
| [ROADMAP.md](ROADMAP.md) | Reference implementation milestones |
| [.github/workflows/](.github/workflows/) | CI pipeline |

## Ecosystem

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

See [docs/implementation/relationship-to-dtcs.md](docs/implementation/relationship-to-dtcs.md) for positioning alongside [DTCS](https://github.com/dtcs/dtcs).

## Quick start

### Build the Rust crate

```bash
cargo build
cargo test
cargo run -- validate examples/minimal.odcs.yaml
cargo run -- version
```

### Validate a contract

```bash
odcs validate examples/minimal.odcs.yaml
odcs validate examples/minimal.odcs.yaml --json
odcs inspect examples/minimal.odcs.yaml
```

The reference implementation targets this pipeline:

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

Execution, pipeline composition, and transformation semantics remain out of scope. See [docs/implementation/non-goals.md](docs/implementation/non-goals.md).

## Repository layout

```text
odcs/
├── SPEC.md                 # Upstream specification policy
├── Cargo.toml              # Rust crate manifest
├── pyproject.toml          # Python package manifest (`pyodcs`, maturin)
├── README.md
├── CONTRIBUTING.md
├── LICENSE
├── docs/
│   ├── README.md           # Documentation index
│   └── implementation/     # Reference implementation guides
├── examples/               # Example data contracts
├── python/                 # Python package source (`pyodcs`)
├── src/                    # Rust library, CLI binary, validation
├── tests/                  # Integration tests and fixtures
└── .cursor/prompts/        # Cursor build prompt
```

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for implementation guidelines and the review process.

When implementation guidance conflicts with the upstream ODCS specification, **the upstream specification wins**. See [docs/implementation/spec-usage.md](docs/implementation/spec-usage.md).

## License

Licensed under the Apache License, Version 2.0. See [LICENSE](LICENSE).