如何使用Schema Registry API校验含外部依赖文件的Schema兼容性

你直接拼接多个独立AVSC文件失败的核心原因是：Avro Schema仅允许存在一个顶层类型定义，所有依赖的自定义类型不能直接作为并列的JSON对象拼接，需通过以下两种合法方式提交校验：

方式一：依赖类型已提前注册到Schema Registry #

如果你的独立AVSC对应的自定义类型已经提前注册到Schema Registry的对应subject下，直接在请求体中新增references字段声明依赖即可，无需拼接所有Schema内容：

POST /compatibility/subjects/test/versions/latest HTTP/1.1
Host: schemaregistry.example.com
Accept: application/vnd.schemaregistry.v1+json, application/vnd.schemaregistry+json, application/json
Content-Type: application/json

{
  "schema": "{\"type\":\"record\",\"name\":\"test\",\"fields\":[{\"type\":\"string\",\"name\":\"field1\"},{\"type\":\"com.example.CustomType\",\"name\":\"field2\"}]}",
  "schemaType": "AVRO",
  "references": [
    {
      "name": "com.example.CustomType",
      "subject": "custom-type-subject",
      "version": 1
    }
  ]
}

参数说明：

• references数组每一项对应一个依赖的自定义类型
• name填写自定义类型的完整命名空间名称
• subject填写该自定义类型注册时对应的subject名称
• version填写你需要依赖的该类型的版本号

方式二：依赖类型未注册，一次性提交所有内容 #

如果自定义类型还未注册，需要把所有独立AVSC的内容合并到同一个Avro Schema定义中，通过顶层types字段声明所有依赖的自定义类型：

1. 合并所有AVSC内容，结构示例如下：

{
  "type": "record",
  "name": "test",
  "namespace": "com.example",
  "types": [
    // 这里放所有独立AVSC中的自定义类型定义
    {
      "type": "enum",
      "name": "CustomType",
      "symbols": ["VALUE1", "VALUE2"]
    }
  ],
  "fields": [
    {"name": "field1", "type": "string"},
    {"name": "field2", "type": "CustomType"}
  ]
}

2. 将合并后的完整JSON对象转义为单行字符串，填入请求体的schema字段提交即可。

注意事项 #

• 手动转义容易出错，可以先在本地用Avro工具类校验合并后的Schema合法性，再转义提交
• 提交请求时需确保Content-Type头设置为application/json

内容的提问来源于stack exchange，提问作者user14817992