Data Contract Template (ODCS v3.2.0)

Data Contract: [Dataset or data product output port name] [version]

Agreement between the producer of a dataset and its consumers: who owns it, what the schema means, which quality rules and service levels it guarantees, where it is served, who may access it, what it costs, how AI tools may use it, and how it may change. The structure and field names follow the Bitol Open Data Contract Standard (ODCS) v3.2.0 (released 2026-09-08, Apache-2.0), so the prose document and the YAML file in section 15 describe the same thing and the YAML can be validated against the published JSON schema. Replace every [bracketed] value and every row marked Example.

Document control

Approvals

Revision history

Contents

• 1. Fundamentals
• 2. Schema
• 3. Semantic roles, synonyms and enumerations
• 4. Data quality rules
• 5. Service level properties
• 6. Servers and environments
• 7. Team, roles and access
• 8. Support and communication
• 9. Pricing
• 10. AI usage context
• 11. Consumers
• 12. Change management, versioning and deprecation
• 13. Authoritative definitions and custom properties
• 14. Traceability matrix
• 15. ODCS YAML skeleton
• 16. Glossary and references
• Standard and licence note

1. Fundamentals

The fundamentals section tells a new consumer in one minute whether this dataset is the right one. ODCS places these facts at the top of the contract: identity (id, name, version, status), ownership context (domain, tenant, tags) and the human description. Write the purpose as a single sentence that states the grain and the business event. Then separate the uses the producer supports from the uses the producer explicitly does not support, because an unsupported use that silently fails is the producer's reputational problem even when it is not the producer's fault.

1.1 Purpose

[Example: "One row per confirmed customer order on Corvid Commerce storefronts, used for revenue reporting, demand forecasting and customer analytics."]

1.2 Usage and limitations

2. Schema

ODCS describes data as a list of schema objects, each with a list of properties. An object has a name, a physicalName, a physicalType (for example table, view, topic or file), a businessName, a description and a dataGranularityDescription that states the grain. A property carries a logicalType from the ODCS list (string, date, timestamp, time, number, integer, object, array, boolean, map, vector), the engine-specific physicalType, and flags for required, unique, primaryKey with primaryKeyPosition, partitioned with partitionKeyPosition, classification and criticalDataElement. Give every object and every property a stable id when other documents or quality rules refer to it, so that renaming the property does not break the reference.

Object: [orders]. Physical name: [lakehouse.sales.orders]. Physical type: table. Grain: one row per confirmed order.

Use logicalTypeOptions to tighten a type without inventing new columns: string length and pattern, number minimum and maximum, timestamp format, array item limits and, for embeddings, the vector dimensions and element type. Record derivations in transformSourceObjects, transformLogic and transformDescription so a reader can trace a property back to its sources without opening the pipeline code. Classification values must come from the Data Classification Policy (data/data-classification-policy); do not invent local labels. Whether a property holds personal data is a separate fact from its classification level: record it with the policy's flags (PD, PSEUDO, PD-SC and the others in its section 5) as tags or a custom property. The flag sets a minimum level: pseudonymised personal data stays at least Confidential.

3. Semantic roles, synonyms and enumerations

ODCS v3.2.0 lets the contract carry semantic information that previously lived only in a BI tool or a wiki. Three features matter most.

Semantic role. Each property may declare a semanticType: column (the default, a physical column), measure (an aggregated value whose aggregation expression goes in transformLogic) or dimension (a categorical attribute used to group and filter). A measure is a separate property that aggregates a base column; the base column itself stays a column. Marking the row-level column as a measure that sums itself confuses the grain, and semantic-layer tools may aggregate it twice. Declare roles only where they help a semantic layer or an assistant; the governed metric itself is defined once in a Metric Definition (data/metric-definition) and modelled in the Semantic Model Specification (data/semantic-model-specification).

Synonyms. Each schema object and property may list synonyms, each with the synonym itself and optionally a description, a BCP 47 locale, a source (for example the glossary or a legacy system) and a status. Synonyms help search, catalogues and AI assistants map a question to the right field. They do not replace the glossary entry.

