diff --git a/kafka/README.md b/kafka/README.md index adc5606e..d93b6d84 100644 --- a/kafka/README.md +++ b/kafka/README.md @@ -6,16 +6,34 @@ This document defines how to describe Kafka-specific information on AsyncAPI. ## Version -Current version is `0.2.0`. +Current version is `0.3.0`. ## Server Binding Object -This object MUST NOT contain any properties. Its name is reserved for future use. +This object contains information about the server representation in Kafka. +##### Fixed Fields +Field Name | Type | Description | Applicability [default] | Constraints +---|:---:|:---:|:---:|--- +`schemaRegistryUrl` | string (url) | API URL for the Schema Registry used when producing Kafka messages (if a Schema Registry was used) | OPTIONAL | - +`schemaRegistryVendor` | string | The vendor of Schema Registry and Kafka serdes library that should be used (e.g. `apicurio`, `confluent`, `ibm`, or `karapace`) | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified +`bindingVersion` | string | The version of this binding. | OPTIONAL [`latest`] + +##### Example + +```yaml +servers: + production: + bindings: + kafka: + schemaRegistryUrl: 'https://my-schema-registry.com' + schemaRegistryVendor: 'confluent' + bindingVersion: '0.3.0' +``` @@ -33,11 +51,14 @@ This object contains information about the operation representation in Kafka. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -`groupId` | [Schema Object][schemaObject] | Id of the consumer group. -`clientId` | [Schema Object][schemaObject] | Id of the consumer inside a consumer group. -`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. +Field Name | Type | Description | Applicability [default] | Constraints +---|:---:|:---:|:---:|--- +`groupId` | [Schema Object][schemaObject] | Id of the consumer group. | OPTIONAL | - +`clientId` | [Schema Object][schemaObject] | Id of the consumer inside a consumer group. | OPTIONAL | - +`schemaIdLocation` | string | If a Schema Registry is used when performing this operation, tells where the id of schema is stored (e.g. `header` or `payload`). | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified at the Server level +`schemaIdPayloadEncoding` | string | Number of bytes or vendor specific values when schema id is encoded in payload (e.g `confluent`/ `apicurio-legacy` / `apicurio-new`). | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified at the Server level +`schemaLookupStrategy` | string | Freeform string for any naming strategy class to use. Clients should default to the vendor default if not supplied. | OPTIONAL | MUST NOT be specified if `schemaRegistryUrl` is not specified at the Server level +`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. | OPTIONAL [`latest`] | - This object MUST contain only the properties defined above. @@ -55,7 +76,10 @@ channels: clientId: type: string enum: ['myClientId'] - bindingVersion: '0.1.0' + schemaIdLocation: 'payload' + schemaIdPayloadEncoding: 'apicurio-new' + schemaLookupStrategy: 'TopicIdStrategy' + bindingVersion: '0.3.0' ``` @@ -69,7 +93,7 @@ This object contains information about the message representation in Kafka. Field Name | Type | Description ---|:---:|--- -`key` | [Schema Object][schemaObject] \| [AVRO Schema Object](https://avro.apache.org/docs/current/spec.html) | The message key. **NOTE**: You can also use the [reference object](https://asyncapi.io/docs/specifications/v2.1.0#referenceObject) way. +`key` | [Schema Object][schemaObject] \| [AVRO Schema Object](https://avro.apache.org/docs/current/spec.html) | The message key. **NOTE**: You can also use the [reference object](https://asyncapi.io/docs/specifications/v2.1.0#referenceObject) way. `bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. This object MUST contain only the properties defined above. @@ -85,7 +109,7 @@ channels: key: type: string enum: ['myKey'] - bindingVersion: '0.1.0' + bindingVersion: '0.3.0' ``` -[schemaObject]: https://www.asyncapi.com/docs/specifications/2.0.0/#schemaObject +[schemaObject]: https://www.asyncapi.com/docs/specifications/2.1.0/#schemaObject diff --git a/kafka/json_schemas/operation.json b/kafka/json_schemas/operation.json index 500744ca..0a6cc4fb 100644 --- a/kafka/json_schemas/operation.json +++ b/kafka/json_schemas/operation.json @@ -7,18 +7,31 @@ "additionalProperties": false, "patternProperties": { "^x-[\\w\\d\\.\\-\\_]+$": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/specificationExtension" + "$ref": "https://raw.githubusercontent.com/asyncapi/spec-json-schemas/v2.9.0/schemas/2.1.0.json#/definitions/specificationExtension" } }, "properties": { "groupId": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "$ref": "https://raw.githubusercontent.com/asyncapi/spec-json-schemas/v2.9.0/schemas/2.1.0.json#/definitions/schema", "description": "Id of the consumer group." }, "clientId": { - "$ref": "https://raw.githubusercontent.com/asyncapi/asyncapi-node/v2.7.7/schemas/2.0.0.json#/definitions/schema", + "$ref": "https://raw.githubusercontent.com/asyncapi/spec-json-schemas/v2.9.0/schemas/2.1.0.json#/definitions/schema", "description": "Id of the consumer inside a consumer group." }, + "schemaIdLocation": { + "type": "string", + "description": "If a Schema Registry is used when performing this operation, tells where the id of schema is stored." + "enum": ["header", "payload"] + }, + "schemaIdPayloadEncoding": { + "type": "string", + "description": "Number of bytes or vendor specific values when schema id is encoded in payload." + }, + "schemaLookupStrategy": { + "type": "string", + "description": "Freeform string for any naming strategy class to use. Clients should default to the vendor default if not supplied." + }, "bindingVersion": { "type": "string", "enum": [ diff --git a/kafka/json_schemas/server.json b/kafka/json_schemas/server.json new file mode 100644 index 00000000..568fd377 --- /dev/null +++ b/kafka/json_schemas/server.json @@ -0,0 +1,37 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "http://asyncapi.com/bindings/ibmmq/server.json", + "title": "Server Schema", + "description": "This object contains server connection information to a Kafka broker. This object contains additional information not possible to represent within the core AsyncAPI specification.", + "type": "object", + "additionalProperties": false, + "patternProperties": { + "^x-[\\w\\d\\.\\-\\_]+$": { + "$ref": "https://raw.githubusercontent.com/asyncapi/spec-json-schemas/v2.9.0/schemas/2.1.0.json#/definitions/specificationExtension" + } + }, + "properties": { + "schemaRegistryUrl": { + "type": "string", + "description": "API URL for the Schema Registry used when producing Kafka messages (if a Schema Registry was used)." + }, + "schemaRegistryVendor": { + "type": "string", + "description": "The vendor of the Schema Registry and Kafka serdes library that should be used." + }, + "bindingVersion": { + "type": "string", + "enum": [ + "0.3.0" + ], + "description": "The version of this binding." + } + }, + "examples": [ + { + "schemaRegistryUrl": "https://my-schema-registry.com", + "schemaRegistryVendor": "confluent", + "bindingVersion": "0.3.0" + } + ] +}