odcs 0.9.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
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160

# CLI Reference

The `odcs` binary (Rust) and `pyodcs` command (Python) share the same subcommands and exit codes.

## Commands

```bash
odcs validate <path>    # Parse and validate; print result
odcs inspect <path>     # Print contract summary
odcs diagnostics <path> # Print validation diagnostics
odcs diff <old> <new> # Compare contracts for breaking changes
odcs schema             # Print pinned ODCS JSON Schema
odcs version            # Print tool and upstream spec versions
odcs registry index <dir>           # Build .odcs/registry.json
odcs registry lookup <dir> <id>     # Look up contract by id
odcs registry list <dir>            # List indexed contracts
```

## Flags

| Flag | Commands | Description |
|------|----------|-------------|
| `--json` | all | Emit JSON output (`schema --json` includes metadata wrapper) |
| `--strict` | `validate` | Deprecated no-op (JSON Schema always runs in 0.4.0+) |
| `--dep` | `validate` | Explicit dependency contract path (repeatable) |
| `--include` | `validate` | Non-recursive directory scan for dependency contracts |
| `--registry` | `validate` | Registry root directory (`<dir>/.odcs/registry.json`) |
| `--url-only` | `schema` | Print upstream repository URL only |

## Exit codes

| Code | Meaning |
|------|---------|
| `0` | Valid contract (or successful informational command) |
| `1` | Validation errors |
| `2` | Parse failure or I/O error (missing file, malformed YAML/JSON) |

## validate

```bash
odcs validate contract.yaml
odcs validate contract.yaml --json
odcs validate consumer.yaml --dep provider.yaml
odcs validate consumer.yaml --registry ./contracts/
```

Cross-file load order: primary → `--dep` → `--registry` → `--include`.

**Text output (valid):**

```text
valid
```

**Text output (invalid):**

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

When present, `at:` shows the affected field path and `hint:` shows remediation.

**JSON output:**

```json
{
  "valid": true,
  "diagnostics": []
}
```

## inspect

```bash
odcs inspect contract.yaml
odcs inspect contract.yaml --json
```

**JSON output fields:**

| Field | Description |
|-------|-------------|
| `id` | Contract id |
| `name` | Contract name (if set) |
| `version` | Contract document revision (e.g. `1.0.0`) |
| `apiVersion` | ODCS API version |
| `kind` | Document kind |
| `status` | Lifecycle status |
| `schemaCount` | Number of schema objects |
| `qualityCount` | Nested quality rules across schemas |

## diagnostics

Same exit codes as `validate`. JSON output contains only the `diagnostics` array.

## schema

```bash
odcs schema
odcs schema --json
odcs schema --url-only
```

**Default:** full pinned ODCS v3.1.0 JSON Schema to stdout.

**`--json`:** metadata wrapper with `schemaVersion`, `upstreamUrl`, and `schema`.

**`--url-only`:** upstream repository URL (previous default style).

## version

```bash
odcs version
odcs version --json
```

**JSON output:**

```json
{
  "crateVersion": "0.7.0",
  "upstreamSpecVersion": "3.1.0"
}
```

## registry

Build and query a local contract index at `<dir>/.odcs/registry.json`.

```bash
odcs registry index ./contracts/
odcs registry lookup ./contracts/ provider-contract
odcs registry lookup ./contracts/ provider-contract --version 1.0.0
odcs registry list ./contracts/
```

Add `--json` for structured output. `lookup` without `--version` returns the highest semver entry for the id. Exit `1` when lookup finds no entry; index exits `1` on duplicate `(id, version)` pairs.

## `--strict` (deprecated)

Since 0.4.0, JSON Schema validation always runs. `--strict` is accepted for backward compatibility but has no additional effect.

## CI integration example

```bash
#!/bin/sh
set -e
for f in contracts/*.yaml; do
  odcs validate "$f" --json > /dev/null
done
```

Or fail the job on any invalid contract:

```bash
odcs validate contract.yaml || exit 1
```

See [diagnostics.md](diagnostics.md) for error code reference.