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/docstags 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 userstags 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 messagestags 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: someSignupValueBelow 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'