https://docs.confluent.io/cloud/current/sr/fundamentals/data-contracts.html

以下は、Confluent の公式ドキュメント「Data Contracts for Schema Registry on Confluent Cloud」に関する内容を、日本語に和訳し Markdown 形式でまとめたものです。

Confluent Cloud の Schema Registry における Data Contracts（データ契約）

Confluent Schema Registry は、タグ（tags）、メタデータ（metadata）、およびルール（rules）をサポートしており、これらを組み合わせることで データ契約（Data Contract） の概念を実現しています。これはストリームガバナンス機能の一環であり、異なるシステムや組織間で情報を共有する際に、データの品質、一貫性、相互運用性、互換性を確保する上で重要な役割を果たします。(docs.confluent.io)

要件

共通要件

スキーマルールは、Confluent Enterprise または Confluent Cloud の Stream Governance “Advanced” パッケージ でのみ利用可能。
スキーマルールはバージョン 7.4 以降 の Schema Registry でサポートされます。(docs.confluent.io)

Confluent Cloud 特有の要件

Schema Registry 上でルールを使用するには、Advanced Stream Governance パッケージ を有効化する必要があります。(docs.confluent.io)

Confluent Platform（オンプレ）の要件

スキーマルールは Confluent Enterprise（Community Edition を除く）でのみ使用可能。
使用するには、起動前の Schema Registry 設定プロパティに以下を追加する必要があります：
```
resource.extension.class=io.confluent.kafka.schemaregistry.rulehandler.RuleSetResourceExtension
```

(docs.confluent.io)

制限事項

以下の制限が現時点では存在します：

Kafka Connect や ksqlDB（Confluent Cloud 上）はルール実行をサポートしていません。
Flink SQL は、Confluent Cloud / Platform のどちらでもルール実行をサポートしていません。
Confluent Control Center（Legacy） は、スキーマビュー上にメタデータやルールといった新しいプロパティを表示しません。
スキーマルールは ルートスキーマにのみ実行され、参照スキーマには適用されません。例えば、Order スキーマが他の Product スキーマを参照していても、Product に付いたルールは実行されません。
非 Java クライアント（.NET、Go、Python、JavaScript）はDLQ（Dead Letter Queue）アクションに未対応です。
JavaScript と .NET は、Protobuf に対するスキーママイグレーションルールに未対応です（使用している第三者 Protobuf ライブラリの制約による）。(docs.confluent.io)

データ契約（Data Contract）の意義と構成要素

データ契約とは、データを「動く」（in motion）際の上流コンポーネントと下流コンポーネント間で合意された、構造や意味に関する正式な取り決めです。スキーマはその一部でしかなく、以下の要素を含む形で構成されます：(docs.confluent.io)

構成要素	説明
構造（Structure）	フィールドと型を定義するスキーマそのもの
整合性制約（Integrity constraints）	例えば「年齢は正の整数であるべき」など、ドメイン値に関する宣言的制約
メタデータ（Metadata）	スキーマやフィールドに関する追加情報（例：機密情報かどうか、作成者など）
ルール／ポリシー（Rules or policies）	機密フィールドは暗号化、無効な年齢を含むメッセージは DLQ 送信など、ポリシーの適用
変更・進化（Change or evolution）	バージョン管理や、スキーマ間で変換するマイグレーションルールのサポート

上流コンポーネントがデータ契約を強制し、下流コンポーネントは契約に準拠したデータ受信を前提とできます。
ストリームアーキテクチャにおいて依存性やデータ使用の透明性を高め、一貫性・信頼性・品質を確保します。
例えば、Producer がバージョン2を使用し、Consumer がバージョン1を期待する場合、Consumer 側で宣言型の変換ルールを使いデータを変換して適合させることができます。(docs.confluent.io)

タグ（Tags）

スキーマまたはその要素に注釈を追加できる仕組みです。スキーマ内に直接埋め込む（インライン）方法と、スキーマ外部で定義する方法があります：

Avro スキーマ（インラインタグ例）：

{
  "type":"record",
  "name":"MyRecord",
  "fields":[
    {
      "name":"ssn",
      "type":"string",
      "confluent:tags":[ "PII", "PRIVATE" ]
    }
  ]
}

JSON Schema：

{
  "type":"object",
  "properties":{
    "ssn":{
      "type":"string",
      "confluent:tags":[ "PII", "PRIVATE" ]
    }
  }
}

Protobuf：

syntax = "proto3";
import "confluent/meta.proto";

message MyRecord {
  string ssn = 1 [
    (confluent.field_meta).tags = "PII",
    (confluent.field_meta).tags = "PRIVATE"
  ];
}

リクエストペイロードが拡張され、既存の schemaType / schema / references に加えて、metadata と ruleSet フィールドが加わりました：(docs.confluent.io)

{
  "schemaType": "...",
  "schema": "...",
  "references": [...],
  "metadata": {
    "tags": { ... },
    "properties": { ... }
  },
  "ruleSet": {
    "migrationRules": [...],
    "domainRules": [...]
  }
}

外部タグ（metadata 内の tags） の例：

{
  "metadata": {
    "tags": {
      "MyRecord.ssn": ["PII"]
    }
  },
  "ruleSet": { ... }
}

パスワイルドカード対応。例："**.ssn": ["PII"] により任意階層のフィールドにタグを付与可能。パスワイルドカードには以下がサポートされます：(docs.confluent.io)

*：パス要素内で任意の文字数（例：a*.bob は alice.bob にマッチ）
**：複数のパス要素にまたがる任意の文字（例：a** は alice.bob にマッチ）
?：任意の1文字（例：alic?.bob は alice.bob にマッチ）

注意：Confluent Cloud 上では、インラインタグを使う前に Stream Catalog でタグ定義を行う必要があります。また、参照スキーマの場合、外部タグはルートスキーマにのみ適用されます。(docs.confluent.io)

メタデータプロパティ（Metadata properties）

任意のメタデータ（キー／バリュー）を追加して、データ契約に意味付けを強化できます：

{
  "metadata": {
    "properties": {
      "owner": "Bob Jones",
      "email": "[email protected]"
    }
  },
  "ruleSet": { ... }
}

(docs.confluent.io)

ルール（Rules）

整合性やポリシーを強制するために利用できるルールには、以下のプロパティがあります：(docs.confluent.io)

name：ユーザー定義のルール名
doc：任意の説明文
kind：CONDITION または TRANSFORM
type：Google Common Expression Language（CEL）や JSONata など、特定のルール実行エンジンを指定
mode：UPGRADE、DOWNGRADE、または両方向（UPDOWN）のマイグレーションルール

まとめ

Confluent Cloud の Schema Registry において、Data Contract（データ契約） は以下のような機能を通じて実現されます：

タグ（Tags）：フィールドやスキーマに注釈を追加して分類やポリシーを表現
メタデータ（Metadata）：所有者やドキュメントなど、データ契約に付随する意味情報を付与
ルール（Rules）：データの検証・変換やマイグレーションを宣言的に実行可能
バージョンと進化対応：変更管理や互換性確保のための宣言的マイグレーションルール

これにより、ストリームベースのアーキテクチャで生じるデータの品質維持やスキーマの進化に伴う問題に対して、強力で柔軟な対策が可能となります。

kenzo0107/Data Contracts for Schema Registry on Confluent Cloud.md