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

# Authoring Contracts

This guide helps you write a minimal ODCS v3.1.0 data contract. For the full specification, see the [upstream ODCS documentation](https://github.com/bitol-io/open-data-contract-standard).

## Minimal template

Save as `contract.yaml` and validate with `odcs validate contract.yaml`:

```yaml
version: "1.0.0"
apiVersion: "v3.1.0"
kind: "DataContract"
id: "hello-contract"
status: "draft"

schema:
  - name: customers
    logicalType: object
    properties:
      - name: customer_id
        logicalType: string
        required: true
```

## Required root fields

| Field | Description | Example |
|-------|-------------|---------|
| `version` | Your contract revision (any non-empty string) | `"1.0.0"` |
| `apiVersion` | ODCS specification release | `"v3.1.0"` |
| `kind` | Document type | `"DataContract"` |
| `id` | Stable contract identifier | `"customer-data-contract"` |
| `status` | Lifecycle status | `"draft"`, `"active"`, … |

## Common sections

| Section | Purpose |
|---------|---------|
| `schema[]` | Tables/objects, columns/properties, nested quality rules |
| `slaProperties` | Service level agreements |
| `team` | Ownership and contacts |
| `servers` | Physical/logical server definitions |
| `roles` | Access roles |
| `customProperties` | Extensions (use instead of unknown fields) |

See the [examples catalog](../examples.md) for contracts with SLA, team, servers, relationships, and quality rules.

## Authoring rules

1. **Quality rules** belong under `schema[]`, not at the contract root.
2. **Extensions** go in `customProperties` — unknown fields are rejected (`odcs:unknown-field`).
3. **Library metrics** use v3.1.0 names: `nullValues`, `missingValues`, `invalidValues`, `duplicateValues`, `rowCount`.
4. **Relationships** use `type: foreignKey` with valid `from` / `to` endpoints.
5. **Schema object names** must be unique within `schema[]` (since 0.7.0).
6. **Server identifiers** (`servers[].server`) must be unique within `servers[]` (since 0.7.0).
7. **SLA element references** — `slaProperties[].element` and deprecated `slaDefaultElement` must name existing `schema[].name` values (comma-separated tokens allowed).

## Validate while authoring

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

## Learn more

- [Getting started](getting-started.md) — install and first validation
- [FAQ](faq.md) — common validation errors
- [Upstream ODCS specification](https://github.com/bitol-io/open-data-contract-standard) — normative standard