Kafka Schema Registryのスキーマ参照：共通型の再利用と版管理

スキーマ参照は、共通の型定義を複数スキーマで再利用するためのSchema Registry機能です。重複定義をなくし、変更時の影響範囲を明確にできます。

参照は“特定のサブジェクトとその版”に固定されます。最新へ自動追従しないため、計画的な移行が可能です。

スキーマ参照の基礎：なぜ使うのか

スキーマ参照（References）は、Schema Registryに登録済みの別スキーマを名前で呼び出して再利用する仕組みです。対象はAvro、Protobuf、JSON Schemaで、共通アドレス型や共通エラーフォーマットなどの“横断的な型”を一元管理できます。

参照は、ルート（親）スキーマに対して、参照名・参照先サブジェクト・参照先バージョンを紐づけて登録します。実行時のKafkaメッセージには、ルートのスキーマIDのみが書き込まれ、デシリアライザはRegistryから参照を解決して完全なスキーマを取得します。

利点は、型定義の重複削減、変更の局所化、レビューの容易化、互換性チェックの一元化です。欠点は、登録順序の管理（先に共通型→後にルート）と、参照バージョンの明示的な更新作業が必要な点です。

• 対応フォーマット: Avro / Protobuf / JSON Schema
• メッセージにはルートのSchema IDのみ（参照のIDは埋め込まれない）
• 参照は“サブジェクト＋固定バージョン”で記録。自動で最新にはならない

登録と解決の流れ：参照はどのように動くか

登録手順はシンプルです。1) まず共通型（例：Address）を単独のサブジェクトとして登録。2) 次に、共通型を使うルートスキーマ（例：Order）を、referencesに共通型の“サブジェクト名とバージョン”を指定して登録します。互換性チェックは解決後の“完全展開スキーマ”に対して行われます。

参照のnameの意味はフォーマットにより異なります。一般ガイドとして、Avroは完全修飾型名、Protobufはimport名（.proto）、JSON Schemaは$refで参照する識別子名やパスに合わせるのが通例です。

実行時は、プロデューサ／コンシューマともにルートのSchema IDのみを用い、Schema Registryが裏側で参照を解決します。したがってクライアントのワイヤ形式は参照の有無で変わりません。

• 登録順序: 参照先（共通型）→ 参照元（ルート）
• name/subject/versionをreferencesに指定（latest指定は不可）
• 解決はRegistryサーバ側。クライアントは通常のIDルックアップのみ

参照解決の流れ（概念図）

Avro 参照付きスキーマの登録例 (Schema Registry REST API)

## 1) 共通型 Address を登録
curl -s -X POST \
  -H 'Content-Type: application/vnd.schemaregistry.v1+json' \
  http://localhost:8081/subjects/com.example.types.Address/versions \
  -d '{
    "schemaType": "AVRO",
    "schema": "{\n  \"type\": \"record\",\n  \"name\": \"Address\",\n  \"namespace\": \"com.example.types\",\n  \"fields\": [\n    {\"name\": \"street\", \"type\": \"string\"},\n    {\"name\": \"city\", \"type\": \"string\"}\n  ]\n}"
  }'

## 2) ルート型 Order を登録（Address を参照）
curl -s -X POST \
  -H 'Content-Type: application/vnd.schemaregistry.v1+json' \
  http://localhost:8081/subjects/com.example.sales.Order/versions \
  -d '{
    "schemaType": "AVRO",
    "references": [
      {
        "name": "com.example.types.Address",
        "subject": "com.example.types.Address",
        "version": 1
      }
    ],
    "schema": "{\n  \"type\": \"record\",\n  \"name\": \"Order\",\n  \"namespace\": \"com.example.sales\",\n  \"fields\": [\n    {\"name\": \"id\", \"type\": \"string\"},\n    {\"name\": \"shippingAddress\", \"type\": \"com.example.types.Address\"}\n  ]\n}"
  }'

# 注意: 上記のサブジェクト名は例です。実運用ではSubject Naming Strategy（例: TopicNameStrategyで orders-value 等）が決定します。参照自体の動作は同じです。

再利用設計パターン：Subject命名戦略と共通型の切り出し

共通型を複数トピックで再利用する場合、Subject Naming Strategyの選択が重要です。デフォルトのTopicNameStrategyでは、各トピックごとに<topic>-key / <topic>-valueの別サブジェクトとなるため、同じ型でもトピックが違えば別サブジェクトに登録されます。

共通型を“1つのサブジェクト”に集約して再利用したい場合は、RecordNameStrategy（またはTopicRecordNameStrategy）を検討します。RecordNameStrategyは完全修飾レコード名（例: com.example.types.Address）をサブジェクトに使うため、トピックをまたいでも同一型は同一サブジェクトで管理できます。

参照は“subject@version”で固定されるため、共通型の新バージョンを発行しても、各ルートスキーマは明示的に参照を更新するまで既存バージョンを使い続けます。これにより段階的ロールアウトが可能です。

• TopicNameStrategy: トピックごとに独立運用（デフォルト）
• RecordNameStrategy: 型名で一元管理しやすい（共通型向き）
• TopicRecordNameStrategy: 型とトピックの両方を粒度に使う

互換性とバージョニング：参照時のチェックのかかり方

Schema Registryの互換性はサブジェクト単位で設定し、登録時に“解決後の完全スキーマ”に対してチェックされます。参照を含む場合、共通型を取り込んだ状態で比較されるため、共通型の破壊的変更はルートの登録時に検知されます。

互換性レベルにはBackward / Forward / Fullと、それぞれにTransitiveのバリアントがあります。Transitiveを使うと直前バージョンだけでなく“全バージョン”との互換性を検証します。共通型を広く再利用している場合、FULL_TRANSITIVEが安全側です。

参照は“バージョン固定”なので、共通型の新バージョンを公開しても既存のルートは直ちには影響を受けません。段階的に各ルートで参照先バージョンを更新・再登録していく運用が基本です。

• チェック対象は展開後のスキーマ全体（参照も含む）
• Transitive互換性は長期運用の退行検知に有効
• 参照が固定版なので、段階的移行がやりやすい

運用プラクティス：破壊的変更の回避とローリング移行

共通型の変更は影響が広いので、Compatibilityを厳しめ（例：FULL_TRANSITIVE）に設定し、まず共通型の新バージョンを公開→検証→各ルートで参照を更新→プロデューサを段階的にデプロイ、という順で進めます。

ワイヤ形式はルートのSchema IDのみなので、参照の有無でKafkaメッセージ互換性は変わりません。焦点は“登録可否”と“デシリアライズ可否”です。互換性違反は登録時に止め、コンシューマ側の互換性はスキーマ進化ルール（例：デフォルト値の付与）で担保します。

• 先に共通型を公開・安定化→各ルートが参照を追随
• 互換性レベルとCIの組み合わせで破壊的変更をブロック
• サンドボックスRegistryでの事前検証を自動化

CCDAK対策メモ：押さえるべき試験観点

Subject Naming Strategyの違いと再利用の可否（TopicNameStrategy/RecordNameStrategy/TopicRecordNameStrategy）。

参照の登録時に必要な要素（name/subject/version）と、最新追随がない点。

互換性チェックは“参照解決後”に行われ、Transitive設定の意味は“全履歴との比較”。

• デフォルトは<topic>-key / <topic>-value の別サブジェクト
• 共通型の再利用にはRecordNameStrategyが有力
• 参照の自動アップグレードは存在しない（明示再登録が必要）

問題で確認

よくある質問