Solace Bindings

This document defines how to describe Solace-specific information with AsyncAPI.

Version

Current version is 0.4.0.

Server Binding Object

Field Name	Type	Description
`bindingVersion`	String	The current version is 0.4.0
`msgVpn`	String	The Virtual Private Network name on the Solace broker.
`clientName`	String	A unique client name to use to register to the appliance. If specified, it must be a valid Topic name, and a maximum of 160 bytes in length when encoded as UTF-8.

Channel Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Operation Binding Object

We need the ability to support several bindings for each operation, see the Example section below for details.

Field Name	Type	Description
`bindingVersion`	String	The current version is 0.4.0
`destinations`	List of Destination Objects	Destination Objects are described next.
`timeToLive`	Integer \| Schema Object \| Reference Object	Interval in milliseconds or a Schema Object containing the definition of the lifetime of the message.
`priority`	Integer \| Schema Object \| Reference Object	The valid priority value range is 0-255 with 0 as the lowest priority and 255 as the highest or a Schema Object containing the definition of the priority.
`dmqEligible`	Boolean	Set the message to be eligible to be moved to a Dead Message Queue. The default value is false.

Destination Object

Each destination has the following structure:

Field Name	Type	Description
`bindingVersion`	String	The current version is 0.4.0
`destinationType`	Enum	'queue' or 'topic'. If the type is queue, then the subscriber can bind to the queue, which in turn will subscribe to the topic as represented by the channel name or to the provided topicSubscriptions.
`deliveryMode`	Enum	'direct' or 'persistent'. This determines the quality of service for publishing messages as documented here. Default is 'persistent'.
`queue.name`	String	The name of the queue, only applicable when destinationType is 'queue'.
`queue.topicSubscriptions`	List of String	A list of topics that the queue subscribes to, only applicable when destinationType is 'queue'. If none is given, the queue subscribes to the topic as represented by the channel name.
`queue.accessType`	Enum	'exclusive' or 'nonexclusive'. This is documented here. Only applicable when destinationType is 'queue'.
`queue.maxMsgSpoolSize`	String	The maximum amount of message spool that the given queue may use. This is documented here. Only applicable when destinationType is 'queue'.
`queue.maxTtl`	String	The maximum TTL to apply to messages to be spooled. This is documented here. Only applicable when destinationType is 'queue'.
`topic.topicSubscriptions`	List of String	A list of topics that the client subscribes to, only applicable when destinationType is 'topic'. If none is given, the client subscribes to the topic as represented by the channel name.

Message Binding Object

This object MUST NOT contain any properties. Its name is reserved for future use.

Example with two destinations

Here is an example of when we could need two Solace destinations.

Imagine a system where there is a schema called Person, and there are topics:

person/{personId}/created

and

person/{personId}/updated

and you have one application that receives both events. We also want each to be on its own queue. The AsyncAPI file could look like this:

1components:
2  schemas:
3    Person:
4      type: string        
5  messages:
6    PersonEvent:
7      payload:
8        $ref: '#/components/schemas/Person'
9      schemaFormat: application/vnd.aai.asyncapi+json;version=2.0.0
10      contentType: application/json
11operations:
12  addPerson:
13    action: send
14    channel:
15      $ref: '#/channels/address'
16    messages:
17      - $ref: '#/channels/address/messages/personEvent'
18    bindings:
19      solace:
20        bindingVersion: 0.4.0
21        destinations:
22          - destinationType: queue
23            queue:
24              name: CreatedHREvents
25              topicSubscriptions:
26                - person/*/created
27          - destinationType: queue
28            queue:
29              name: UpdatedHREvents
30              topicSubscriptions:
31                - person/*/updated
32        timeToLive: 5000
33        priority: 120
34        dmqEligible: true
35
36channels:
37  person:
38    address: person/{personId}/{eventType}
39    parameters:
40      personId:
41        schema:
42          type: string
43      eventType:
44        schema:
45          type: string
46    messages:
47      personEvent:
48        $ref: '#/components/messages/PersonEvent'
49asyncapi: 3.0.0
50info:
51  title: HRApp
52  version: 0.0.1

The expected behavior would be that the application binds to both queues, and each queue has its own topic subscription, one to create and one to updated events.

Example with a wildcard subscription

This example shows how a client could receive all the topics under person/ using a wildcard subscription:

1components:
2  schemas:
3    Person:
4      type: string
5  messages:
6    PersonEvent:
7      payload:
8        schemaFormat: application/vnd.aai.asyncapi+json;version=3.0.0
9        schema:
10          $ref: '#/components/schemas/Person'
11      contentType: application/json
12operations:
13  addPerson:
14    action: send
15    channel:
16      $ref: '#/channels/person'
17    messages:
18      - $ref: '#/channels/person/messages/personEvent'
19    bindings:
20      solace:
21        bindingVersion: 0.4.0
22        destinations:
23          - destinationType: queue
24            queue:
25              name: CreatedHREvents
26              topicSubscriptions:
27                - person/*/created
28          - destinationType: queue
29            queue:
30              name: UpdatedHREvents
31              topicSubscriptions:
32                - person/*/updated
33        timeToLive: 5000
34        priority: 120
35        dmqEligible: true
36
37channels:
38  person:
39    address: person/{personId}/{eventType}
40    parameters:
41      personId:
42        description: The machine readable id of the person
43      eventType:
44        enum:
45          - create
46          - delete
47    messages:
48      personEvent:
49        $ref: '#/components/messages/PersonEvent'
50asyncapi: 3.0.0
51info:
52  title: HRApp
53  version: 0.0.1

On this page

solace