CI/CD Integration

Use odcs or pyodcs in continuous integration to block merges when data contracts are invalid.

Exit codes

Code	Meaning	CI action
0	Valid	Pass
1	Validation errors	Fail
2	Parse or I/O failure	Fail

Cross-file and FQN relationships

Important: Single-file odcs validate contract.yaml does not resolve fully-qualified relationship endpoints (provider-contract/schema/property) against other contracts. For consumers with FQN references, use one of:

# Explicit dependency
odcs validate consumer.yaml --dep provider.yaml

# Include directory (non-recursive scan)
odcs validate consumer.yaml --include ./contracts/

# Local registry (recommended for monorepos)
odcs registry index ./contracts/
odcs validate consumer.yaml --registry ./contracts/

See examples/registry/ and Local registry.

Untrusted input (PR validation)

Treat pull-request YAML as potentially hostile:

• Prefer JSON for untrusted contributions when possible
• Enforce a 16 MiB file size limit at ingress (before odcs validate)
• Run validation in an isolated CI job with memory limits
• YAML anchors/aliases are not fully bounded — see SECURITY.md

# Example: cap wall time for large registry index jobs
timeout 300 odcs registry index ./contracts/

Set ODCS_VERBOSE=1 for per-file index progress on stderr (does not affect stdout JSON).

Validate a single contract

odcs validate contracts/customer.yaml || exit 1

JSON output for structured logging:

odcs validate contracts/customer.yaml --json

Validate all contracts in a directory

#!/bin/sh
set -e
failed=0
for f in contracts/*.{yaml,yml,json}; do
  [ -f "$f" ] || continue
  if ! odcs validate "$f" --json > /dev/null; then
    echo "INVALID: $f"
    odcs diagnostics "$f"
    failed=1
  fi
done
exit $failed

GitHub Actions

name: Validate ODCS contracts

on:
  pull_request:
    paths:
      - 'contracts/**'
  push:
    branches: [main]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Install odcs
        run: cargo install odcs --version 0.9.1 --locked

      - name: Index contract registry
        run: odcs registry index ./contracts/

      - name: Validate contracts
        run: |
          for f in contracts/*.{yaml,yml,json}; do
            [ -f "$f" ] || continue
            echo "Validating $f"
            odcs validate "$f" --registry ./contracts/ --json
          done

Python alternative

      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'

      - run: pip install pyodcs==0.9.1

      - run: pyodcs validate contracts/customer.yaml

Pre-commit hook

Add to .pre-commit-config.yaml:

repos:
  - repo: local
    hooks:
      - id: odcs-validate
        name: Validate ODCS contracts
        entry: odcs validate
        language: system
        files: \.(yaml|yml|json)$
        pass_filenames: true

Requires odcs on PATH (cargo install odcs).

Notes

• Pin the tool version in CI for reproducibility: cargo install odcs --version 0.9.1 --locked and pip install pyodcs==0.9.1.
• Do not run odcs registry index in parallel against the same directory — index writes are atomic but concurrent jobs can race.
• See Release status for current published versions.
• See diagnostics.md for routing on odcs:* error codes.