Enumerations. Use the enum list on a property for controlled vocabularies. Each entry has a value, an optional human label and an optional description. A validator can then reject unknown values, and a dashboard can show labels instead of codes.

4. Data quality rules

ODCS attaches quality rules to a schema object or to a property. Each rule has a type: text for a human-readable expectation, library for a predefined metric (nullValues, missingValues, invalidValues, duplicateValues, rowCount), sql for a query whose result is compared with a threshold, or custom for a rule written in an external engine's own syntax. Thresholds use the ODCS comparison operators (mustBe, mustNotBe, mustBeGreaterThan, mustBeGreaterOrEqualTo, mustBeLessThan, mustBeLessOrEqualTo, mustBeBetween, mustNotBeBetween). The ODCS dimension field accepts accuracy, completeness, conformity, consistency, coverage, timeliness and uniqueness; map these to the characteristic names your Data Quality Standard (data/data-quality-standard) uses, which may follow ISO/IEC 25012.

ODCS severity is free text (the schema examples are info, warning and error); this template uses the Data Quality Standard's Critical, Major and Minor so that contracts, tests and alerts share one scale. Tell any tool that expects the ODCS example values how to map them.

Write the businessImpact of each Critical and Major rule in one sentence, for example "Duplicate orders inflate reported revenue". Consumers read that field when they decide whether to wait for a fix or use the data with a caveat. When a rule fails, follow the Data Incident Postmortem (data/data-incident-postmortem) process for anything that reached consumers.

5. Service level properties

ODCS expresses service levels as a list of slaProperties. Each entry has a property name, a value (and optionally valueExt), a unit, the element it is measured on, a driver and, for scheduled checks, a scheduler and schedule. ODCS recommends the property names availability, throughput, errorRate, latency (preferred to freshness), frequency, retention, generalAvailability, endOfSupport, endOfLife, timeToDetect, timeToNotify and timeToRepair; the documentation examples also use timeOfAvailability. Add others, such as supportResponse in the table below, only when no recommended name fits, and define them in the standards register so tools read them consistently. Version 3.2.0 adds authoritativeDefinitions and customProperties on each SLA entry, so you can link the formal SLA document or the measurement method. The older slaDefaultElement field is deprecated since v3.1.0; set element on each entry instead.

Retention must agree with the Data Retention and Deletion Standard (data/data-retention-deletion-standard). If the contract promises longer retention than the standard allows, the standard wins and the contract is wrong.

6. Servers and environments

The ODCS servers list records each place the dataset can be read. Every entry has a server identifier and a type; v3.2.0 added eight server types (hana, iceberg, exasol, teradata, ingres, vectorwise, versant, poet) plus the synonyms fastobjects and btrieve. Each type has its own connection fields. For iceberg they are catalog and catalogUrl (required) plus namespace and warehouse. Add environment (for example dev, uat, prod), a description and the roles that may connect. File-based servers may also declare an encoding such as UTF-8.

ODCS v3.2.0 also defines variables: any string value may contain a ${VAR_NAME} reference, with an optional default written ${VAR_NAME:-default}, resolved by tooling at run time from environment variables, a secrets manager or CI variables. One contract file can then serve every environment, and no secret enters version control. The server port accepts a string so it can hold a variable. Tooling must report an unresolved variable instead of silently using an empty value.

7. Team, roles and access

Since v3.1.0, ODCS models team as an object with a name, a description and a members list; the older plain array of members is deprecated and will be removed in ODCS 4.0. Each member has a username, a name, a role (for example owner or data steward), and dateIn and dateOut so the history of ownership is kept. When someone leaves, set dateOut and record replacedByUsername rather than deleting the row.

The ODCS roles list names each access role with its access level and the firstLevelApprovers and secondLevelApprovers who grant it.

8. Support and communication

ODCS support entries each name a channel, a url, a tool (for example email, slack, teams or ticket) and a scope (interactive, announcements, issues or notifications). Separate the scopes so that consumers can subscribe to announcements without following every question.

