Avro Plugin

The Avro plugin lets Drift encode and validate Apache Avro message payloads. Use it with the AsyncAPI plugin to verify message-based APIs whose messages use an Avro binary payload.

The plugin reads the Avro schema embedded in your AsyncAPI document. You do not need a schema registry or any generated code.

Property	Value
Plugin name	`avro`
Purpose	vro payload encoding and validation for AsyncAPI messages
Content types	`application/vnd.apache.avro`, `application/avro`, `avro/binary`
Schema format	`application/vnd.apache.avro+json;version=1.9.0`
Used with	`asyncapi`, a transport plugin (`kafka` or `aws-messaging`), and `json`
Tier	Optional

Enabling the Plugin

The Avro plugin is an optional component. Install it before you use it:

   drift component install avro

Then add it to the plugins section of your test case file, together with the AsyncAPI plugin, a transport plugin, and the JSON plugin:

  plugins:
      - name: asyncapi
      - name: kafka
      - name: avro
      - name: json

The JSON plugin is required because Drift always validates message headers as JSON.

The Avro plugin activates for any message whose `contentType` is one of the supported Avro content types.

Describing the Payload in Your AsyncAPI Document

Declare the payload with an AsyncAPI multi-format schema. Set schemaFormat to the Avro schema format, and embed the Avro schema as a JSON string in schema or provide a JSON schema as an object:

 components:
      messages:
        orderCreated:
          contentType: application/vnd.apache.avro
          payload:
            schemaFormat: application/vnd.apache.avro+json;version=1.9.0
            schema: |
              {
                "type": "record",
                "name": "OrderCreated",
                "namespace": "orders",
                "fields": [
                  {"name": "order_id",    "type": "string"},
                  {"name": "customer_id", "type": "string"},
                  {"name": "status",      "type": "string"},
                  {"name": "shipping_address", "type": {
                    "type": "record",
                    "name": "Address",
                    "fields": [
                      {"name": "street", "type": "string"},
                      {"name": "city",   "type": "string"}
                    ]
                  }}
                ]
              }

Both contentType and schemaFormat with schema are required. contentType selects the Avro plugin, and schema gives Drift the record definition.

Writing Expected Payloads

Use the field names exactly as they appear in the Avro schema:

operations:
      SendOrderCreated_Observe:
        target: orders-api:sendOrderCreated:orderCreated
        parameters:
          correlation-id: order-created-001
        trigger:
          # ...
        expected:
          headers:
            correlation-id: ${parameters.correlation-id}
          payload:
            order_id: ORD-100
            customer_id: CUST-9
            status: created
            shipping_address:
              street: "123 Main St"
              city: "Anytown"

When Drift sends a message to your service (action: receive), provide the values in parameters.payload in the same way. Drift encodes them using the schema.

Validation Behavior

How Drift uses the plugin depends on the operation's action:

Action	What Drift does
`send`	Captures the message your service publishes, decodes it with the schema, checks that every record field is present, and compares the result with `expected.payload`.
`receive`	Encodes `parameters.payload` as Avro binary using the schema, and publishes it for your service to consume.

When Drift compares payloads:

Drift checks only the fields in expected.payload. Extra fields in the actual message are allowed.
Lists must have the same number of items.
Values must match exactly. Drift does not support matching rules, such as type or regex matching, for Avro payloads.

When Drift encodes a payload:

If you leave out a field, Drift sends null. This works only when the field type allows null, for example [null, string].
For a union type, Drift uses the first type in the union that matches the value.
Enum values are written as strings. Logical types, such as date, timestamp-millis, and uuid, use their underlying Avro type.

Configuration

To make the plugin handle additional content types, add them in drift.config.toml:

  [plugin_config.avro]
    content_types = ["application/octet-stream"]

Use this setting with care. A broad content type, such as application/octet-stream, can cause the Avro plugin to handle payloads intended for another plugin.

Limitations

The schema must be embedded inline in the AsyncAPI document as a JSON string, or as schemas written as YAML or JSON objects. Drift does not load .avsc files by path.
Drift reads and writes plain Avro binary for a single record. Messages that use a schema registry wire format, such as the Confluent format with a schema ID prefix, are not supported.
Avro object container files are not supported.
Drift does not check schema compatibility or schema evolution between versions.
Drift does not support matching rules for Avro payloads.

Troubleshooting

Symptom	Likely cause
Don't know how to resolve plugin `avro`	The plugin is not installed. Run `drift component install avro`.
Failed to parse Avro schema	The embedded schema is not valid Avro JSON. Check it with your Avro tooling.
Failed to decode Avro bytes	The message does not match the schema, or includes a schema registry prefix.
Avro construct requires a schema	The message payload has no `schemaFormat` and `schema`
Payload handled as JSON instead of Avro	The message `contentType` is missing or is not a supported Avro content type.

In this section: