Using Avro Schemas with APIkit for AsyncAPI

APIkit for AsyncAPI accepts Avro in AsyncAPI message definitions so you serialize payloads and validate them in Mule. Declare schemas inline in the spec or reference external Avro documents; Studio can expose message shape during design, and DataSense assists with Avro-backed message metadata.

Schema Definitions

The Avro spec defines its format by giving the value of schemaFormat as application/vnd.apache.avro.

The Avro spec supports describing the schema inline or referencing an external document that describes the schema in the Avro format:

Inline definition

publish:
  summary: inform details about person
  operationId: lightMeasured
  message:
    schemaFormat: 'application/vnd.apache.avro;version=1.9.0'
    payload:
      name: lightMeasured
      type: record
      fields:
        - name: lumens
          type: int
          example: 134
        - name: sentAt
          type: string
          logicalType: timestamp-millis
          10
          example: 1985-04-12T23:20:50.52Z

Reference to an Avro fragment

channels:
 smartylighting.streetlights.1.0.event.{streetlightId}.monitor:
   publish:
     message:
       schemaFormat: application/vnd.apache.avro;version=1.9.0
       payload:
         $ref: /exchange_modules/83589b9b-6630-4c28-985d-174ee9172661/lumenschema/1.0.0/lumens.json'

The lumens.json file provides the specification in the Avro schema.

{
  "type": "record",
  "name": "lightMeasured",
  "fields": [
    {"name": "lumens", "type": "int"},
    {"name": "sentAt", "type": {"type": "string", "logicalType": "timestamp-millis"}}
  ]
}

APIkit for AsyncAPI supports async APIs that have Avro messages defined inline. APIkit for AsyncAPI doesn’t support API specs that refer to Avro fragments.

Avro Message Encoding and Validation

Avro messages are encoded in either binary or text (JSON) format. The specification provides the value of contentType OR defaultContentType.

APIkit for AsyncAPI validates messages encoded in text (JSON) but doesn’t validate binary-encoded messages.