Skip to content

Fix your first invalid contract

This tutorial walks through diagnosing and fixing a contract that fails validation.

Starting point

Save this intentionally broken contract as broken.yaml:

version: "1.0.0"
apiVersion: "v3.1.0"
kind: "DataContract"
id: "tutorial-contract"
status: "draft"

schema:
  - name: customers
    logicalType: object
    properties:
      - name: customer_id
        logicalType: string
        requred: true   # typo — should be "required"
    quality:
      - name: bad-metric
        type: library
        metric: not_null   # legacy name — use nullValues
        mustBe: 0

Step 1 — Validate

odcs validate broken.yaml

You should see multiple errors. Exit code 1 means validation failed (parse succeeded).

For machine-readable output:

odcs diagnostics broken.yaml --json

Step 2 — Fix the unknown field

Look for odcs:unknown-field:

[error] odcs:unknown-field: ...
  at: schema[0].properties[0].requred

Fix: rename requred → required.

Extensions

If the field is intentional custom metadata, use customProperties instead of inventing new keys. See Authoring contracts.

Step 3 — Fix the quality metric

Look for odcs:invalid-quality:

[error] odcs:invalid-quality: unsupported library metric 'not_null'
  at: schema[0].quality[0].metric

Fix: change metric: not_null to metric: nullValues (v3.1.0 library metric name).

Step 4 — Re-validate

odcs validate broken.yaml

Expected output:

valid

Step 5 — Inspect the result

odcs inspect broken.yaml --json

Confirms schemaCount, qualityCount, and contract metadata.

Common variations

If you see… Also check…
Exit code 2 Parse failure — duplicate keys, malformed YAML; see Troubleshooting
odcs:unsupported-version apiVersion must be v3.1.0
odcs:json-schema-violation Compare field against odcs schema output
odcs:duplicate-key Remove duplicate mapping keys at the path in object_ref

Next steps