├── README.md ├── spec_cn.md └── spec_en.md /README.md: -------------------------------------------------------------------------------- 1 | # OpenSchema 2 | This project propose a specification for data schema when exchanging the message and event in more and more modern cloud-native applications. Any vendor could provide a serving layer base on this spec, designing a RESTful interface for storing and retrieving such as Avro®, JSON Schema, and Protobuf3 schemas. Implementations like that already exist, such as Schema Registry, you could store a versioned history of all schemas based on a specified subject name strategy, provides multiple compatibility settings and allows evolution of schemas according to the configured compatibility settings and expanded support for these schema types. 3 | 4 | Nowadays, it is still in the rapid development process. We released the preview version 1.0.0-preview. The schema registry of Spring and Confluent can be regarded as an implementation of it. Currently, communities such as Apache Eventmesh, Apache RocketMQ are actively adapting it. If you have any improvment suggestion, please do not hesitate to issue us. 5 | 6 | ## Releases 7 | [1.0.0-preview](https://github.com/openmessaging/openschema/blob/master/spec_en.md) 8 | 9 | ## Quick Start 10 | 11 | [SchemaRegistry](https://github.com/openmessaging/schemaregistry) is the reference implementation for OpenSchema, that you can rely on in your project. We would like to hear any feedback from the community. 12 | -------------------------------------------------------------------------------- /spec_cn.md: -------------------------------------------------------------------------------- 1 | ## 一、综述 2 | 3 | 本篇提供了 OpenSchema 的相关元数据以及交互方式定义。 4 | 5 | ## 目录 6 | 7 | - [兼容性设计](#二兼容性设计) 8 | - [Content Types](#三content-types) 9 | - [Error Codes](#四error-codes) 10 | - [Schema格式](#五schema格式) 11 | - [元信息](#51-元信息) 12 | - [Schema定义](#52-schema定义) 13 | - [Subject与Topic的对应关系](#六subject与topic的对应关系) 14 | - [REST 接口定义](#七rest-接口定义) 15 | - [Schema相关接口](#71-schema相关接口) 16 | - [Subject 相关接口](#72-subject-相关接口) 17 | - [兼容性相关接口](#73-兼容性相关接口) 18 | 19 | ## 二、兼容性设计 20 | 21 | | 兼容性设置 | 说明 | 22 | | ------------------- | ------------------------------------------------------------ | 23 | | BACKWARD(默认) | Consumer使用新Schema可以读取由使用最新Schema的Producer发送的数据。 | 24 | | BACKWARD_TRANSITIVE | Consumer可以使用新Schema读取由Producer使用所有以前注册过的Schema发送的数据。 | 25 | | FORWARD | Consumer使用最近的Schema可以读取由使用最新Schema的Producer发送的数据。 | 26 | | FORWARD_TRANSITIVE | Consumer可以使用所有注册过的Schema读取由Producer使用最新的Schema发送的数据。 | 27 | | FULL | 新Schema与最新注册的Schema向前和向后兼容。 | 28 | | FULL_TRANSITIVE | 新Schema向前和向后兼容所有以前注册的Schema | 29 | | NONE | 禁用模式兼容性检查。 | 30 | 31 | 32 | 33 | ## 三、Content Types 34 | 35 | OpenSchema REST服务器通过使用http+json的方式进行通信。 36 | 37 | 请求应通过HTTP Accept标头指定最具体的格式和版本信息，此外可以包括多个加权首选项： 38 | 39 | > Accept:application/vnd.openschema.v1+json 40 | 41 | 42 | 43 | ## 四、Error Codes 44 | 45 | 所有的请求的HTTP返回保持跟HTTP标准统一，其中细化的错误码由返回的json字符串来决定，格式： 46 | 47 | ```json 48 | { 49 | "errorCode": 422, 50 | "errorMessage": "schema info cannot be empty" 51 | } 52 | ``` 53 | 54 | 55 | 56 | ## 五、Schema格式 57 | 58 | ### 5.1 元信息 59 | 60 | 元信息称之为 subject 。 61 | 62 | | 元信息 | 含义 | 示例 | 63 | | ------------- | ------------------------ | ------------------------------- | 64 | | tenant | 租户 | org/apache/rocketmq/mybank | 65 | | namespace | 命名空间 | 集群名称, 如 rocketmq-cluster | 66 | | subject | 元数据的名称 | 比如使用Topic名称作为元数据名称 | 67 | | app | 服务提供方的应用部署单元 | | 68 | | description | 描述信息 | 由申请人提供 | 69 | | status | 元数据状态 | 比如已发布、已废弃等 | 70 | | compatibility | 兼容性策略 | 无、向前兼容、向后兼容、全兼容 | 71 | | coordinate | Maven坐标 | 消息Payload的JAR的Maven坐标 | 72 | | createdTime | subject注册的时间 | 比如2021-09-14T02:26:09.018 | 73 | | lastModifiedTime | subject最近更新的时间 | 比如2021-09-15T02:26:09.018 | 74 | | format | schema类型的枚举：NONE、JSON、PB、AVRO、USER-DEFINED、Int、Long、String、Map | NONE 表示不提供Schema。也可以给当前消息加上Schema，比如用PB来描述RocketMQ 传输的数据的格式 | 75 | | schema | 数据格式 | 关联的数据格式描述，详见下表 | 76 | 77 | 示例： 78 | 79 | ```json 80 | { 81 | "tenant": "messaging/rocketmq", 82 | "namespace": "org.apache.rocketmq", 83 | "subject": "test-topic", 84 | "app": "rocketmq", 85 | "description": "rocketmq test subject", 86 | "status": "released", 87 | "compatibility": "NONE", 88 | "coordinate": "maven-group:package:1.0.0", 89 | "createdTime": "2021-09-14T02:26:09.018", 90 | "lastModifiedTime": "2021-09-15T02:26:09.018", 91 | "format": "AVRO", 92 | "schema": {} 93 | } 94 | ``` 95 | 96 | ### 5.2 Schema定义 97 | 98 | Payload Schema用于描述消息的Payload数据。 99 | 100 | | 元信息 | 含义 | 示例 | 101 | | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 102 | | name | payload名称，可空（比如消息的payload不需要名字） | | 103 | | id | 全局唯一标识，用于确定该schema | | 104 | | comment | payload注释说明 | | 105 | | serialization | 序列化方式：hissian、json、pb、avro、user-defined | | 106 | | schemaDefinition | schema具体的内容，以一种方式来描述数据格式 | NONE：无 PB：给出PB描述文件 AVRO：给出AVRO Schema内容 USER-DEFINED：给出用户自定义的信息 基础内容类型：无 | 107 | | validator | 值校验器 | 对Schema描述的对象的值进行校验 | 108 | | version | schema的版本信息 | 以消息为例，Payload可能会变，这个时候需要版本来标识区别不同的Schema | 109 | 110 | 示例： 111 | 112 | ```json 113 | { 114 | "name": "rocketmq-user-topic", 115 | "id": "SLEd-3334-XSSFE-44983", 116 | "comment": "Rocketmq user information", 117 | "serialization": "", 118 | "schemaDefinition": [{ 119 | "name": "id", 120 | "type": "string" 121 | }, 122 | { 123 | "name": "age", 124 | "type": "short" 125 | } 126 | ], 127 | "validator": "a.groovy", 128 | "version": 1 129 | } 130 | ``` 131 | 132 | 133 | 134 | ## 六、Subject与Topic的对应关系 135 | 136 | ### 6.1 Subject和Topic的关系 137 | 138 | - 消息系统 139 | 140 | 141 | Subject名称默认对于Topic名称，用于定义消息体的格式。可以通过后缀的方式进行扩展，${topic}-${suffix}，比如，在kafka中，一般使用Kafka-Key来用来定义kafka消息的中的key的数据格式。 142 | 143 | - 其他系统 144 | 145 | 146 | 由使用方自己负责解释。 147 | 148 | ### 6.2 Subject 和schema的关系 149 | 150 | - 一个subject包含多个版本的schema，是1:N的关系。 151 | 152 | - subject层级提供兼容性设置，多个schema按照该设置演进。 153 | 154 | - 全局唯一标识定义在schema中，由该id可以找到唯一的schema，是1:1的关系。 155 | 156 | - subject+version同样可以唯一定位到一个schema。 157 | 158 | 159 | 160 | 161 | ## 七、REST 接口定义 162 | 163 | - **公共参数** 164 | 165 | | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 166 | | ------------ | ------------- | -------- | -------- | -------- | 167 | | 请求公共参数 | tenant | string | 非必选 | 租户 | 168 | | | namespace | string | 非必选 | 命名空间 | 169 | | 返回公共参数 | errorCode | int | 必选 | 错误码 | 170 | | | errorMessage | string | 必选 | 错误解释 | 171 | 172 | - **版本规则** 173 | 174 | Schema的版本号默认采用递增的方式增加，可以使用latest替代版本号来获取最新版本的schema，但是latest在获取的那一刻可能会有新版本的schema产生。 175 | 176 | 例如，通过以下请求获取test-value下最新版本的schema定义： 177 | 178 | ```sh 179 | curl -X GET http://localhost:8081/subjects/test-value/versions/latest/schema 180 | ``` 181 | 182 | 183 | 184 | 185 | 186 | ### 7.1 Schema相关接口 187 | 188 | #### 7.1.1 根据ID获取schema详细信息 189 | 190 | - URL 191 | 192 | 193 | ​ GET /schemas/{string: id} 194 | 195 | - 请求参数 196 | 197 | 198 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 199 | | -------- | -------- | -------- | ---------------- | 200 | | id | string | 是 | schema的唯一标识 | 201 | 202 | - 响应参数 203 | 204 | 205 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 206 | | -------- | -------- | -------- | -------------------- | 207 | | name | string | 否 | schema 名称 | 208 | | id | string | 是 | schema的唯一标识 | 209 | | comment | string | 否 | schema 描述| 210 | | serialization | string | 否 | schema 序列化信息: JSON, AVRO, etc | 211 | | schemaDefinition | json | 是 | schema 定义内容 | 212 | | validator | string | 否 | schema 数据校验 | 213 | | version | string | 是 | schema 版本 | 214 | 215 | - 错误码 216 | 217 | 401： 218 | 219 | ​ 40101 - 未授权错误 220 | 221 | 404： 222 | 223 | ​ 40401 - schema信息不存在 224 | 225 | 500： 226 | 227 | ​ 50001 - 存储服务错误 228 | 229 | - 请求示例 230 | 231 | 232 | ```shell 233 | curl -X GET http://localhost:8081/schema/20 234 | ``` 235 | 236 | - 响应示例 237 | 238 | 239 | ```json 240 | { 241 | "version": 1, 242 | "id": "20", 243 | "serialization": "PB", 244 | "schemaDefinition": [{ 245 | "name": "id", 246 | "type": "string" 247 | }, 248 | { 249 | "name": "age", 250 | "type": "short" 251 | } 252 | ], 253 | "validator": "a.groovy", 254 | "comment": "user information" 255 | } 256 | ``` 257 | 258 | 259 | 260 | #### 7.1.2 根据ID获取所属的subject以及对应的版本号 261 | 262 | - URL 263 | 264 | 265 | ​ GET /schemas/{string: id}/subject 266 | 267 | - 请求参数 268 | 269 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 270 | | -------- | -------- | -------- | ---------------- | 271 | | id | string | 是 | schema的唯一标识 | 272 | 273 | - 响应参数 274 | 275 | 276 | | 参数名称 | 参数类型 | 参数说明 | 277 | | -------- | -------- | -------- | 278 | | subject | string | 主题名称 | 279 | | version | int | 版本 | 280 | 281 | - 错误码 282 | 283 | 401： 284 | 285 | ​ 40101 - 未授权错误 286 | 287 | 404： 288 | 289 | ​ 40401 - schema信息不存在 290 | 291 | 500： 292 | 293 | ​ 50001 - 存储服务错误 294 | 295 | - 请求示例 296 | 297 | 298 | ```shell 299 | curl -X GET http://localhost:8081/schemas/20/subject 300 | ``` 301 | 302 | - 响应示例 303 | 304 | 305 | ```json 306 | {"subject":"test-topic","version":1} 307 | ``` 308 | 309 | 310 | 311 | ### 7.2 Subject 相关接口 312 | 313 | #### 7.2.1 获取所有的subject 314 | 315 | - URL 316 | 317 | 318 | GET /subjects 319 | 320 | - 请求参数 321 | 322 | 无 323 | 324 | - 响应参数 325 | 326 | 327 | | 参数名称 | 参数类型 | 参数说明 | 328 | | -------- | --------- | --------------- | 329 | | name | JsonArray | subject名称列表 | 330 | 331 | - 错误码 332 | 333 | 401： 334 | 335 | ​ 40101 - 未授权错误 336 | 337 | 500： 338 | 339 | ​ 50001 - 存储服务错误 340 | 341 | - 请求示例 342 | 343 | 344 | ```shell 345 | curl -X GET http://localhost:8081/subjects 346 | ``` 347 | 348 | - 响应示例 349 | 350 | 351 | ```json 352 | {"name": ["subject1", "subject2"] } 353 | ``` 354 | 355 | 356 | 357 | #### 7.2.2 获取subject定义 358 | 359 | - URL 360 | 361 | 362 | GET /subjects/(string: subject) 363 | 364 | - 请求参数 365 | 366 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 367 | | -------- | -------- | -------- | ----------- | 368 | | subject | string | 必选 | subject名称 | 369 | 370 | - 响应参数 371 | 372 | 373 | | 参数名称 | 参数类型 | 参数说明 | 374 | | ------------- | -------- | ---------------------- | 375 | | subject | string | subject名称subject名称 | 376 | | namespace | string | 命名空间 | 377 | | tenant | string | 租户 | 378 | | app | string | 所属应用 | 379 | | compatibility | string | 兼容性设置 | 380 | | coordinate | string | 坐标 | 381 | | status | string | 状态 | 382 | | description | string | 描述 | 383 | | createdTime | string | subject注册的时间 | 384 | | lastModifiedTime | string | subject最近更新的时间 | 385 | 386 | - 错误码 387 | 388 | 401： 389 | 390 | 40101 - 未授权错误 391 | 392 | 404： 393 | 394 | 40401 - subject信息不存在 395 | 396 | 500： 397 | 398 | 50001 - 存储服务错误 399 | 400 | - 请求示例 401 | 402 | 403 | ```shell 404 | curl -X GET http://localhost:8081/subjects/test-value 405 | ``` 406 | 407 | - 响应示例 408 | 409 | 410 | ```json 411 | { 412 | "subject": "test-topic", 413 | "namespace": "org.apache.rocketmq", 414 | "tenant": "messaging/rocketmq", 415 | "app": "rocketmq", 416 | "description": "JSON", 417 | "compatibility": "NONE", 418 | "createdTime": "2021-09-14T02:26:09.018", 419 | "lastModifiedTime": "2021-09-15T02:26:09.018" 420 | } 421 | ``` 422 | 423 | 424 | #### 7.2.3 获取对应subject的所有版本 425 | 426 | - URL 427 | 428 | 429 | GET /subjects/(string: subject)/versions 430 | 431 | - 请求参数 432 | 433 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 434 | | -------- | -------- | -------- | ----------- | 435 | | subject | string | 必选 | subject名称 | 436 | 437 | - 响应参数 438 | 439 | 440 | | 参数名称 | 参数类型 | 参数说明 | 441 | | -------- | -------- | -------- | 442 | | version | int | 版本号 | 443 | 444 | - 错误码 445 | 446 | 401： 447 | 448 | ​ 40101 - 未授权错误 449 | 450 | 404： 451 | 452 | ​ 40401 - subject信息不存在 453 | 454 | 500： 455 | 456 | ​ 50001 - 存储服务错误 457 | 458 | - 请求示例 459 | 460 | 461 | ```shell 462 | curl -X GET http://localhost:8081/subjects/test-value/versions 463 | ``` 464 | 465 | - 响应示例 466 | 467 | 468 | ```json 469 | { "version": [1, 2, 3, 4] } 470 | ``` 471 | 472 | #### 7.2.4 根据subject以及schema版本获取schema定义 473 | 474 | - URL 475 | 476 | 477 | ​ GET /subjects/(string: subject)/versions/(version: version)/schema 478 | 479 | - 请求参数 480 | 481 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 482 | | -------- | -------- | -------- | ------------ | 483 | | subject | string | 必选 | subject名称 | 484 | | version | int | 必选 | schema版本号 | 485 | 486 | - 响应参数 487 | 488 | 489 | | 参数名称 | 参数类型 | 参数说明 | 490 | | ------------- | -------- | ---------------------- | 491 | | subject | string | subject名称subject名称 | 492 | | namespace | string | 命名空间 | 493 | | tenant | string | 租户 | 494 | | app | string | 所属应用 | 495 | | compatibility | string | 兼容性设置 | 496 | | coordinate | string | 坐标 | 497 | | status | string | 状态 | 498 | | description | string | 描述 | 499 | | createdTime | string | subject注册的时间 | 500 | | lastModifiedTime | string | subject最近更新的时间 | 501 | | schema | JSON | schema的具体信息 | 502 | 503 | 504 | - 错误码 505 | 506 | 401： 507 | 508 | ​ 40101 - 未授权错误 509 | 510 | 404： 511 | 512 | ​ 40401 - subject信息不存在 513 | 514 | ​ 40402 - version不存在 515 | 516 | 500： 517 | 518 | ​ 50001 - 存储服务错误 519 | 520 | - 请求示例 521 | 522 | 523 | ```shell 524 | curl -X GET http://localhost:8081/subjects/test-value/versions/1/schema 525 | ``` 526 | 527 | - 响应示例 528 | 529 | 530 | ```json 531 | { 532 | "subject": "test-topic", 533 | "namespace": "org.apache.rocketmq", 534 | "tenant": "messaging/rocketmq", 535 | "app": "rocketmq", 536 | "description": "rocketmq user information", 537 | "compatibility": "NONE", 538 | "createdTime": "2021-09-14T02:26:09.018", 539 | "lastModifiedTime": "2021-09-15T02:26:09.018", 540 | "format": "AVRO", 541 | "schema": { 542 | "version": 1, 543 | "id": "20", 544 | "serialization": "PB", 545 | "schemaDefinition": [{ 546 | "name": "id", 547 | "type": "string" 548 | }, { 549 | "name": "amount", 550 | "type": "double" 551 | }], 552 | "validator": "a.groovy", 553 | "comment": "rocketmq user information" 554 | } 555 | } 556 | ``` 557 | 558 | #### 7.2.5 新增、修改subject 559 | 560 | 如果不存在相关的subject，则新增subject。 561 | 562 | 如果存在，则修改相关属性。 563 | 564 | - URL 565 | 566 | 567 | ​ POST /subjects/(string: subject)/ 568 | 569 | - 请求参数 570 | 571 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 572 | | ------------- | -------- | -------- | ----------- | 573 | | tenant | string | 必选 | 租户 | 574 | | namespace | string | 必选 | 命名空间 | 575 | | subject | string | 必选 | subject名称 | 576 | | app | string | | 所属app | 577 | | description | string | | 描述 | 578 | | status | string | 必选 | 状态 | 579 | | compatibility | string | | 兼容性策略 | 580 | | coordinate | string | | Maven坐标 | 581 | 582 | - 响应参数 583 | 584 | | 参数名称 | 参数类型 | 参数说明 | 585 | | ------------- | -------- | ----------- | 586 | | tenant | string | 租户 | 587 | | namespace | string | 命名空间 | 588 | | subject | string | subject名称 | 589 | | app | string | 所属app | 590 | | description | string | 描述 | 591 | | status | string | 状态 | 592 | | compatibility | string | 兼容性策略 | 593 | | coordinate | string | Maven坐标 | 594 | | createdTime | string | subject注册的时间 | 595 | | lastModifiedTime | string | subject最近更新的时间 | 596 | 597 | - 错误码 598 | 599 | 401： 600 | 601 | ​ 40101 - 未授权错误 602 | 603 | 409： 604 | 605 | 40901 - 兼容性错误 606 | 607 | 422: 608 | 609 | ​ 42201 - 格式错误 610 | 611 | 500： 612 | 613 | ​ 50001 - 存储服务错误 614 | 615 | ​ 50002 - 超时 616 | 617 | - 请求示例 618 | 619 | 620 | ```shell 621 | curl -X POST -H "Content-Type: application/vnd.openschema.v1+json" \ 622 | http://localhost:8081/subjects/test-value/ --data ' 623 | { 624 | "subject": "test-topic", 625 | "namespace": "org.apache.rocketmq", 626 | "tenant": "messaging/rocketmq", 627 | "app": "rocketmq", 628 | "description": "rocketmq user information", 629 | "compatibility": "NONE", 630 | "status": "deprecated" 631 | } 632 | ' 633 | ``` 634 | 635 | - 响应示例 636 | 637 | 638 | ```json 639 | { 640 | "subject": "test-topic", 641 | "namespace": "org.apache.rocketmq", 642 | "tenant": "messaging/rocketmq", 643 | "app": "rocketmq", 644 | "description": "rocketmq user information", 645 | "compatibility": "NONE", 646 | "createdTime": "2021-09-14T02:26:09.018", 647 | "lastModifiedTime": "2021-09-15T02:26:09.018", 648 | "status": "deprecated" 649 | } 650 | ``` 651 | 652 | #### 7.2.6 新增，注册Schema 653 | 654 | 如果已有相同定义，则直接返回原有的id。 655 | 656 | 如果无相同定义，则检查兼容性设置，创建新的schema，返回新的id。 657 | 658 | - URL 659 | 660 | 661 | ​ POST /subjects/(string: subject)/versions 662 | 663 | - 请求参数 664 | 665 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 666 | | -------- | -------- | -------- | -------------- | 667 | | subject | string | 必选 | subject名称 | 668 | | schema | Json | 必选 | 参考schema定义 | 669 | 670 | - 响应参数 671 | 672 | 673 | | 参数名称 | 参数类型 | 参数说明 | 674 | | -------- | -------- | --------- | 675 | | id | string | schema ID | 676 | 677 | - 错误码 678 | 679 | 401： 680 | 681 | ​ 40101 - 未授权错误 682 | 683 | 409: 684 | 685 | ​ 40901 - 兼容性错误 686 | 687 | 422: 688 | 689 | ​ 42201 - 格式错误 690 | 691 | 500： 692 | 693 | ​ 50001 - 存储服务错误 694 | 695 | ​ 50002 - 超时 696 | 697 | - 请求示例 698 | 699 | 700 | ```shell 701 | curl -X POST -H "Content-Type: application/vnd.openschema.v1+json" \ 702 | http://localhost:8081/subjects/test-value/versions --data ' 703 | { 704 | "serialization": "PB", 705 | "schemaDefinition": [{ 706 | "name": "id", 707 | "type": "string" 708 | }, { 709 | "name": "amount", 710 | "type": "double" 711 | }] 712 | }' 713 | ``` 714 | 715 | - 响应示例 716 | 717 | 718 | ```json 719 | {"id":"10"} 720 | ``` 721 | 722 | #### 7.2.7 删除subject以及其对应所有版本的schema 723 | 724 | - URL 725 | 726 | 727 | DELETE /subjects/(string: subject) 728 | 729 | - 请求参数 730 | 731 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 732 | | -------- | -------- | -------- | ----------- | 733 | | subject | string | 必选 | subject名称 | 734 | 735 | - 响应参数 736 | 737 | 738 | | 参数名称 | 参数类型 | 参数说明 | 739 | | -------- | -------- | -------- | 740 | | version | int | 版本号 | 741 | 742 | - 错误码 743 | 744 | 401： 745 | 746 | ​ 40101 - 未授权错误 747 | 748 | 404： 749 | 750 | ​ 40401 - subject信息不存在 751 | 752 | 500： 753 | 754 | ​ 50001 - 存储服务错误 755 | 756 | - 请求示例 757 | 758 | 759 | ```shell 760 | curl -X DELETE http://localhost:8081/subjects/test-value 761 | ``` 762 | 763 | - 响应示例 764 | 765 | 766 | ```json 767 | { "version": [1, 2, 3, 4] } 768 | ``` 769 | 770 | #### 7.2.8 删除指定subject指定版本的schema 771 | 772 | - URL 773 | 774 | 775 | ​ DELETE /subjects/(string: subject)/versions/(version: version) 776 | 777 | - 请求参数 778 | 779 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 780 | | -------- | -------- | -------- | ----------- | 781 | | subject | string | 必选 | subject名称 | 782 | | version | int | 必选 | 版本号 | 783 | 784 | - 响应参数 785 | 786 | | 参数名称 | 参数类型 | 参数说明 | 787 | | -------- | -------- | -------- | 788 | | version | int | 版本号 | 789 | 790 | - 错误码 791 | 792 | 401： 793 | 794 | 40101 - 未授权错误 795 | 796 | 404: 797 | 798 | 40401 - subject信息不存在 799 | 800 | 40402 - version信息不存在 801 | 802 | 409： 803 | 804 | 40901 - 兼容性错误 805 | 806 | 500： 807 | 808 | 50001 - 存储服务错误 809 | 810 | - 请求示例 811 | 812 | 813 | ```shell 814 | curl -X DELETE http://localhost:8081/subjects/test-value/versions/1 815 | ``` 816 | 817 | - 响应示例 818 | 819 | 820 | ```json 821 | { "version": 1 } 822 | ``` 823 | 824 | 825 | 826 | ### 7.3 兼容性相关接口 827 | 828 | #### 7.3.1 测试是否兼容 829 | 830 | - URL 831 | 832 | 833 | ​ POST /compatibility/subjects/(string: subject)/versions/(version: version) 834 | 835 | - 请求参数 836 | 837 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 838 | | -------- | -------- | -------- | ----------- | 839 | | subject | string | 必选 | subject名称 | 840 | | version | int | 必选 | 版本号 | 841 | | schema | json | 必选 | | 842 | 843 | - 响应参数 844 | 845 | | 参数名称 | 参数类型 | 参数说明 | 846 | | ------------- | -------- | -------- | 847 | | isCompatible | boolean | 是否兼容 | 848 | 849 | - 错误码 850 | 851 | 401： 852 | 853 | ​ 40101 - 未授权错误 854 | 855 | 404: 856 | 857 | ​ 40401 - subject信息不存在 858 | 859 | ​ 40402 - version信息不存在 860 | 861 | 422:格式错误 862 | 863 | ​ 42201: schema格式错误 864 | 865 | ​ 42202：版本格式错误 866 | 867 | 500： 868 | 869 | ​ 50001 - 存储服务错误 870 | 871 | - 请求示例 872 | 873 | 874 | ```shell 875 | curl -X POST -H "Content-Type: application/vnd.openschema.v1+json" \ 876 | --data'{"schema": "{"type": "string"}"}' \ 877 | http://localhost:8081/compatibility/subjects/test-value/versions/latest 878 | ``` 879 | 880 | - 响应示例 881 | 882 | 883 | ```json 884 | {"isCompatible": true} 885 | ``` 886 | 887 | 888 | 889 | #### 7.3.2 兼容性配置获取 890 | 891 | - URL 892 | 893 | 894 | ​ GET /config/(string: subject) 895 | 896 | - 请求参数 897 | 898 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 899 | | -------- | -------- | -------- | ----------- | 900 | | subject | string | 必选 | subject名称 | 901 | 902 | - 响应参数 903 | 904 | | 参数名称 | 参数类型 | 参数说明 | 905 | | ------------- | -------- | -------- | 906 | | compatibility | string | 是否兼容 | 907 | 908 | - 错误码 909 | 910 | 401： 911 | 912 | ​ 40101 - 未授权错误 913 | 914 | 404: 915 | 916 | ​ 40401 - subject信息不存在 917 | 918 | 500： 919 | 920 | ​ 50001 - 存储服务错误 921 | 922 | - 请求示例 923 | 924 | 925 | ```shell 926 | curl -X GET -H "Content-Type: application/vnd.openschema.v1+json" \ 927 | http://localhost:8081/config/test-value 928 | ``` 929 | 930 | - 响应示例 931 | 932 | 933 | ```json 934 | {"compatibility": "FULL"} 935 | ``` 936 | 937 | 938 | 939 | #### 7.3.3 兼容性配置更新 940 | 941 | - URL 942 | 943 | 944 | ​ PUT /config/(string: subject) 945 | 946 | - 请求参数 947 | 948 | | 参数名称 | 参数类型 | 是否必选 | 参数说明 | 949 | | ------------- | -------- | -------- | ----------- | 950 | | subject | string | 必选 | subject名称 | 951 | | compatibility | string | | 兼容性 | 952 | 953 | - 响应参数 954 | 955 | | 参数名称 | 参数类型 | 参数说明 | 956 | | ------------- | -------- | -------- | 957 | | compatibility | string | 兼容性 | 958 | 959 | - 错误码 960 | 961 | 401： 962 | 963 | ​ 40101 - 未授权错误 964 | 965 | 404: 966 | 967 | ​ 40401 - subject信息不存在 968 | 969 | 409： 970 | 971 | 40901 - 兼容性错误 972 | 973 | 422: 974 | 975 | ​ 42201 - compatibility格式错误 976 | 977 | 500： 978 | 979 | ​ 50001 - 存储服务错误 980 | 981 | - 请求示例 982 | 983 | 984 | ```shell 985 | curl -X PUT -H "Content-Type: application/vnd.openschema.v1+json" \ 986 | --data'{"compatibility": "NONE"}' \ 987 | http://localhost:8081/config/test-value 988 | ``` 989 | 990 | - 响应示例 991 | 992 | 993 | ```json 994 | {"compatibility": "NONE"} 995 | ``` 996 | -------------------------------------------------------------------------------- /spec_en.md: -------------------------------------------------------------------------------- 1 | # OpenSchema Specification 2 | 3 | 4 | ## 1. Abstract 5 | 6 | This specification defines a vendor-neutral OpenSchema metadata and interaction modes, targeting the data schema domain. 7 | 8 | ## Table of Contents 9 | 10 | - [Compatibility Mode](#compatibility-mode) 11 | - [Content Types](#3-content-types) 12 | - [Error Codes](#4-error-codes) 13 | - [Schema Format](#5-schema-format) 14 | - [Metadata Information](#51-metadata-information) 15 | - [Schema Definition](#52-schema-definition) 16 | - [Relationship Between Subjects, Topics and Schemas](#6-relationship-between-subjects-topics-and-schemas) 17 | - [REST Interface Definition](#7-rest-interface-definition) 18 | - [Schema related APIs](#71-schema-related-apis) 19 | - [Subject related APIs](#72-subject-related-apis) 20 | - [Compatibility related APIs](#73-compatibility-related-apis) 21 | 22 | ## 2. Compatibility Mode 23 | 24 | The compatibility mode defines the compatibility rules concerning which changes you’re allowed to make to the schema without breaking the consumers, and how to handle upgrades for the different types of schema changes 25 | 26 | | Compatibility Settings | Description | 27 | | ------------------- | ------------------------------------------------------------ | 28 | | BACKWARD (default) | Consumers using the new schema can read data produced with the last schema.| 29 | | BACKWARD_TRANSITIVE | Consumers using the new schema can read data sent by the producer using all previously registered schemas.| 30 | | Forward | data produced with a new schema can be read by consumers using the last schema.| 31 | | Forward_TRANSITIVE | data produced with a new schema can be read by consumers using all registered schemas.| 32 | | FULL | The new schema is backward and forward compatible with the newly registered schema.| 33 | | FULL_TRANSITIVE | The newly registered schema is backward and forward compatible with all previously registered schemas | 34 | | NONE | Schema compatibility checks are disabled.| 35 | 36 | 37 | 38 | ## 3. Content Types 39 | 40 | The OpenSchema REST service communicates using HTTP+JSON. 41 | 42 | The request should specify the most specific format and version information via the HTTP Accept header, and MAY include several authentication settings: 43 | 44 | > Accept:application/vnd.openschema.v1+json 45 | 46 | 47 | 48 | ## 4. Error Codes 49 | 50 | The HTTP response of all requests is consistent with the HTTP standard. The detailed error code is determined by the returned JSON response. The format is as follows: 51 | 52 | ```json 53 | { 54 | "errorCode": 422, 55 | "errorMessage": "schema info cannot be empty" 56 | } 57 | ``` 58 | 59 | 60 | 61 | ## 5. Schema Format 62 | 63 | ### 5.1 Metadata Information 64 | 65 | The following metadata information describes Subject definition in OpenSchema specification. 66 | 67 | |Parameter Name|Description|Example| 68 | | ------------- | ------------------------ | ------------------------------- | 69 | | tenant | Tenant | org/apache/rocketmq/mybank | 70 | | namespace | Namespace | Cluster name, for example, rocketmq-cluster | 71 | | subject | Subject name | For example, use the topic name as the subject name. | 72 | | app | Application deployment unit of the service provider | | 73 | | description | Description | Provided by the applicant | 74 | | status | Subject status | For example, released or abandoned | 75 | | compatibility | Compatibility setting | None, forward compatibility, backward compatibility, and full compatibility| 76 | | coordinate | Maven coordinate | Maven coordinate of the JAR of the payload| 77 | | createdTime | the time when a subject was registered | 2021-09-14T02:26:09.018 | 78 | | lastModifiedTime | the time when a subject was last updated | 2021-09-15T02:26:09.018 | 79 | | format | Enumeration of schema types: NONE, JSON, PB, AVRO, USER-DEFINED, Int, Long, String, and Map | If no schema is provided in a message, the schema type is NONE. You can also add a schema to the current message. For example, you can use PB to describe the format of the data transmitted by the RocketMQ. 80 | | schema | Data format | Associated data format description. For details, see the following table. | 81 | 82 | Example: 83 | 84 | ```json 85 | { 86 | "tenant": "messaging/rocketmq", 87 | "namespace": "org.apache.rocketmq", 88 | "subject": "test-topic", 89 | "app": "rocketmq", 90 | "description": "rocketmq test subject", 91 | "status": "released", 92 | "compatibility": "NONE", 93 | "coordinate": "maven-group:package:1.0.0", 94 | "createdTime": "2021-09-14T02:26:09.018", 95 | "lastModifiedTime": "2021-09-15T02:26:09.018", 96 | "format": "AVRO", 97 | "schema": {} 98 | } 99 | ``` 100 | 101 | ### 5.2 Schema Definition 102 | 103 | The Payload Schema is used to describe the payload data of a message. 104 | 105 | |Parameter Name|Description|Example| 106 | | ---------------- | ------------------------------------------------------------ | ------------------------------------------------------------ | 107 | | name | Payload name, which can be null. For example, the payload of a message does not need a name. | | 108 | | id | Globally unique identifier, which is used to identify the schema | | 109 | | comment | Payload comment | | 110 | | serialization | Serialization mode: Hissian, JSON, PB, AVRO, and user-defined | | 111 | | schemaDefinition | Schema content, which is used to describe the data format. | NONE: none PB: PB description file AVRO: AVRO schema content USER-DEFINED: user-defined information Basic content type: none | 112 | | validator | Object value validator | Validates the values of objects described in the schema.| 113 | | version | Schema version | For example, the payload may change. In this case, the version is required to identify different schemas. | 114 | 115 | Example: 116 | 117 | ```json 118 | { 119 | "name": "rocketmq-user-topic", 120 | "id": "SLEd-3334-XSSFE-44983", 121 | "comment": "Rocketmq user information", 122 | "serialization": "", 123 | "schemaDefinition": [{ 124 | "name": "id", 125 | "type": "string" 126 | }, 127 | { 128 | "name": "age", 129 | "type": "short" 130 | } 131 | ], 132 | "validator": "a.groovy", 133 | "version": 1 134 | } 135 | ``` 136 | 137 | 138 | 139 | ## 6. Relationship Between Subjects, Topics and Schemas 140 | 141 | ### 6.1 Relationship Between Subjects and Topics 142 | 143 | - Messaging system 144 | 145 | 146 | Subject Name by default, the value is a topic name, which defines the format of the message body. The value can be extended by suffix ${topic}-${suffix}. For example, in Kafka, Kafka-Key is generally used to define the data format of the key in Kafka messages. 147 | 148 | - Other systems 149 | 150 | 151 | Subject Name can be defined and customized according to other system's requirement. 152 | 153 | ### 6.2 Relationship Between Subjects and Schemas 154 | 155 | - A subject contains multiple versions of schemas, and the relationship is 1:N. 156 | 157 | - Compatibility settings are defined at the subject level. Multiple versions of schemas evolve based on the settings. 158 | 159 | - The globally unique ID is defined in a schema. You can find a unique schema based on the ID. The relationship is 1:1. 160 | 161 | - Subject+version can also uniquely locate a schema. 162 | 163 | 164 | 165 | 166 | ## 7. REST Interface Definition 167 | 168 | - **Common Parameter** 169 | 170 | | | Parameter name | Parameter type | Required or not | Parameter description | 171 | | ------------ | ------------- | -------- | -------- | -------- | 172 | | Common request parameter | tenant | string | Optional | Tenant | 173 | | | namespace | string | Optional | Namespace | 174 | | Common Response parameter | errorCode | int | Required | Error code | 175 | | | errorMessage | string | Required | Error message | 176 | 177 | - **Version Rules** 178 | 179 | By default, the schema version number increases in ascending order. You can use the latest version number to obtain the latest schema version. However, a new schema version may be registered right after the latest version number is retrieved. 180 | 181 | For example, the following request is used to obtain the latest schema definition under test-value: 182 | 183 | ```sh 184 | curl -X GET http://localhost:8081/subjects/test-value/versions/latest/schema 185 | ``` 186 | 187 | 188 | 189 | 190 | 191 | ### 7.1 Schema related APIs 192 | 193 | #### 7.1.1 Obtaining Schema Details by ID 194 | 195 | - URL 196 | 197 | 198 | GET /schemas/{string: id} 199 | 200 | - Request parameters 201 | 202 | 203 | |Parameter name|Parameter type|Required or not|Parameter description| 204 | | -------- | -------- | -------- | ---------------- | 205 | | id | string | Yes | Unique ID of a schema | 206 | 207 | - Response parameters 208 | 209 | 210 | |Parameter name|Parameter type|Required or not|Parameter description| 211 | | -------- | -------- | -------- | -------------------- | 212 | | name | string | No | schema name | 213 | | id | string | Yes | Unique ID of a schema | 214 | | comment | string | No | description for this schema | 215 | | serialization | string | No | schema serialization mode: JSON, AVRO, etc | 216 | | schemaDefinition | json | Yes | schema definition content | 217 | | validator | string | No | schema value validator | 218 | | version | string | Yes | schema version | 219 | 220 | - Error code. 221 | 222 | 401: 223 | 224 | 40101 - Unauthorized Error 225 | 226 | 404: 227 | 228 | 40401: The corresponding schema information does not exist. 229 | 230 | 500: 231 | 232 | 50001 - Storage Service Error 233 | 234 | - Sample request 235 | 236 | 237 | ```shell 238 | curl -X GET http://localhost:8081/schema/20 239 | ``` 240 | 241 | - Response Example 242 | 243 | 244 | ```json 245 | { 246 | "version": 1, 247 | "id": "20", 248 | "serialization": "PB", 249 | "schemaDefinition": [{ 250 | "name": "id", 251 | "type": "string" 252 | }, 253 | { 254 | "name": "age", 255 | "type": "short" 256 | } 257 | ], 258 | "validator": "a.groovy", 259 | "comment": "user information" 260 | } 261 | ``` 262 | 263 | 264 | 265 | #### 7.1.2 Obtaining the Subject name and Version Number Based on the ID 266 | 267 | - URL 268 | 269 | 270 | ​ GET /schemas/{string: id}/subject 271 | 272 | - Request parameters 273 | 274 | |Parameter name|Parameter type|Required or not|Parameter description| 275 | | -------- | -------- | -------- | ---------------- | 276 | | id | string | Unique ID of a | schema | 277 | 278 | - Response parameters 279 | 280 | 281 | | Parameter Name| Parameter Type| Parameter Description| 282 | | -------- | -------- | -------- | 283 | | subject | string | Subject name | 284 | | version | int | Version | 285 | 286 | - Error code. 287 | 288 | 401: 289 | 290 | 40101 - Unauthorized Error 291 | 292 | 404: 293 | 294 | 40401: The corresponding schema information does not exist. 295 | 296 | 500: 297 | 298 | 50001 - Storage Service Error 299 | 300 | - Sample request 301 | 302 | 303 | ```shell 304 | curl -X GET http://localhost:8081/schemas/20/subject 305 | ``` 306 | 307 | - Response Example 308 | 309 | 310 | ```json 311 | {"subject":"test-topic","version":1} 312 | ``` 313 | 314 | 315 | 316 | ### 7.2 Subject related APIs 317 | 318 | #### 7.2.1 Obtaining All Subjects 319 | 320 | - URL 321 | 322 | 323 | GET /subjects 324 | 325 | - Request parameters 326 | 327 | None 328 | 329 | - Response parameters 330 | 331 | 332 | | Parameter Name| Parameter Type| Parameter Description| 333 | | -------- | --------- | --------------- | 334 | | name | JsonArray | Subject name list | 335 | 336 | - Error code. 337 | 338 | 401: 339 | 340 | 40101 - Unauthorized Error 341 | 342 | 500: 343 | 344 | 50001 - Storage Service Error 345 | 346 | - Sample request 347 | 348 | 349 | ```shell 350 | curl -X GET http://localhost:8081/subjects 351 | ``` 352 | 353 | - Response Example 354 | 355 | 356 | ```json 357 | { "name": ["subject1", "subject2"] } 358 | ``` 359 | 360 | 361 | #### 7.2.2 Obtaining Subject Definitions 362 | 363 | - URL 364 | 365 | 366 | GET /subjects/(string: subject) 367 | 368 | - Request parameters 369 | 370 | |Parameter name|Parameter type|Required or not|Parameter description| 371 | | -------- | -------- | -------- | ----------- | 372 | | subject | string | Required | Subject name | 373 | 374 | - Response parameters 375 | 376 | 377 | | Parameter Name| Parameter Type| Parameter Description| 378 | | ------------- | -------- | ---------------------- | 379 | | subject | string | Subject name | 380 | | namespace | string | Namespace | 381 | | tenant | string | Tenant | 382 | | app | string | Application | 383 | | compatibility | string | Compatibility setting | 384 | | coordinate | string | coordinate | 385 | | status | string | Status | 386 | | description | string | description | 387 | | createdTime | string | the time when a subject was registered | 388 | | lastModifiedTime | string | the time when a subject was last updated | 389 | 390 | - Error code. 391 | 392 | 401: 393 | 394 | 40101 - Unauthorized Error 395 | 396 | 404: 397 | 398 | 40401: The corresponding openschema information does not exist. 399 | 400 | 500: 401 | 402 | 50001 - Storage Service Error 403 | 404 | - Sample request 405 | 406 | 407 | ```shell 408 | curl -X GET http://localhost:8081/subjects/test-value 409 | ``` 410 | 411 | - Response Example 412 | 413 | 414 | ```json 415 | { 416 | "subject": "test-topic", 417 | "namespace": "org.apache.rocketmq", 418 | "tenant": "messaging/rocketmq", 419 | "app": "rocketmq", 420 | "description": "JSON", 421 | "compatibility": "NONE", 422 | "createdTime": "2021-09-14T02:26:09.018", 423 | "lastModifiedTime": "2021-09-15T02:26:09.018" 424 | } 425 | ``` 426 | 427 | #### 7.2.3 Obtaining All Versions of a Subject 428 | 429 | - URL 430 | 431 | 432 | GET /subjects/(string: subject)/versions 433 | 434 | - Request parameters 435 | 436 | |Parameter name|Parameter type|Required or not|Parameter description| 437 | | -------- | -------- | -------- | ----------- | 438 | | subject | string | Required | Subject name | 439 | 440 | - Response parameters 441 | 442 | 443 | | Parameter Name| Parameter Type| Parameter Description| 444 | | -------- | -------- | -------- | 445 | | version | int | Version number | 446 | 447 | - Error code. 448 | 449 | 401: 450 | 451 | 40101 - Unauthorized Error 452 | 453 | 404: 454 | 455 | 40401: The corresponding openschema information does not exist. 456 | 457 | 500: 458 | 459 | 50001 - Storage Service Error 460 | 461 | - Sample request 462 | 463 | 464 | ```shell 465 | curl -X GET http://localhost:8081/subjects/test-value/versions 466 | ``` 467 | 468 | - Response Example 469 | 470 | 471 | ```json 472 | { "version": [1, 2, 3, 4] } 473 | ``` 474 | 475 | #### 7.2.4 Obtaining Schema Definitions Based on Subject and Schema Version 476 | 477 | - URL 478 | 479 | 480 | GET /subjects/(string: subject)/versions/(version: version)/schema 481 | 482 | - Request parameters 483 | 484 | |Parameter name|Parameter type|Required or not|Parameter description| 485 | | -------- | -------- | -------- | ------------ | 486 | | subject | string | Required | Subject name | 487 | | version | int | Required | Schema version number | 488 | 489 | - Response parameters 490 | 491 | 492 | | Parameter Name| Parameter Type| Parameter Description| 493 | | ------------- | -------- | ---------------------- | 494 | | subject | string | Subject name | 495 | | namespace | string | Namespace | 496 | | tenant | string | Tenant | 497 | | app | string | Application | 498 | | compatibility | string | Compatibility setting | 499 | | coordinate | string | coordinate | 500 | | status | string | Status | 501 | | description | string | description | 502 | | createdTime | string | the time when a subject was registered | 503 | | lastModifiedTime | string | the time when a subject was last updated | 504 | | schema | JSON | Refer to the schema definition | 505 | 506 | - Error code. 507 | 508 | 401: 509 | 510 | 40101 - Unauthorized Error 511 | 512 | 404: 513 | 514 | 40401: The corresponding openschema information does not exist. 515 | 516 | 40402 - The version does not exist. 517 | 518 | 500: 519 | 520 | 50001 - Storage Service Error 521 | 522 | - Sample request 523 | 524 | 525 | ```shell 526 | curl -X GET http://localhost:8081/subjects/test-value/versions/1/schema 527 | ``` 528 | 529 | - Response Example 530 | 531 | 532 | ```json 533 | { 534 | "subject": "test-topic", 535 | "namespace": "org.apache.rocketmq", 536 | "tenant": "messaging/rocketmq", 537 | "app": "rocketmq", 538 | "description": "rocketmq user information", 539 | "compatibility": "NONE", 540 | "createdTime": "2021-09-14T02:26:09.018", 541 | "lastModifiedTime": "2021-09-15T02:26:09.018", 542 | "format": "AVRO", 543 | "schema": { 544 | "version": 1, 545 | "id": "20", 546 | "serialization": "PB", 547 | "schemaDefinition": [ 548 | { 549 | "name": "id", 550 | "type": "string" 551 | }, 552 | { 553 | "name": "amount", 554 | "type": "double" 555 | } 556 | ], 557 | "validator": "a.groovy", 558 | "comment": "rocketmq user information" 559 | } 560 | } 561 | ``` 562 | 563 | 564 | #### 7.2.5 Create or Modify a Subject 565 | 566 | If the same subject does not exist, create a subject. 567 | 568 | If yes, modify the related attributes of existing subject. 569 | 570 | - URL 571 | 572 | 573 | POST /subjects/(string: subject)/ 574 | 575 | - Request parameters 576 | 577 | |Parameter name|Parameter type|Required or not|Parameter description| 578 | | ------------- | -------- | -------- | ----------- | 579 | | tenant | string | Required | Tenant | 580 | | namespace | string | Required | Namespace | 581 | | subject | string | Required | Subject name | 582 | | app | string | | Home app | 583 | | description | string | | description | 584 | | status | string | Required | Status | 585 | | compatibility | string | | Compatibility setting | 586 | | coordinate | string | | Maven coordinate | 587 | 588 | - Response parameters 589 | 590 | | Parameter Name| Parameter Type| Parameter Description| 591 | | ------------- | -------- | ----------- | 592 | | tenant | string | Tenant | 593 | | namespace | string | Namespace | 594 | | subject | string | subject name | 595 | | app | string | Home app | 596 | | description | string | description | 597 | | status | string | Status | 598 | | compatibility | string | Compatibility policy | 599 | | coordinate | string | Maven coordinate | 600 | | createdTime | string | the time when a subject was registered | 601 | | lastModifiedTime | string | the time when a subject was last updated | 602 | 603 | - Error code. 604 | 605 | 401: 606 | 607 | 40101 - Unauthorized Error 608 | 609 | 422: 610 | 611 | 42201 - Incorrect format 612 | 613 | 500: 614 | 615 | 50001 - Storage Service Error 616 | 617 | 50002 - Timeout 618 | 619 | - Sample request 620 | 621 | 622 | ```shell 623 | curl -X POST -H "Content-Type: application/vnd.openschema.v1+json" \ 624 | http://localhost:8081/subjects/test-value/ --data' 625 | { 626 | "subject": "test-topic", 627 | "namespace": "org.apache.rocketmq", 628 | "tenant": "messaging/rocketmq", 629 | "app": "rocketmq", 630 | "description": "rocketmq user information", 631 | "compatibility": "NONE", 632 | "status": "deprecated" 633 | }' 634 | ``` 635 | 636 | - Response Example 637 | 638 | 639 | ```json 640 | { 641 | "subject": "test-topic", 642 | "namespace": "org.apache.rocketmq", 643 | "tenant": "messaging/rocketmq", 644 | "app": "rocketmq", 645 | "description": "rocketmq user information", 646 | "compatibility": "NONE", 647 | "createdTime": "2021-09-14T02:26:09.018", 648 | "lastModifiedTime": "2021-09-15T02:26:09.018", 649 | "status": "deprecated" 650 | } 651 | ``` 652 | 653 | #### 7.2.6 Create and Register New Schemas 654 | 655 | If the same definition already exists, the current schema ID is returned. 656 | 657 | If no, check new schema against the subject's compatibility setting, create a new schema, and return the new ID. 658 | 659 | - URL 660 | 661 | 662 | POST /subjects/(string: subject)/versions 663 | 664 | - Request parameters 665 | 666 | |Parameter name|Parameter type|required or not|Parameter description| 667 | | -------- | -------- | -------- | -------------- | 668 | | subject | string | required | Subject name | 669 | | schema | JSON | required | Refer to the schema definition | 670 | 671 | - Response parameters 672 | 673 | 674 | | Parameter Name| Parameter Type| Parameter Description| 675 | | -------- | -------- | --------- | 676 | | id | string | schema ID | 677 | 678 | - Error code. 679 | 680 | 401: 681 | 682 | 40101 - Unauthorized Error 683 | 684 | 409: 685 | 686 | 40901 - Compatibility Error 687 | 688 | 422: 689 | 690 | 42201 - Incorrect format 691 | 692 | 500: 693 | 694 | 50001 - Storage Service Error 695 | 696 | 50002 - Timeout 697 | 698 | - Sample request 699 | 700 | 701 | ```shell 702 | curl -X POST -H "Content-Type: application/vnd.openschema.v1+json" \ 703 | http://localhost:8081/subjects/test-value/versions --data' 704 | { 705 | "serialization": "PB", 706 | "schemaDefinition": [ 707 | { 708 | "name": "id", 709 | "type": "string" 710 | }, 711 | { 712 | "name": "amount", 713 | "type": "double" 714 | } 715 | ] 716 | }' 717 | ``` 718 | 719 | - Response Example 720 | 721 | 722 | ```json 723 | {"id":"10"} 724 | ``` 725 | 726 | 727 | #### 7.2.7 Delete the subject, compatibility settings along with all versions of schemas belong to this subject. 728 | 729 | - URL 730 | 731 | 732 | DELETE /subjects/(string: subject) 733 | 734 | - Request parameters 735 | 736 | |Parameter name|Parameter type|Required or not|Parameter description| 737 | | -------- | -------- | -------- | ----------- | 738 | | subject | string | Required | Subject name | 739 | 740 | - Response parameters 741 | 742 | 743 | | Parameter Name| Parameter Type| Parameter Description| 744 | | -------- | -------- | -------- | 745 | | version | int | Version number | 746 | 747 | - Error code. 748 | 749 | 401: 750 | 751 | 40101 - Unauthorized Error 752 | 753 | 404: 754 | 755 | 40401: The corresponding openschema information does not exist. 756 | 757 | 500: 758 | 759 | 50001 - Storage Service Error 760 | 761 | - Sample request 762 | 763 | 764 | ```shell 765 | curl -X DELETE http://localhost:8081/subjects/test-value 766 | ``` 767 | 768 | - Response Example 769 | 770 | 771 | ```json 772 | { "version": [1, 2, 3, 4] } 773 | ``` 774 | 775 | #### 7.2.8 Delete a Specific Schema Version of a Subject 776 | 777 | - URL 778 | 779 | 780 | DELETE /subjects/(string: subject)/versions/(version: version) 781 | 782 | - Request parameters 783 | 784 | |Parameter name|Parameter type|Required or not|Parameter description| 785 | | -------- | -------- | -------- | ----------- | 786 | | subject | string | Required | Subject name | 787 | | version | int | Required | Version number | 788 | 789 | - Response parameters 790 | 791 | | Parameter Name| Parameter Type| Parameter Description| 792 | | -------- | -------- | -------- | 793 | | version | int | Version number | 794 | 795 | - Error code. 796 | 797 | 401: 798 | 799 | 40101 - Unauthorized Error 800 | 801 | 404: 802 | 803 | 40401: The subject does not exist. 804 | 805 | 40402-The version does not exist. 806 | 807 | 500: 808 | 809 | 50001 - Storage Service Error 810 | 811 | - Sample request 812 | 813 | 814 | ```shell 815 | curl -X DELETE http://localhost:8081/subjects/test-value/versions/1 816 | ``` 817 | 818 | - Response Example 819 | 820 | 821 | ```json 822 | { "version": 1 } 823 | ``` 824 | 825 | 826 | ### 7.3 Compatibility related APIs 827 | 828 | #### 7.3.1 Testing if new schema is compatible against Compatibility Setting of this Subject 829 | 830 | - URL 831 | 832 | 833 | ​ POST /compatibility/subjects/(string: subject)/versions/(version: version) 834 | 835 | - Request parameters 836 | 837 | |Parameter name|Parameter type|Required or not|Parameter description| 838 | | -------- | -------- | -------- | ----------- | 839 | | subject | string | Required | Subject name | 840 | | version | int | Required | Version number | 841 | | schema | json | Required | | 842 | 843 | - Response parameters 844 | 845 | | Parameter Name| Parameter Type| Parameter Description| 846 | | ------------- | -------- | -------- | 847 | | isCompatible | boolean | Compatible | 848 | 849 | - Error code. 850 | 851 | 401: 852 | 853 | 40101 - Unauthorized Error 854 | 855 | 404: 856 | 857 | 40401: The subject does not exist. 858 | 859 | 40402-The version does not exist. 860 | 861 | 422: The format is incorrect. 862 | 863 | 42201: Schema format error 864 | 865 | 42202: The version format is incorrect. 866 | 867 | 500: 868 | 869 | 50001 - Storage Service Error 870 | 871 | - Sample request 872 | 873 | 874 | ```shell 875 | curl -X POST -H "Content-Type: application/vnd.openschema.v1+json" \ 876 | --data'{"schema": "{"type": "string"}"}'\ 877 | http://localhost:8081/compatibility/subjects/test-value/versions/latest 878 | ``` 879 | 880 | - Response Example 881 | 882 | 883 | ```json 884 | {"isCompatible": true} 885 | ``` 886 | 887 | 888 | 889 | #### 7.3.2 Obtaining Compatibility Setting 890 | 891 | - URL 892 | 893 | 894 | GET /config/(string: subject) 895 | 896 | - Request parameters 897 | 898 | |Parameter name|Parameter type|Required or not|Parameter description| 899 | | -------- | -------- | -------- | ----------- | 900 | | subject | string | Required | Subject name | 901 | 902 | - Response parameters 903 | 904 | | Parameter Name| Parameter Type| Parameter Description| 905 | | ------------- | -------- | -------- | 906 | | Compatibility | string | Compatibility | 907 | 908 | - Error code. 909 | 910 | 401: 911 | 912 | 40101 - Unauthorized Error 913 | 914 | 404: 915 | 916 | 40401: The subject does not exist. 917 | 918 | 500: 919 | 920 | 50001 - Storage Service Error 921 | 922 | - Sample request 923 | 924 | 925 | ```shell 926 | curl -X GET -H "Content-Type: application/vnd.openschema.v1+json" \ 927 | http://localhost:8081/config/test-value 928 | ``` 929 | 930 | - Response Example 931 | 932 | 933 | ```json 934 | {"compatibility": "FULL"} 935 | ``` 936 | 937 | 938 | 939 | #### 7.3.3 Update Compatibility Setting 940 | 941 | - URL 942 | 943 | 944 | PUT /config/(string: subject) 945 | 946 | - Request parameters 947 | 948 | |Parameter name|Parameter type|Required or not|Parameter description| 949 | | ------------- | -------- | -------- | ----------- | 950 | | subject | string | Required | Subject name | 951 | | compatibility | string | | Compatibility | 952 | 953 | - Response parameters 954 | 955 | | Parameter Name| Parameter Type| Parameter Description| 956 | | ------------- | -------- | -------- | 957 | | compatibility | string | compatibility | 958 | 959 | - Error code. 960 | 961 | 401: 962 | 963 | 40101 - Unauthorized Error 964 | 965 | 404: 966 | 967 | 40401: The subject does not exist. 968 | 969 | 422: 970 | 971 | 42201 - Compatibility format error 972 | 973 | 500: 974 | 975 | 50001 - Storage Service Error 976 | 977 | - Sample request 978 | 979 | 980 | ```shell 981 | curl -X PUT -H "Content-Type: application/vnd.openschema.v1+json" \ 982 | --data '{"compatibility": "NONE"}'\ 983 | http://localhost:8081/config/test-value 984 | ``` 985 | 986 | - Response Example 987 | 988 | 989 | ```json 990 | {"compatibility": "NONE"} 991 | ``` --------------------------------------------------------------------------------