Implementing and Validating Avro Schemas in APIkit for AsyncAPI Module

APIkit for AsyncAPI supports Avro, a data serialization system that helps you define the format for specifying the structure and encoding of messages. This module shows you the structure of messages in the design phase. APIkit for AsyncAPI also supports DataSense of messages with Avro schema.

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.