9. Pricing

The ODCS price object has priceAmount, priceCurrency and priceUnit. Many organisations charge nothing internally and still record a zero price, because it shows that the question was considered. Where the platform charges back query cost, name the unit the bill uses.

10. AI usage context

ODCS v3.2.0 adds an optional context block at contract level and at schema object level (not on individual properties; the schema rejects a context key on a property). It holds instructions (natural-language guidance scoped to that level), verifiedStatements (canonical questions, with verified answers where available) and constraints (negative guidance: what an agent must not do). Write instructions as you would brief a new analyst. Keep verified answers to the method, not to a number that will go stale.

11. Consumers

ODCS does not prescribe a consumer register; keep it here or in the data catalogue and reference it with a custom property. Record the properties each consumer uses, so that a change to an unused property can proceed with less ceremony.

12. Change management, versioning and deprecation

Contract versions follow semantic versioning:

• Major (breaking): removing or renaming a property, changing a type or meaning, changing the grain, making a nullable property required in a way that drops rows, lowering a service level.
• Minor (compatible): adding an optional property, adding an enumeration value with notice, improving a service level, marking a property deprecated.
• Patch: description fixes and documentation only.

ODCS v3.2.0 adds a deprecated flag on schema objects and properties. Set it when the replacement is available, keep the property populated during the notice period, and remove it only in the next major version. Record the replacement in the description and, if useful, as a deprecated synonym.

13. Authoritative definitions and custom properties

authoritativeDefinitions may appear at contract, object, property and SLA level. Each entry has a type (recommended values in the ODCS documentation include businessDefinition, glossary, implementation, transformationImplementation and canonicalUrl) and a url. Use them to point to the glossary term, the dbt model and the metric definition.

customProperties is the extension point for anything ODCS does not define. Each entry has a property name in camel case and a value; v3.2.0 adds an optional vendor to show which tool owns the property; an optional description is also available.

