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

# Contract upgrade with diff

This tutorial uses `odcs diff` to review breaking changes before publishing a new contract revision.

## Starting point

The repository includes compatibility fixtures under `tests/fixtures/compatibility/`:

| File | Role |
|------|------|
| `base.yaml` | Baseline contract |
| `breaking-removed-column.yaml` | Removes a property (breaking) |

Copy them or reference the fixtures directly from a checkout.

## Step 1 — Compare contracts

```bash
odcs diff tests/fixtures/compatibility/base.yaml \
         tests/fixtures/compatibility/breaking-removed-column.yaml
```

Expected output (exit code `1`):

```text
[breaking] odcs:compatibility-breaking: removed property 'email' (schema[customers].properties[email])
```

## Step 2 — JSON output for CI

```bash
odcs diff tests/fixtures/compatibility/base.yaml \
         tests/fixtures/compatibility/breaking-removed-column.yaml \
         --json
```

Key fields:

```json
{
  "compatible": false,
  "hasBreaking": true,
  "changes": [ ... ]
}
```

Use `hasBreaking` as the gate in scripts:

```bash
odcs diff old.yaml new.yaml || {
  echo "Breaking changes detected — review before merging"
  exit 1
}
```

## Step 3 — Validate both revisions

Diff does not validate. Confirm both files are valid ODCS documents:

```bash
odcs validate tests/fixtures/compatibility/base.yaml
odcs validate tests/fixtures/compatibility/breaking-removed-column.yaml
```

## Step 4 — Python equivalent

```python
import pyodcs

old = pyodcs.parse_file("tests/fixtures/compatibility/base.yaml")["contract"]
new = pyodcs.parse_file("tests/fixtures/compatibility/breaking-removed-column.yaml")["contract"]
assert old is not None and new is not None

report = pyodcs.diff(old, new)
assert report["hasBreaking"] is True
for change in report["changes"]:
    print(change["kind"], change["path"])
```

## Step 5 — Typical upgrade workflow

1. Author the new contract revision (`version` field updated).
2. Run `odcs validate` on the new file.
3. Run `odcs diff old.yaml new.yaml` and review changes with consumers.
4. Merge when breaking changes are intentional and communicated.

## What to read next

| Goal | Document |
|------|----------|
| Full compatibility reference | [Compatibility analysis](../compatibility.md) |
| CLI flags and exit codes | [CLI — diff](../cli.md#diff) |
| Migration between tool releases | [Migration](../migration.md) |