odcs 0.5.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

# 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 schema             # Print pinned ODCS JSON Schema
odcs version            # Print tool and upstream spec versions
```

## 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+) |
| `--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
```

**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.5.0",
  "upstreamSpecVersion": "3.1.0"
}
```

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