8.3.2. 使用 Service Registry 配置 JSON Schema SerDes

本主题解释了如何使用 Kafka 客户端序列化r 和 deserializer (SerDes)类用于 JSON Schema。

Service Registry 为 JSON Schema 提供以下 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 Schema deserializer 类,如下所示:

  • Service Registry URL
  • 模式验证
  • 用于反序列化数据的类

您必须提供 Service Registry 的位置,以便可以加载 schema。其他配置是可选的。

注意

仅当序列化器传递 Kafka 信息中的全局 ID 时,Deserializer 验证才会正常工作,这只有在被序列化器中启用验证时才会发生。

JSON Schema SerDes 和 artifact 引用

JSON Schema SerDes 无法从消息有效负载发现 schema,因此必须预先注册架构工件,这也会应用工件引用。

根据方案的内容,如果 $ref 值是 URL,则 SerDes 会尝试使用该 URL 解析引用的 schema,然后验证针对主架构的数据,并对主模式验证嵌套值。还实施了对 Service Registry 中引用工件的支持。

例如,以下 citizen.json 模式引用 city.json 模式:

公民.json 模式,并参考 city.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
   }
 }
}

在本例中,给定公民具有城市。在 Service Registry 中,会使用名称 city.json 创建对城市工件的引用的公民工件。在 SerDes 中,当公民架构获取时,也会获取城市架构,因为它是从公民架构中引用的。在对数据进行序列化/反序列化数据时,使用引用名称来解决嵌套模式,从而允许针对市民和嵌套城市模式进行验证。

其他资源