THE LINUX FOUNDATION PROJECTS

Open Data Contract Standard (ODCS)

The open, technology-agnostic specification defining schema agreements, automated data quality rules, and service levels in version-controlled YAML.

View Spec on GitHubView ODPS Standard

Specification Overview: Version 3.1.0

A data contract defines the formal agreement between data producers and data consumers. Rather than relying on undocumented assumptions, ODCS defines the dataset structure, expected behavior, validation assertions, and SLAs in human-readable and machine-executable YAML.

ODCS is a Linux Foundation AI & Data incubation project licensed under Apache 2.0. The standard is backed by official JSON Schema specifications (v3.0.x and v3.1.x) allowing automated IDE validation (VS Code, IntelliJ) and continuous integration pipelines.

ODCS Specification Structure

1. Fundamentals & Schemas

  • apiVersion & kind: Fixed root version declaration (e.g., v3.1.0, DataContract).
  • dataset objects: Declarations of physical and logical models (tables, topics, files, views).
  • properties: Column/field names, data types, nullability, descriptions, and primary keys.
  • relationships: Primary and foreign key dependencies across models.
  • business metadata: Terms, classifications, tags, and authoritative definitions.

2. Data Quality Assertions

  • accuracy: Verification of mathematical validity and column values.
  • completeness: Null checks, empty value thresholds, and record counts.
  • validity: Regular expressions, enumerated sets, and range constraints.
  • custom assertions: Native SQL checks and integration hooks for Great Expectations and Soda.
  • execution schedule: Automated run triggers, test cadences, and alert destinations.

3. Physical Servers & Runtimes

  • server definitions: Environment targets (production, staging, analytics sandbox).
  • database engines: Snowflake, BigQuery, Redshift, PostgreSQL, Databricks, and Trino.
  • streaming systems: Apache Kafka brokers, Schema Registry formats (Avro, Protobuf, JSON).
  • object stores: AWS S3, Google Cloud Storage, and Azure Data Lake Storage.

4. SLAs, Roles & Governance

  • service-level agreements: Latency limits, update cadences, and uptime guarantees.
  • stakeholders: Data producer leads, consuming domain teams, and custodians.
  • communication: Operational support channels (Slack, Teams, PagerDuty, email).
  • lifecycle & pricing: Contract status (proposed, draft, active, deprecated, retired) and access fees.

ODCS YAML Contract Structure

The following example illustrates an actionable ODCS data contract manifest describing a table schema with embedded data quality assertions and SLA rules:

apiVersion: v3.1.0
kind: DataContract
id: urn:datacontract:checkout:orders
name: Completed Customer Orders
version: 1.2.0
status: active
domain: checkout

dataset:
  - table: orders
    description: Canonical records of completed customer orders
    properties:
      - name: order_id
        type: string
        primaryKey: true
        description: Unique order identifier
      - name: customer_id
        type: string
        description: Customer account identifier
      - name: total_amount
        type: numeric
        description: Net total transaction amount in USD
      - name: order_timestamp
        type: timestamp
        description: UTC timestamp when the order was completed

quality:
  - type: rowCount
    mustBeGreaterThan: 0
  - column: order_id
    type: nullValues
    mustBe: 0
  - column: total_amount
    type: custom
    query: "SELECT COUNT(*) FROM orders WHERE total_amount < 0"
    mustBe: 0

sla:
  frequency: daily
  latency: 3h

JSON Schema & IDE Setup

Every release of ODCS ships with an official JSON Schema. You can import this schema into your IDE to enable instant autocompletion, real-time syntax checking, and schema linting:

  • VS Code: Add the schema mapping directly into your settings.json:
    "yaml.schemas": {
      "https://raw.githubusercontent.com/bitol-io/open-data-contract-standard/main/schema/odcs-json-schema-v3.1.0.json": ["*contract*.yaml"]
    }
  • IntelliJ IDEA: Configure under Settings > Languages & Frameworks > Schemas and DTDs > JSON Schema Mappings by linking to the raw GitHub schema URL.
Browse JSON Schema on GitHub

Standardize Your Data Contracts with ODCS

Contribute to the specification, explore real-world examples, or join the Bitol community.

Join CommunityView Spec on GitHub