8.3.2. Service Registry を使用した JSON スキーマ SerDes の設定
このトピックでは、JSON スキーマの Kafka クライアントシリアライザーおよびデシリアライザー (SerDes) クラスを使用する方法について説明します。
Service Registry は、JSON スキーマ用に次の Kafka クライアント SerDes クラスを提供します。
-
io.apicurio.registry.serde.jsonschema.JsonSchemaKafkaSerializer -
io.apicurio.registry.serde.jsonschema.JsonSchemaKafkaDeserializer
Apache Avro とは異なり、JSON スキーマはシリアライズテクノロジーではなく、検証テクノロジーです。その結果、JSON スキーマの設定オプションは大きく異なります。たとえば、データは常に JSON としてエンコードされるため、エンコーディングオプションはありません。
JSON スキーマシリアライザーの設定
JSON スキーマシリアライザークラスを以下のように設定できます。
- Service Registry の URL
- アーティファクトリーゾルバーストラテジー
- スキーマ検証
唯一の標準以外の設定プロパティーは、デフォルトで有効になっている JSON スキーマバリデーションです。これを無効にするには、apicurio.registry.serde.validation-enabled を false に設定します。以下に例を示します。
props.putIfAbsent(SerdeConfig.VALIDATION_ENABLED, Boolean.FALSE)
JSON スキーマデシリアライザーの設定
JSON スキーマデシリアライザークラスを以下のように設定できます。
- Service Registry の URL
- スキーマ検証
- データをデシリアライズするためのクラス
スキーマをロードできるように、Service Registry の場所を指定する必要があります。他の設定はオプションです。
デシリアライザーの検証は、シリアライザーが Kafka メッセージでグローバル ID を渡す場合にのみ機能します。これは、シリアライザーで検証が有効になっている場合にのみ発生します。
JSON スキーマの SerDes とアーティファクトの参照
JSON スキーマ SerDes はメッセージペイロードからスキーマを検出できないため、事前にスキーマアーティファクトを登録する必要があり、これはアーティファクト参照にも適用されます。
スキーマの内容に応じて、$ref の値は URL に置き換えます。SerDes はこの URL を使用して参照のスキーマを解決しようとし、主要なスキーマに対するデータの検証、ネスト化されたスキーマに対するネスト化された値の検証など、検証は通常どおりに行われます。Service Registry でアーティファクトを参照するためのサポートも実装されています。
たとえば、次の city.json スキーマは city.json スキーマを参照ししています。
city.json スキーマを参照する citizen.json スキーマ
{
"$id": "https://example.com/citizen.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "Citizen",
"type": "object",
"properties": {
"firstName": {
"type": "string",
"description": "The citizen's first name."
},
"lastName": {
"type": "string",
"description": "The citizen's last name."
},
"age": {
"description": "Age in years which must be equal to or greater than zero.",
"type": "integer",
"minimum": 0
},
"city": {
"$ref": "city.json"
}
}
}
city.json スキーマ
{
"$id": "https://example.com/city.schema.json",
"$schema": "http://json-schema.org/draft-07/schema#",
"title": "City",
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The city's name."
},
"zipCode": {
"type": "integer",
"description": "The zip code.",
"minimum": 0
}
}
}
この例では、citizen に city が含まれます。Service Registry では、city アーティファクトへの参照を持つ citizen アーティファクトが、city.json という名前を使用して作成されます。SerDes では、citizen スキーマをフェッチすると、citizen スキーマから参照されるため、city スキーマもフェッチされます。データをシリアライズ/デシリアライズする場合、ネストされたスキーマを解決するために参照名が使用され、citizen スキーマとネストされた city スキーマに対する検証が可能になります。
関連情報
- 詳細は、JsonSchemaKafkaDeserializerConfig Java クラス を参照してください。
Java のサンプルアプリケーションについては、以下を参照してください。