The open, technology-agnostic specification defining schema agreements, automated data quality rules, and service levels in version-controlled YAML.
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.
Standardize Your Data Contracts with ODCS
Contribute to the specification, explore real-world examples, or join the Bitol community.