odcs 0.9.1

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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117

# odcs — Rust & Python reference implementation for ODCS

[![CI](https://github.com/eddiethedean/odcs/actions/workflows/ci.yml/badge.svg)](https://github.com/eddiethedean/odcs/actions/workflows/ci.yml)
[![Crates.io](https://img.shields.io/crates/v/odcs)](https://crates.io/crates/odcs)
[![PyPI](https://img.shields.io/pypi/v/pyodcs)](https://pypi.org/project/pyodcs/)
[![Documentation](https://readthedocs.org/projects/odcs/badge/?version=latest)](https://odcs.readthedocs.io/)
[![License](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](LICENSE)

> **Reference implementation, not the specification.** This repo validates ODCS documents. The normative [Open Data Contract Standard (ODCS)](https://github.com/bitol-io/open-data-contract-standard) is maintained by Bitol.

**odcs** validates ODCS YAML/JSON files locally and in CI.

It checks that your contract document is well-formed and conforms to ODCS v3.1.0 — schema, quality rules, SLAs, ownership, and server metadata. It does **not** run quality checks against live data.

> **Release:** **0.9.1** on `main` (**0.9.0** on [crates.io](https://crates.io/crates/odcs) and [PyPI](https://pypi.org/project/pyodcs/) until v0.9.1 ships). **1.0.0** stabilization is complete on `main`, pending release tag and registry publish — see [Release status](https://odcs.readthedocs.io/en/latest/project/release-status/) and [API stability policy](https://odcs.readthedocs.io/en/latest/implementation/api-stability/).

**Install → validate in 60 seconds:**

```bash
cargo install odcs   # or: pip install pyodcs
odcs version         # odcs 0.9.1 (upstream ODCS 3.1.0)
pyodcs version       # pyodcs 0.9.1 (upstream ODCS 3.1.0); use --json for crateVersion JSON
odcs validate contract.yaml
```

New to ODCS? Read [What is ODCS?](https://odcs.readthedocs.io/en/latest/user/what-is-odcs/) first.

| | |
|---|---|
| **Upstream ODCS** | 3.1.0 |
| **Rust crate** | [`odcs`](https://crates.io/crates/odcs) |
| **Python package** | [`pyodcs`](https://pypi.org/project/pyodcs/) |
| **Documentation** | [odcs.readthedocs.io](https://odcs.readthedocs.io/) |
| **Rust API docs** | [docs.rs/odcs](https://docs.rs/odcs) |

## Quick start

Copy [`examples/minimal.odcs.yaml`](examples/minimal.odcs.yaml) or save as `contract.yaml` (`.yaml` and `.odcs.yaml` both work):

```yaml
version: "1.0.0"      # your contract revision
apiVersion: "v3.1.0"  # ODCS spec release — not the same as version
kind: "DataContract"
id: "hello-contract"
status: "draft"
schema:
  - name: customers
    logicalType: object
    properties:
      - name: customer_id
        logicalType: string
        required: true
```

```bash
odcs validate contract.yaml   # prints: valid
```

On failure, diagnostics include stable codes and paths:

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

See [Diagnostics](https://odcs.readthedocs.io/en/latest/user/diagnostics/) and [Troubleshooting](https://odcs.readthedocs.io/en/latest/user/troubleshooting/).

From code:

```python
import pyodcs

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

Full walkthrough: [Getting started](https://odcs.readthedocs.io/en/latest/user/getting-started/) · [Installation](https://odcs.readthedocs.io/en/latest/user/installation/)

## Documentation

**Full docs:** [odcs.readthedocs.io](https://odcs.readthedocs.io/)

| I want to… | Read |
|------------|------|
| Learn what ODCS is | [What is ODCS?](https://odcs.readthedocs.io/en/latest/user/what-is-odcs/) |
| Get started in 5 minutes | [Getting started](https://odcs.readthedocs.io/en/latest/user/getting-started/) |
| Install Rust or Python | [Installation](https://odcs.readthedocs.io/en/latest/user/installation/) |
| Choose the right API | [API decision guide](https://odcs.readthedocs.io/en/latest/user/api-guide/) |
| Use the CLI | [CLI](https://odcs.readthedocs.io/en/latest/user/cli/) |
| Integrate in CI/CD | [CI/CD](https://odcs.readthedocs.io/en/latest/user/ci-cd/) |
| Fix validation errors | [Troubleshooting](https://odcs.readthedocs.io/en/latest/user/troubleshooting/) |
| Browse examples | [Examples](https://odcs.readthedocs.io/en/latest/examples/) |
| Local registry & cross-file refs | [Local registry](https://odcs.readthedocs.io/en/latest/user/registry/) · [examples/registry/](examples/registry/) |
| Compare contract revisions | [Compatibility analysis](https://odcs.readthedocs.io/en/latest/user/compatibility/) |
| Contribute | [Contributing](https://odcs.readthedocs.io/en/latest/contributing/) |
| Upstream sync policy (maintainers) | [SPEC.md](SPEC.md) |
| Report a security issue | [SECURITY.md](SECURITY.md) |

**Status:** 0.9.1 on `main` (0.9.0 published); 1.0 stabilization complete, pending release — [Release status](https://odcs.readthedocs.io/en/latest/project/release-status/) · [API stability](https://odcs.readthedocs.io/en/latest/implementation/api-stability/) · [ROADMAP.md](ROADMAP.md)

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

## Pipeline

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

Execution, pipeline composition, and transformation semantics are out of scope. See [non-goals](https://odcs.readthedocs.io/en/latest/implementation/non-goals/).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md). Run `./scripts/check.sh` before opening a PR. When implementation guidance conflicts with the upstream ODCS specification, **the upstream specification wins**.

## License

Apache License 2.0. See [LICENSE](LICENSE).