データコントラクトとは？壊れないデータ連携の約束をYAML例で解説

アプリ側で注文テーブルの列名を変えた翌朝、データパイプラインは失敗し、経営ダッシュボードが更新されない。あるいは処理自体は成功したのに、通貨単位の変更に気付かず売上だけが異常になる。データ連携では、作る側の小さな変更が、知らないところにいる利用者へ大きな影響を与えます。

この問題に対する結論は、変更を禁止することではありません。データの提供者と利用者が、構造、意味、品質、鮮度、変更方法を機械可読な形で約束することです。それがデータコントラクトです。法的契約やブロックチェーンのSmart Contractではありません。ここでは、何を書くのか、YAMLは何のためか、dbtのModel Contractとどう違うかを順番に説明します。

最初に結論

データコントラクトとは、データ提供者が利用者へ公開するデータについて、スキーマ、意味、品質、SLA、所有者、利用条件、変更方針をバージョン付きで定義する合意です。人同士の会話だけで終わらせず、YAMLなどの機械可読形式にすることで、CIやパイプラインで変更と実データを検証できます。

データ版API契約として考える

APIを利用する開発者は、入力項目、返却形式、エラー、バージョンを確認します。提供側が応答形式を突然変えれば、利用側のアプリが壊れます。データパイプラインでも同じことが起きますが、テーブルは多くのダッシュボード、機械学習、AIエージェントから間接的に使われるため、影響先を見落としやすくなります。

データコントラクトは、公開するデータの期待を明示します。たとえばordersは一行一注文、order_idは必須かつ一意、amountは税込み日本円、毎日8時までに前日分が届く、破壊的変更は新しいMajor Versionで提供する、という内容です。

契約という言葉でも、罰則を定める法律文書ではありません。提供者と利用者が、何を信用してよいかを共有し、自動検証へつなげるための技術・運用文書です。

契約に含める7項目

最小構成は対象によって変わりますが、構造だけで終わらせないことが重要です。型が合っていても、売上の単位や注文の粒度が変われば分析は誤ります。逆に、すべての説明を最初から埋めようとすると運用が止まるため、重要項目から段階的に増やします。

ODCSは何を標準化するのか

Open Data Contract Standard（ODCS）は、データコントラクトをYAMLで表すためのオープン標準です。2026年8月時点でv3.1.0が公開され、Schema、Quality、SLA、Team、Role、Serverなどをプラットフォームに依存しない形で記述できます。JSON Schemaを使って契約ファイル自体を検証することもできます。

標準を使う利点は、BigQuery用、Snowflake用、Kafka用に基本概念を作り直さずに済むことです。対応ツールへImport・Exportしたり、CIでLintしたり、実データと契約を照合したりしやすくなります。ただし、標準に従えば合意が自動で生まれるわけではありません。曖昧なdescriptionを正式なYAMLへ入れても、曖昧さは残ります。

以前からあるData Contract Specificationは、公式リポジトリでODCSへの移行が案内されています。古いサンプルをそのまま採用せず、利用するCLIと標準Versionを明記してください。

小さなYAML例を人の言葉へ戻して確認する

最初から完全なYAMLを書くより、業務上の約束を短い文章で合意し、それを構造へ移す方が失敗しません。たとえば「確定注文を一行一件で提供し、IDと金額を必須にし、前日分の到着時刻を監視する」と決めます。その後、ODCSのid、description、schema、quality、slaProperties、teamへ割り当てます。

以下は、その約束をODCS v3.1.0へ移した小さな例です。ordersテーブルのorder_idとamount、型・必須・一意性、日本円という単位、実データで検査する品質ルール、毎日8時までというSLA、担当チームと読み取りRoleまでを含みます。公式JSON Schemaに対して検証できる構文です。

YAMLレビューでは、構文だけでなく、利用者が誤解しないかを見ます。amountが税込みか、返金後か、物理型integerの単位が円か銭かは、型検査では分かりません。またQuality Ruleが厳しすぎると正しい遅延まで止め、緩すぎると契約の意味がなくなります。過去データでRuleを試してからBlockingへ切り替えます。

• apiVersionとversion：ODCSの仕様版と、この注文契約自体の版を分ける
• schema：ordersを一行一注文とし、order_idは必須かつ一意、amountは必須の数値とする
• customProperties：amountの通貨単位がJPYであることを機械可読にする
• quality：order_idの重複件数とamountのNull件数が0であることを実データで検査する
• slaProperties：前日分を毎日8時（日本時間）までに提供する期待を記録する
• teamとroles：担当チームと、読み取りを許可するRole・承認者を明示する

