From aa8cafde907ea55a9e8b647b5ed2acdf138be2cc Mon Sep 17 00:00:00 2001 From: Goker Akce Date: Mon, 12 Feb 2024 11:29:48 +0000 Subject: [PATCH] feat: updated kafka topic configuration object (#238) Co-authored-by: Goker Akce --- kafka/README.md | 30 +++++++++++++++++++----------- 1 file changed, 19 insertions(+), 11 deletions(-) diff --git a/kafka/README.md b/kafka/README.md index 17fcb92e..79c22579 100644 --- a/kafka/README.md +++ b/kafka/README.md @@ -6,7 +6,7 @@ This document defines how to describe Kafka-specific information on AsyncAPI. ## Version -Current version is `0.4.0`. +Current version is `0.5.0`. @@ -32,7 +32,7 @@ servers: kafka: schemaRegistryUrl: 'https://my-schema-registry.com' schemaRegistryVendor: 'confluent' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` @@ -71,7 +71,7 @@ channels: retention.bytes: 1000000000 delete.retention.ms: 86400000 max.message.bytes: 1048588 - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` ## TopicConfiguration Object @@ -85,8 +85,12 @@ Field Name | Type | `retention.bytes` | integer | The [`retention.bytes`](https://kafka.apache.org/documentation/#topicconfigs_retention.bytes) configuration option. | OPTIONAL | see kafka documentation `delete.retention.ms` | integer | The [`delete.retention.ms`](https://kafka.apache.org/documentation/#topicconfigs_delete.retention.ms) configuration option. | OPTIONAL | see kafka documentation `max.message.bytes` | integer | The [`max.message.bytes`](https://kafka.apache.org/documentation/#topicconfigs_max.message.bytes) configuration option. | OPTIONAL | see kafka documentation +`confluent.key.schema.validation` | boolean | It shows whether the schema validation for the message key is enabled. Vendor specific config. | OPTIONAL | - +`confluent.key.subject.name.strategy` | string | The name of the schema lookup strategy for the message key. Vendor specific config. | OPTIONAL | Clients should default to the vendor default if not supplied. +`confluent.value.schema.validation` | boolean | It shows whether the schema validation for the message value is enabled. Vendor specific config. | OPTIONAL | - +`confluent.value.subject.name.strategy` | string | The name of the schema lookup strategy for the message value. Vendor specific config. | OPTIONAL | Clients should default to the vendor default if not supplied. -This object MUST contain only the properties defined above. +This object MAY contain the properties defined above including optional additional properties. ##### Example @@ -97,6 +101,10 @@ topicConfiguration: retention.bytes: 1000000000 delete.retention.ms: 86400000 max.message.bytes: 1048588 + confluent.key.schema.validation: true + confluent.key.subject.name.strategy: "TopicNameStrategy" + confluent.value.schema.validation: true + confluent.value.subject.name.strategy: "TopicNameStrategy" ``` @@ -131,7 +139,7 @@ operations: clientId: type: string enum: ['myClientId'] - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` @@ -143,13 +151,13 @@ This object contains information about the message representation in Kafka. ##### Fixed Fields -Field Name | Type | Description ----|:---:|--- -`key` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) \| [AVRO Schema Object](https://avro.apache.org/docs/current/spec.html) | The message key. **NOTE**: You can also use the [reference object](referenceObject) way. +Field Name | Type | Description | Applicability [default] | Constraints +---|:-------:|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------:|:-----------------------:|--- +`key` | [Schema Object][schemaObject] \| [Reference Object](referenceObject) \| [AVRO Schema Object](https://avro.apache.org/docs/current/spec.html) | The message key. **NOTE**: You can also use the [reference object](referenceObject) way. | 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. +`bindingVersion` | string | The version of this binding. If omitted, "latest" MUST be assumed. | OPTIONAL [`latest`] | - This object MUST contain only the properties defined above. @@ -168,7 +176,7 @@ channels: enum: ['myKey'] schemaIdLocation: 'payload' schemaIdPayloadEncoding: '4' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` This is another example that describes the use if Apicurio schema registry. We describe the `apicurio-new` way of serializing without details on how it's implemented. We reference a [specific lookup strategy](https://www.apicur.io/registry/docs/apicurio-registry/2.2.x/getting-started/assembly-using-kafka-client-serdes.html#registry-serdes-concepts-strategy_registry) that may be used to retrieve schema Id from registry during serialization. @@ -187,7 +195,7 @@ channels: schemaIdLocation: 'payload' schemaIdPayloadEncoding: 'apicurio-new' schemaLookupStrategy: 'TopicIdStrategy' - bindingVersion: '0.4.0' + bindingVersion: '0.5.0' ``` [schemaObject]: https://www.asyncapi.com/docs/reference/specification/v3.0.0-next-major-spec.15#schemaObject