A tag functions as a label or category for logically grouping related entities like channels or servers in an event-driven system. The tag object facilitates the organization of channels, operations, or other components, categorizing them based on functionality, purpose, or other relevant criteria.
In AsyncAPI, the tags object is a list of individual tag objects. Each tag within this collection can be defined with a specific name, accompanied by an optional description that offers additional insight into the tag's intended purpose or usage.
You can define tags in the components object of an AsyncAPI document, which enables the reusability of the tags. If you include tags in the components object, they can be re-used by using reference objects.
Additionally, within AsyncAPI, you can create a list of tags in the tags object at the info level, specifying the tags you intend to use throughout the document. These predefined tags can then be applied to individual components like servers or channels, facilitating logical grouping and organization of these components.
tags in AsyncAPI document
The tags object consists of a list of tag objects, which can be referenced using the reference object.
The tags object is a list of tags and individual tag objects, each containing specific fields.
In an AsyncAPI document, the function of tags within the tags object differs depending on context. For example, the tags object can be employed for consistent usage of tags across the document and logical grouping of components. Alternatively, tags can be applied to individual components such as servers or channels, serving more specific purposes within those contexts.
The tags object fields include:
name: The name of the tag.description: A short description for the tag.externalDocs: Additional external documentation for the tag.
tags in info object
When specified in the tags property of the info object, tags offer a comprehensive categorization for the entire AsyncAPI document. These globally defined tags under the info object impart an overarching context, representing key themes or functional areas within the event-driven system. They effectively group elements like channels or servers by their broader relevance, providing a holistic understanding of the application's structure.
Here's a visual representation of the tags object inside an 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
When tags are utilized within the servers object's tags property, they specifically pertain to server configurations and characteristics. These tags enable server categorization by various criteria, including geographical location, environment type (i.e., production or development), or unique server features. Using tags in the servers object allows for the categorization and organization of servers based on specific tags or labels. Using the tags object under the servers object is optional.
Here's a visual representation of the tags object inside a 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 linked with individual channels enable logical grouping and categorization based on specific functionalities or business domains. When the tags object is used within a channels object in an AsyncAPI document, its context is either confined to the channels object, impacting only that section, or it can be employed for consistent tagging across the document for cohesive grouping. Using the tags object under the channels object is optional.
Here's a visual representation of the tags object inside a 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
Within an AsyncAPI document, the tags object in the operations object facilitates logical grouping and categorization of operation objects by operation type, functionality, and more. When used in an operations object, the tags can either serve a specific purpose within that object or be employed for consistent, logical grouping of components across the document. Using the tags object in the operations object is optional.
Here's a visual representation of the tags object inside a 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 linked to individual message objects in an AsyncAPI document enable logical grouping and categorization of messages based on specific criteria, requirements, channels, and operations. When implemented within a message object, the context of the tags object can be confined to that specific message or integrated as the strategy for consistent tagging and logical organization across the entire document.
Here's a visual representation of a tags object inside a 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: someSignupValueHere's an example illustrating all the tags being defined in the components object and then referenced in other components such as servers, channels, and more:
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'