# Channels

All AsyncAPI specs **MUST** include definitions for the channels (Kafka topics) including:

* Description of the topic
* Servers in which the topic is available
  * This is a reference to one of the server identifiers included in the servers section
* publish/subscribe operations
  * Operation ID
  * Summary or short description for the operation
  * Description for the operation
  * Security schemes
  * Tags
  * External Docs
  * Message details

In addition to those supported fields, it **MAY** be possible to use extension attributes (using the x- prefix) to specify specific configuration parameters and metadata. In so, the recommended attributes to use are:

* x-metadata
  * To include additional configuration specific to your team or project
* x-configurations
  * To include Kafka configuration parameters and producers/consumers

As the parameters can be different per environment, it is very convenient to add an additional level for the environment.

As part of the publish/subscribe operations, the spec **SHOULD** specify the different Kafka clients currently consuming from the different topics for each cluster/environment. For this, the extended attributes x-producers and x-consumers will be used.

```yaml
...
channels:
  namespace.source.event.topic-name:
    description: 'A description of the purpose of the topic and the contained information'
    servers: ['playground-dev', 'playground-sit', 'playground-pro']
    x-metadata:
      myField1: 'myValue1'
      myField2: 'myValue2'
    x-configurations:
      playground.dev:
        kafka:
          partitions: '12'
          replicas: '1'
          topicConfiguration:
            min.insync.replicas: '1'
            retention.ms: '2592000000'
      playground.sit:
        kafka:
          partitions: '12'
          replicas: '2'
          topicConfiguration:
            min.insync.replicas: '1'
            retention.ms: '2592000000'
     publish:
      operationId: 'producer'
      summary: 'Description for the operation'
      description: 'An extensive explanation about the operation'
      security:
        - producerAcl: []
      tags:
        - name: 'tagA'
        - name: 'tagB'
      x-producers:
        playground.dev:
          - 'producer1'
          - 'producer2'
        playground.sit:
          - 'producer1'
          - 'producer2'
        playground.pro:
          - 'producer3'
          - 'producer4'
      externalDocs:
        description: 'documentation'
        url: 'http://confluence.adidas.fdp/catalogue/myTopic'
      ...
    subscribe:
      operationId: 'consumer'
      ...
      x-consumers:
        playground.dev:
          - 'consumer1'
          - 'consumer2'
        playground.sit:
          - 'consumer1'
          - 'consumer2'
        playground.pro:
          - 'consumer3'
...
```