1. 1. 対象と利用者を決める：重要な公開テーブルを一つ選び、実際に利用するダッシュボードやチームを特定します。
2. 2. 人が読める期待を合意する：粒度、意味、必須列、鮮度、変更通知を提供者と利用者で確認します。
3. 3. ODCSなどで機械可読にする：契約Versionを付け、Schema、Quality、SLA、Ownerを構造化します。
4. 4. CIと実データで検証する：構文、破壊的変更、実テーブルの型・品質・鮮度を段階的に検査します。

apiVersion: v3.1.0
kind: DataContract
id: bb0104e5-7396-4a8c-9d4f-cd099406a6fa
name: orders
version: 1.0.0
status: active
domain: commerce
description:
  purpose: 確定注文を一行一件で分析へ提供する
  limitations: amountは税込みの注文金額で、取消・返金は別データで管理する
schema:
  - name: orders
    logicalType: object
    physicalType: table
    dataGranularityDescription: 一行一注文
    properties:
      - name: order_id
        logicalType: string
        physicalType: VARCHAR
        required: true
        unique: true
        quality:
          - type: library
            metric: duplicateValues
            mustBe: 0
            unit: rows
            dimension: uniqueness
            severity: error
      - name: amount
        logicalType: number
        physicalType: DECIMAL(18,2)
        required: true
        logicalTypeOptions:
          minimum: 0
        customProperties:
          - property: currency
            value: JPY
            description: 金額単位は日本円
        quality:
          - type: library
            metric: nullValues
            mustBe: 0
            unit: rows
            dimension: completeness
            severity: error
slaProperties:
  - property: frequency
    value: 1
    unit: d
    element: orders
    driver: operational
  - property: timeOfAvailability
    value: "08:00+09:00"
    element: orders
    driver: operational
    description: 前日分を毎日8時（日本時間）までに提供する
team:
  name: Commerce Data Team
  members:
    - username: data-owner@example.com
      role: owner
roles:
  - role: analytics_reader
    description: 注文分析用の読み取りRole
    access: read
    firstLevelApprovers: data-owner@example.com

dbt Model Contractとの違い

dbtのModel Contractは、dbt Modelが返す列名とデータ型を事前に定義し、Build時に形が一致するか確認する機能です。公開Modelを下流から安定して利用するうえで有効ですが、ODCSと同じ範囲を扱うわけではありません。

壊さないための変更フロー

契約の価値は、初回作成より変更時に現れます。列を削除する、型を変える、粒度を変えるといった破壊的変更を検知したら、すぐ本番を止めるのではなく、影響先を確認し、新Versionを並行提供し、利用者の移行期限を決めます。

一方、説明の明確化やOptional列の追加など、互換性を保つ変更もあります。何をMajor、Minor、Patchとするかをチームで決め、GitのPull Requestで契約と実装を一緒にReviewします。実データが契約に違反したときは、提供者へ通知するのか、データを隔離するのか、下流処理を止めるのかをSLAと重要度で分けます。

Ownerが異動して連絡先が古くなる、Ruleが実態と合わなくなる、誰も見ない契約が増えるという運用負債にも注意が必要です。契約数ではなく、重要データで違反検知から復旧まで機能しているかを見ます。

次に読む記事

参考文献

本記事は以下の公式文書、標準、論文、公開記事・投稿を確認し、初心者向けに論点を再構成しています。 仕様や制度は更新されるため、導入時はリンク先の最新版も確認してください。

• Open Data Contract Standard v3.1.0 — Fundamentals — Bitol / Linux Foundation AI & Data（最終確認：2026-08-07）：ODCSの構造、項目、仕様版を参照。
• Open Data Contract Standard repository — Bitol（最終確認：2026-08-07）：v3.1.0のRelease、Schema、License、標準の背景を参照。
• Model contracts — dbt Labs（最終確認：2026-08-07）：dbt Model Contractの保証範囲とData Testとの違いを参照。
• Data Contract CLI documentation — Data Contract CLI（最終確認：2026-08-07）：ODCSのLint、Import、実データ検査という運用例を参照。

よくある質問

まとめと次の一歩

データコントラクトは変更を禁じる文書ではなく、構造・意味・品質・鮮度・責任者の期待を機械可読にし、破壊的変更を安全に移行する運用です。YAMLは合意を自動検証へつなぐ手段です。