Payload schema

The payload schema sets the format, data types, and properties of a message. Such an approach ensures the message's payload follows a specific structure and data format.

It's recommended to use AsyncAPI Schema (a superset of JSON Schema) for handling complex messages and structured data. AsyncAPI Schema helps consumers understand the payload's structure and data types. However, AsyncAPI allows any schema format. For example, when using the Avro schema format, define your message payload in Avro directly instead of trying to represent it in JSON Schema format.

Define schema

Define the schema for the message payload with one of the following methods:

• Inline: Define the JSON schema within the message payload property.
• Components reference: Specify the schema using a reference to the components.schemas section, such as $ref: '#/components/schemas/user.
• Remote reference: Specify the schema using an absolute remote endpoint, such as $ref: 'https://schemas.example.com/user'.
• Local file reference: Specify the schema using a relative reference, such as $ref: './user-signedup.json'.

The diagram below describes how payload referencing works within the component reference:

Here is an example of an AsyncAPI document where the payload's schema is defined directly within it:

1channels:
2  exampleChannel:
3    address: exampleChannel
4    messages:
5      SimpleSignup:
6        payload:
7          type: object
8          properties:
9            name:
10              type: string
11            email:
12              type: string

Attach examples

Although optional, attaching examples to the AsyncAPI document is highly recommended. You can use JSON or YAML format for binary encodings. Attach the examples to the examples property within the message payload definition. For example:

1examples:
2  - name: SimpleSignup
3    summary: A simple UserSignup example message
4    payload:
5      user:
6        name: Demo
7        email: demo@demo.io

Reuse schemas between messages

To reuse a schema in your AsyncAPI document, define it in the components/schemas section and reference it using the $ref keyword. Using $ref avoids duplication and ensures consistency. Here's an example of reusing a schema from components in AsyncAPI:

1components:
2  messages:
3    SimpleSignup:
4      name: SimpleSignup
5      contentType: application/json
6      payload:
7        $ref: '#/components/schemas/SimpleSignup'
8    examples:
9    - name: SimpleSignup
10      payload: 
11        user:
12          name: Demo
13          email: demo@demo.io
14  schemas:
15    SimpleSignup:
16      type: object
17      properties:
18        name:
19          type: string
20        email:
21          type: string

Schema formats

The default schema in an AsyncAPI document is the AsyncAPI schema itself. However, you can choose from other formats like JSON Schema, Avro, OpenAPI Schema, Protobuf, and more. Remember to indicate in your AsyncAPI document which schema format you're using.

You specify the format of the schema inside the payload field. The type of information you can put in payload can be described as a tuple. (A tuple is an ordered sequence of elements that can't be changed during a program's execution.)

When using AsyncAPI Schema, the payload must represent a reference or the payload schema definition as described in previous sections.

If you're using various formats, the payload field should include both payload.schemaFormat and payload.schema. For example:

1  payload:
2    schemaFormat: application/vnd.apache.avro;version=1.9.0
3    schema:
4      $ref: "https://www.asyncapi.com/resources/casestudies/adeo/CostingRequestPayload.avsc"

The above example specifies that the provided schema of the message payload is in Avro, version 1.9.0. It also specifies where the Avro schema file is located.

Schema formats and limitations related to their structures

Some schema formats are too challenging to manage in JSON/YAML. Complex schema formats — Avro, AsyncAPI schemas, and other JSON-based schemas — can be directly included in the AsyncAPI document or referenced using $ref for specific sections.

1    payload:
2        schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
3        schema: # The following is an Avro schema in YAML format (JSON format is also supported)
4          type: record
5          name: User
6          namespace: com.company
7          doc: User information
8          fields:
9            - name: displayName
10              type: string
11            - name: email
12              type: string
13            - name: age
14              type: int

The process is more complex for Protobuf schemas, as their Protocol Buffers are not JSON-based. You cannot use $ref to reference parts of the schema. Instead, you must include the entire Protobuf schema definition as a string:

1      payload:
2        schemaFormat: application/vnd.google.protobuf;version=3
3        schema: |
4            message Point {
5                required int32 x = 1;
6                required int32 y = 2;
7                optional string label = 3;
8            }
9
10            message Line {
11                required Point start = 1;
12                required Point end = 2;
13                optional string label = 3;
14            }