The top-level dataProduct field is deprecated since ODCS v3.1.0. Link the contract to its data product from the product side (the ODPS output port's contract reference) and, if you need a back-link, with a custom property.

14. Traceability matrix

15. ODCS YAML skeleton

The skeleton mirrors sections 1 to 13. Values are Example data for the fictional Corvid Commerce.

apiVersion: v3.2.0
kind: DataContract
id: corvid-orders-orders
name: orders
version: 2.1.0
status: active
domain: sales
tenant: corvid-commerce
tags: [orders, sales, gold, PD, PSEUDO]
contractCreatedTs: "2026-10-24T09:00:00Z"
description:
  purpose: One row per confirmed customer order for revenue reporting and forecasting.
  usage: Daily revenue reporting, cohort analysis, source of the orders_daily_agg port.
  limitations: Marketplace orders may arrive up to 24 hours late.
context:
  instructions: >
    Use this dataset for order-level questions; prefer the orders_daily_agg port for daily
    counts and net revenue. Exclude cancelled orders from net revenue.
  verifiedStatements:
    - id: net-revenue-month
      question: "What was net revenue last month?"
      answer: "Sum net_amount by currency for non-cancelled orders, using order_ts in UTC."
  constraints:
    - id: no-customer-level-output
      constraint: "Do not return individual orders together with customer_id."
schema:
  - name: orders
    id: orders_obj
    physicalName: orders
    physicalType: table
    logicalType: object
    businessName: Customer orders
    dataGranularityDescription: One row per confirmed order
    synonyms:
      - synonym: purchases
        source: glossary
    properties:
      - name: order_id
        id: order_id_prop
        logicalType: string
        physicalType: VARCHAR(20)
        required: true
        primaryKey: true
        primaryKeyPosition: 1
        unique: true
        criticalDataElement: true
        classification: internal
        quality:
          - id: dq-ord-001
            type: library
            metric: duplicateValues
            mustBe: 0
            dimension: uniqueness
            severity: critical
            businessImpact: Duplicate orders inflate reported revenue.
      - name: net_amount
        id: net_amount_prop
        logicalType: number
        physicalType: DECIMAL(12,2)
        required: true
        classification: confidential
        synonyms:
          - synonym: Nettoumsatz
            locale: de-DE
            source: finance-team
      - name: total_net_amount
        id: total_net_amount_prop
        logicalType: number
        semanticType: measure
        transformLogic: SUM(net_amount)
        description: Sum of net_amount; aggregate per currency.
      - name: channel
        id: channel_prop
        logicalType: string
        semanticType: dimension
        enum:
          - value: web
            label: Web shop
          - value: app
            label: Mobile app
          - value: marketplace
            label: Marketplace
      - name: region_code
        id: region_code_prop
        logicalType: string
        deprecated: true
        description: Deprecated since 2.1.0; use ship_country.
    quality:
      - id: dq-ord-005
        type: library
        metric: rowCount
        mustBeBetween: [40000, 160000]
        dimension: completeness
        severity: minor
servers:
  - server: lakehouse-prod
    type: iceberg
    environment: prod
    catalog: corvid
    catalogUrl: ${ICEBERG_CATALOG_URL}
    namespace: sales
  - server: lakehouse-dev
    type: iceberg
    environment: dev
    catalog: corvid
    catalogUrl: ${ICEBERG_CATALOG_URL}
    namespace: ${DEV_NAMESPACE:-sales_dev}
slaProperties:
  - id: sla-ord-001
    property: latency
    value: 60
    unit: min
    element: orders.order_ts
    driver: analytics
  - id: sla-ord-004
    property: retention
    value: 7
    unit: y
    element: orders.order_ts
    driver: regulatory
team:
  name: sales-data-products
  description: Owns the Orders and Checkout data products.
  members:
    - username: a.okafor
      role: owner
      dateIn: "2025-03-01"
    - username: m.lindqvist
      role: data steward
      dateIn: "2025-03-01"
roles:
  - role: orders_reader
    access: read
    firstLevelApprovers: Data steward
  - role: orders_finance
    access: read
    firstLevelApprovers: Data steward
    secondLevelApprovers: Finance controller
support:
  - channel: "#orders-data"
    tool: slack
    scope: interactive
  - channel: orders-data-announce
    tool: email
    scope: announcements
price:
  priceAmount: 0
  priceCurrency: EUR
  priceUnit: gigabyte
authoritativeDefinitions:
  - type: businessDefinition
    url: https://catalog.example.com/glossary/order
customProperties:
  - property: dataProductOutputPort
    value: orders

16. Glossary and references

References:

• Bitol, Open Data Contract Standard (ODCS) v3.2.0, released 2026-09-08, Apache-2.0: https://github.com/bitol-io/open-data-contract-standard and https://bitol-io.github.io/open-data-contract-standard/
• Bitol, Open Data Product Standard (ODPS) v1.1.0, released 2026-09-08, Apache-2.0: https://github.com/bitol-io/open-data-product-standard
• ISO/IEC 25012:2008, Data quality model (names only).
• Apache Iceberg table specification: https://iceberg.apache.org/spec/
• Related templates: Data Product Specification (data/data-product-specification), Data Quality Standard (data/data-quality-standard), Data Pipeline Specification (data/data-pipeline-spec), Metric Definition (data/metric-definition), Semantic Model Specification (data/semantic-model-specification), Data Classification Policy (data/data-classification-policy), Data Retention and Deletion Standard (data/data-retention-deletion-standard), Data Incident Postmortem (data/data-incident-postmortem), Data Requirements Specification (requirements/data-requirements).

Standard and licence note

Based on the Open Data Contract Standard (ODCS) v3.2.0 published by the Bitol project (a Linux Foundation AI and Data project) under the Apache License 2.0, https://github.com/bitol-io/open-data-contract-standard. Field names and enumerated values are used as defined by the specification; all explanatory text is original and copies no prose from the specification. Check the current ODCS release and JSON schema before validating a contract, because field names and server types change between versions. Template licence: MIT.