AsyncAPI Contracts - Overview

Introduction

AsyncAPI definitions describe event-driven APIs. Swagger Contract Testing compares consumer message contracts against AsyncAPI provider contracts using the same bi-directional model used for OpenAPI definitions. This allows you to verify that your event-driven API meets the expectations defined by consuming services.

Notice ON-PREMISES SUPPORT
AsyncAPI provider contracts from release 2.6.0

Supported Versions

Format	Support
AsyncAPI 2.x	Not supported
AsyncAPI 3.0	Supported (any patch version)
AsyncAPI 3.1	Supported (any patch version)

Your AsyncAPI definition must declare its version at the root of the definition using the asyncapi key, as a full major.minor.patch version string — for example:

asyncapi: "3.0.0"

In line with the AsyncAPI specification, patch versions are not distinguished — for example, 3.0.0 and 3.0.1 definitions are treated identically.

Validation on Upload

Contract Testing validates your AsyncAPI definition when you upload it:

Version check — the version is read from the top-level asyncapi key. The upload is rejected, with a message explaining why, if the version is missing, is not a full major.minor.patch string (for example, a bare 3.0), or is an unsupported version (for example, a 2.x definition).
Structure check — the structure of your definition is validated against the official AsyncAPI 3.0 or 3.1 schema, matching its declared version.
Payload format notices — if your definition declares message payload content types that Contract Testing does not compare in this release (for example, application/avro or Protobuf content types), the definition still uploads successfully, but a notice is included so that you know those messages are not covered by cross-contract verification.

Supported Messaging Patterns

Contract Testing supports two messaging patterns in AsyncAPI definitions:

Pattern	AsyncAPI Operation	Pact V4 Interaction Type	Description
Fire-and-forget	`receive` (from provider perspective)	`Asynchronous/Messages`	The provider receives a message and processes it without sending a response.
Request/reply	`send` + `reply`	`Synchronous/Messages`	The provider receives a message and sends a response back to the consumer.

Payload Formats

Contract Testing validates message payloads against JSON schemas defined in your AsyncAPI definition. JSON payloads only are supported in this release. Avro and Protobuf serialization formats are not currently supported.

Note: Avro and Protobuf support is planned for a future release. For now, use JSON payloads.

Limitations and Considerations

AsyncAPI version: Only AsyncAPI 3.0 and 3.1 definitions are supported. AsyncAPI 2.x definitions are not supported.
Validation on upload: AsyncAPI definitions must be well-formed YAML or JSON and are validated on upload — see Validation on Upload.
Binding-specific validation: Contract Testing checks channel or topic names (for example, Kafka topic names or SQS queue names) but does not validate binding-specific behaviour such as partitions, security policies, or schema registry integration.
Pact matching rules: Pact matching rules defined in your consumer test are ignored during verification. Contract Testing validates only the payload and metadata values you provide.
External references: Each AsyncAPI definition must be self-contained. References using $ref must resolve within the same definition.

Consumer Contracts with Mixed Interaction Types

A provider publishes either an OpenAPI definition (for HTTP APIs) or an AsyncAPI definition (for event-driven APIs) as its provider contract — a single provider cannot hold both at the same time.

A consumer contract, however, can contain both HTTP interactions and message interactions. During verification, only the interactions that match your provider contract type are compared against it:

With an AsyncAPI provider contract, message interactions are compared against the AsyncAPI definition.
With an OpenAPI definition, HTTP interactions are compared against the OpenAPI definition.

Any remaining interactions of the other type must be validated using Pact provider verification so that every interaction in the consumer contract has a verification result.

Note: If a consumer contract includes an interaction type that your provider contract does not cover, the comparison reports that the corresponding definition is missing for those interactions rather than silently skipping them. Ensure those interactions are covered by Pact provider verification before deploying.

In this section: