Tags

tags in AsyncAPI document

A tag is a label or category that groups related entities in an event-driven system.

In the AsyncAPI document, tags are defined as a list of tag objects within the tags object at the info level.

The individual tags field contains the following properties:

• name: The name of the tag.
• description: A short description explaining the tag's purpose or usage.
• externalDocs: Additional external documentation for the tag.

Tags have different purposes depending on the context. They can either be used for consistent tag usage across the AsyncAPI document and logical component grouping or be applied to individual components like servers, channels, or operations for more specific purposes.

To reuse tags, you must define them in the components object of an AsyncAPI document and then use reference objects to include them.

tags in info object

Tags specified in the tags property of the info object categorize the entire AsyncAPI document. These globally defined tags provide an overarching context, representing key themes or functional areas within the event-driven system. They group elements like channels or servers by relevance, offering a holistic understanding of the application's structure.

Below is a visual representation of the tags object inside the info object in an AsyncAPI document:

Below is an example of the tags object inside the info object in an AsyncAPI document:

1asyncapi: 3.0.0
2info:
3  title: AsyncAPI Documentation
4  version: 1.0.0
5  description: |
6    This AsyncAPI document provides an overview
7    of the event-driven system
8  tags:
9    - name: Applications
10      description: All applications related topics
11      externalDocs:
12        description: More info about applications
13        url: https://applications.example.com/docs
14    - name: Time
15      description: All time related topics
16      externalDocs:
17        description: More info about time
18        url: https://time.example.com/docs

tags in servers object

Tags specified in the tags property of the servers object categorize server configurations and characteristics. They allow for server categorization based on:

• criteria like location, environment type (like production or development), and unique server features.
• specific tags or labels.

Using the tags object under servers is optional.

Below is a visual representation of the tags object inside the servers object in an AsyncAPI document:

Below is an example of the tags object inside the servers object in an AsyncAPI document:

1asyncapi: 3.0.0
2
3info:
4  title: AsyncAPI Documentation
5  version: 1.0.0
6
7servers:
8  development:
9    host: localhost:5672
10    description: Development AMQP broker
11    protocol: amqp
12    protocolVersion: 0-9-1
13    tags:
14      - name: env:development
15        description: This environment is meant for developers to run their tests
16  production:
17    host: rabbitmq.in.mycompany.com:5672
18    description: RabbitMQ broker for the production environment
19    protocol: amqp
20    protocolVersion: 0-9-1
21    tags:
22      - name: env:production
23        description: This environment is the live environment available for final users

tags in channels object

Tags specified in the tags property of the channels object enable logical grouping and categorization based on specific functionalities or business domains.

Using the tags object under the channels object is optional.

Below is a visual representation of the tags object inside the channels object in an AsyncAPI document:

Below is an example of the tags object inside the channels object in an AsyncAPI document:

1asyncapi: 3.0.0
2
3info:
4  title: AsyncAPI Documentation
5  version: 1.0.0
6
7channels:
8  SignedUp:
9    address: 'user.signedup'
10    messages:
11      userSignedUp:
12        payload:
13          type: object
14    tags:
15      - name: user
16        description: User-related messages

tags in operations object

Tags specified in the tags property of the operations object facilitate logical grouping and categorization of operation objects by type, functionality, and more.

Using the tags object under the operations object is optional.

Below is a visual representation of the tags object inside the operations object in an AsyncAPI document:

Below is an example of the tags object inside the operations object in an AsyncAPI document:

1operations:
2  onUserSignUp:
3    title: User sign up
4    summary: Action to sign a user up
5    description: A longer description
6    channel:
7      $ref: '#/channels/userSignup'
8    action: send
9    tags:
10      - name: user
11        description: operation related to user
12      - name: signup
13        description: operation related to a user's signUp
14      - name: register
15        description: operation related to a new registration
16    bindings:
17      amqp:
18        ack: false
19    traits:
20      - $ref: '#/components/operationTraits/kafka'

tags in message object

Tags specified in the tags property of the message object group and categorize messages based on criteria, requirements, channels, and operations.

Using the tags object under the message object is optional.

Below is a visual representation of the tags object inside the message object in an AsyncAPI document:

Below is an example of the tags object inside the message object in an AsyncAPI document:

1 name: SimpleSignup
2summary: A simple UserSignup example message
3tags: 
4    - name: userSignUp
5      description: some message related to user signup
6headers:
7  correlationId: my-correlation-id
8  applicationInstanceId: myInstanceId
9payload:
10  user:
11    someUserKey: someUserValue
12  signup:
13    someSignupKey: someSignupValue

Below is an example of all the tags defined in the components object and referenced in other components like servers and channels:

1asyncapi: 3.0.0
2
3components:
4  tags:
5    speech:
6      name: Speech
7      description: All speech related topics
8    video:
9      name: Video
10      description: All video related topics
11      
12info:
13  title: AsyncAPI Documentation
14  version: 1.0.0
15  description: |
16    This AsyncAPI document provides an overview
17    of the event-driven system
18  tags:
19    - $ref: '#/components/tags/speech'
20    - $ref: '#/components/tags/video'
21
22servers:
23  speech:
24    host: localhost:5672
25    description: RabbitMQ broker for sending speech data
26    protocol: amqp
27    tags:
28      - $ref: '#/components/tags/speech'
29  video:
30    host: localhost:5673
31    description: RabbitMQ broker for video information
32    protocol: amqp
33    tags:
34       - $ref: '#/components/tags/video'
35
36channels:
37  getSpeech:
38      address: 'application/speech/get'
39      servers: 
40        - $ref: '#/servers/speech'
41      messages:
42        voice:
43          name: Voice
44          summary: Add info about the voice stream data
45          tags:
46            - $ref: '#/components/tags/speech'
47  getVideo:
48      address: 'application/video/get'
49      servers: 
50        - $ref: '#/servers/video'
51      messages:
52        voice:
53          name: Video
54          summary: Add info about the video data live bitrate and others
55          tags: 
56            - $ref: '#/components/tags/video'
57
58operations:
59  onVoiceStreamed:
60    title: Get speech data
61    channel:
62      $ref: '#/channels/getSpeech'
63    action: receive
64    tags:
65      - $ref: '#/components/tags/speech'
66
67  onVideoStreamed:
68    title: Get video data
69    channel:
70      $ref: '#/channels/getVideo'
71    action: receive
72    tags:
73      - $ref: '#/components/tags/video'