Multi-Format Schema

What is Multi-Format Schema Object in AsyncAPI?

The Multi-Format Schema Object in AsyncAPI represents a schema definition that supports multiple schema formats or languages. Unlike the standard Schema Object which is based solely on JSON Schema, the Multi-Format Schema Object allows you to use various schema formats such as Avro, JSON Schema, AsyncAPI Schema, OpenAPI Schema, RAML, Google Protobuf, and XML.

This flexibility enables you to define your message payloads using the schema format that best suits your needs or integrates with your existing systems.

Avro

Apache Avro is a data serialization system that provides rich data structures, a compact binary data format, and integration with many programming languages. Avro schemas are defined using JSON and support features like complex types, logical types, and schema evolution.

In AsyncAPI, Avro schemas can be used to define message payloads with precise type definitions and efficient serialization.

1.9.0

ApplicationEvent - Defines an event structure with application-specific information (JSON, YAML)
DocumentInfo - Schema for document metadata and information (JSON, YAML)
foo.Bar - Example of a namespaced record type (JSON, YAML)
full_record_v1/v2 - Complete record examples showing schema evolution (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - Demonstrates Avro's logical type for UUIDs (JSON, YAML)
logical_types_with_multiple_fields - Shows how to use multiple logical types in a single record (JSON, YAML)
MyResponse - Simple response record structure (JSON, YAML)
regression_error_field_in_record - Example showing error field handling (JSON, YAML)
schema-location - Demonstrates schema references and locations (JSON, YAML)
schema-location-read/write - Examples of read and write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Shows programmatic schema construction (JSON, YAML)
simple_record - Basic record structure example (JSON, YAML)
TestRecordWithLogicalTypes - Record with various logical types (JSON, YAML)
TestRecordWithMapsAndArrays - Demonstrates complex data structures (JSON, YAML)
TestUnionRecord - Shows union type usage (JSON, YAML)
union_and_fixed_fields - Combines union types with fixed-length fields (JSON, YAML)

1.9.1

ApplicationEvent - Updated event structure for version 1.9.1 (JSON, YAML)
DocumentInfo - Enhanced document metadata schema (JSON, YAML)
foo.Bar - Namespaced record with 1.9.1 features (JSON, YAML)
full_record_v1/v2 - Evolution examples for 1.9.1 (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID handling in 1.9.1 (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types example (JSON, YAML)
MyResponse - Response structure for 1.9.1 (JSON, YAML)
regression_error_field_in_record - Error handling example (JSON, YAML)
schema-location - Schema reference example (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Schema construction example (JSON, YAML)
simple_record - Basic record example (JSON, YAML)
TestRecordWithLogicalTypes - Logical types demonstration (JSON, YAML)
TestRecordWithMapsAndArrays - Complex structures example (JSON, YAML)
TestUnionRecord - Union type usage (JSON, YAML)
union_and_fixed_fields - Union and fixed fields example (JSON, YAML)

1.9.2

ApplicationEvent - Event structure for version 1.9.2 (JSON, YAML)
DocumentInfo - Document metadata schema (JSON, YAML)
foo.Bar - Namespaced record example (JSON, YAML)
full_record_v1/v2 - Schema evolution examples (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID logical type example (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types (JSON, YAML)
MyResponse - Response structure (JSON, YAML)
regression_error_field_in_record - Error field handling (JSON, YAML)
schema-location - Schema reference demonstration (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Programmatic schema building (JSON, YAML)
simple_record - Simple record structure (JSON, YAML)
TestRecordWithLogicalTypes - Record with logical types (JSON, YAML)
TestRecordWithMapsAndArrays - Complex data structures (JSON, YAML)
TestUnionRecord - Union type example (JSON, YAML)
union_and_fixed_fields - Union with fixed fields (JSON, YAML)

1.10.0

ApplicationEvent - Updated event structure for 1.10.0 (JSON, YAML)
DocumentInfo - Enhanced document schema (JSON, YAML)
foo.Bar - Namespaced record example (JSON, YAML)
full_record_v1/v2 - Schema evolution examples (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID handling in 1.10.0 (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types (JSON, YAML)
MyResponse - Response structure (JSON, YAML)
regression_error_field_in_record - Error handling (JSON, YAML)
schema-location - Schema reference example (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Schema construction (JSON, YAML)
simple_record - Basic record example (JSON, YAML)
TestRecordWithLogicalTypes - Logical types demonstration (JSON, YAML)
TestRecordWithMapsAndArrays - Complex structures (JSON, YAML)
TestUnionRecord - Union type usage (JSON, YAML)
union_and_fixed_fields - Union and fixed fields (JSON, YAML)

1.10.1

ApplicationEvent - Event structure for 1.10.1 (JSON, YAML)
DocumentInfo - Document metadata schema (JSON, YAML)
foo.Bar - Namespaced record example (JSON, YAML)
full_record_v1/v2 - Schema evolution examples (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID logical type (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types (JSON, YAML)
MyResponse - Response structure (JSON, YAML)
regression_error_field_in_record - Error field handling (JSON, YAML)
schema-location - Schema reference example (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Schema construction (JSON, YAML)
simple_record - Simple record structure (JSON, YAML)
TestRecordWithLogicalTypes - Record with logical types (JSON, YAML)
TestRecordWithMapsAndArrays - Complex data structures (JSON, YAML)
TestUnionRecord - Union type example (JSON, YAML)
union_and_fixed_fields - Union with fixed fields (JSON, YAML)

1.10.2

ApplicationEvent - Event structure for 1.10.2 (JSON, YAML)
DocumentInfo - Document metadata schema (JSON, YAML)
foo.Bar - Namespaced record example (JSON, YAML)
full_record_v1/v2 - Schema evolution examples (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID logical type (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types (JSON, YAML)
MyResponse - Response structure (JSON, YAML)
regression_error_field_in_record - Error field handling (JSON, YAML)
schema-location - Schema reference example (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Schema construction (JSON, YAML)
simple_record - Simple record structure (JSON, YAML)
TestRecordWithLogicalTypes - Record with logical types (JSON, YAML)
TestRecordWithMapsAndArrays - Complex data structures (JSON, YAML)
TestUnionRecord - Union type example (JSON, YAML)
union_and_fixed_fields - Union with fixed fields (JSON, YAML)

1.11.0

ApplicationEvent - Updated event structure for 1.11.0 (JSON, YAML)
DocumentInfo - Enhanced document schema (JSON, YAML)
foo.Bar - Namespaced record example (JSON, YAML)
full_record_v1/v2 - Schema evolution examples (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID handling in 1.11.0 (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types (JSON, YAML)
MyResponse - Response structure (JSON, YAML)
regression_error_field_in_record - Error handling (JSON, YAML)
schema-location - Schema reference example (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Schema construction (JSON, YAML)
simple_record - Basic record example (JSON, YAML)
TestRecordWithLogicalTypes - Logical types demonstration (JSON, YAML)
TestRecordWithMapsAndArrays - Complex structures (JSON, YAML)
TestUnionRecord - Union type usage (JSON, YAML)
union_and_fixed_fields - Union and fixed fields (JSON, YAML)

1.11.1

ApplicationEvent - Event structure for 1.11.1 (JSON, YAML)
DocumentInfo - Document metadata schema (JSON, YAML)
foo.Bar - Namespaced record example (JSON, YAML)
full_record_v1/v2 - Schema evolution examples (v1 JSON, v1 YAML, v2 JSON, v2 YAML)
logical-uuid - UUID logical type (JSON, YAML)
logical_types_with_multiple_fields - Multiple logical types (JSON, YAML)
MyResponse - Response structure (JSON, YAML)
regression_error_field_in_record - Error field handling (JSON, YAML)
schema-location - Schema reference example (JSON, YAML)
schema-location-read/write - Read/write schema locations (read JSON, read YAML, write JSON, write YAML)
SchemaBuilder - Schema construction (JSON, YAML)
simple_record - Simple record structure (JSON, YAML)
TestRecordWithLogicalTypes - Record with logical types (JSON, YAML)
TestRecordWithMapsAndArrays - Complex data structures (JSON, YAML)
TestUnionRecord - Union type example (JSON, YAML)
union_and_fixed_fields - Union with fixed fields (JSON, YAML)

JSON Schema

JSON Schema is a vocabulary that allows you to annotate and validate JSON documents. It's the foundation for AsyncAPI's Schema Object and provides a way to describe the structure and validation requirements of your JSON data.

In AsyncAPI, JSON Schema (draft-07) can be used to define message payloads with validation rules and documentation.

Draft-07

arrays.schema - Demonstrates array validation with items, minItems, maxItems, and uniqueItems (JSON)
complex-object.schema - Shows nested object structures with properties and required fields (JSON)
conditional-validation-if-else.schema - Examples of conditional validation using if/then/else (JSON)
draft-07-core-schema-meta-schema - The complete JSON Schema draft-07 meta-schema (JSON)
enumerated-values.schema - Demonstrates the enum keyword for restricting values (JSON)
person.schema - Simple person object with basic properties (JSON)
regex-pattern.schema - Shows string validation using regular expression patterns (JSON)

AsyncAPI Schema

AsyncAPI Schema extends JSON Schema with additional keywords specific to AsyncAPI. It allows for more expressive schema definitions tailored for asynchronous APIs.

2.0.0

arrays.schema - Array validation examples for AsyncAPI 2.0.0 (JSON, YAML)
complex-object.schema - Nested object structures with AsyncAPI extensions (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation examples (JSON, YAML)
draft-07-core-schema-meta-schema - The JSON Schema meta-schema with AsyncAPI extensions (JSON, YAML)
enumerated-values.schema - Enum validation examples (JSON, YAML)
person.schema - Person object with AsyncAPI-specific annotations (JSON, YAML)
regex-pattern.schema - Regular expression pattern validation (JSON, YAML)

2.1.0

arrays.schema - Array validation for AsyncAPI 2.1.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

2.2.0

arrays.schema - Array validation for AsyncAPI 2.2.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

2.3.0

arrays.schema - Array validation for AsyncAPI 2.3.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

2.4.0

arrays.schema - Array validation for AsyncAPI 2.4.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

2.5.0

arrays.schema - Array validation for AsyncAPI 2.5.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

2.6.0

arrays.schema - Array validation for AsyncAPI 2.6.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

3.0.0

arrays.schema - Array validation for AsyncAPI 3.0.0 (JSON, YAML)
complex-object.schema - Complex object structures (JSON, YAML)
conditional-validation-if-else.schema - Conditional validation (JSON, YAML)
draft-07-core-schema-meta-schema - Extended meta-schema (JSON, YAML)
enumerated-values.schema - Enumeration examples (JSON, YAML)
person.schema - Person object schema (JSON, YAML)
regex-pattern.schema - Pattern validation (JSON, YAML)

OpenAPI Schema

OpenAPI Schema is based on JSON Schema but includes extensions specific to the OpenAPI Specification. It's used to define request and response payloads in REST APIs.

3.0.0

schema - Basic OpenAPI 3.0.0 schema example (JSON, YAML)

3.0.1

schema - OpenAPI 3.0.1 schema with updated features (JSON, YAML)

3.0.2

schema - OpenAPI 3.0.2 schema example (JSON, YAML)

3.0.3

schema - OpenAPI 3.0.3 schema with latest features (JSON, YAML)

XML

XML Schema Definition (XSD) is a recommendation of the World Wide Web Consortium that specifies how to formally describe the elements in an XML document. XSD defines the structure, content, and semantics of XML documents, allowing for validation and strong typing of XML data.

In AsyncAPI, XML schemas can be used to define message payloads when working with XML-based protocols or systems that require XML data formats. The XML schema is embedded within the AsyncAPI document using the schemaFormat property set to application/xml.

XML schemas offer several advantages for API definitions:

Strong typing and validation: XSD provides robust validation capabilities with built-in data types and constraints
Wide industry adoption: XML is supported across many enterprise systems and legacy applications
Rich expression: Complex data structures can be precisely defined with namespaces, attributes, and elements
Tooling support: Many tools exist for working with XML schemas, including validators and code generators

When to Use XML Schemas in AsyncAPI

XML schemas are particularly useful in the following scenarios:

Integrating with enterprise systems that use XML as their primary data format
Working with SOAP-based services or XML-RPC
Maintaining backward compatibility with existing XML-based APIs
Industries with established XML standards (like finance, healthcare, or telecommunications)
When strong validation and type checking are required

Examples

User Schema - Defines a simple user data structure with display name and email (JSON, YAML)

The User schema example demonstrates how to embed an XML schema within an AsyncAPI document. The schema defines a User element with two child elements:

xml

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified">
  <xs:element name="User">
    <xs:complexType>
      <xs:sequence>
        <xs:element name="displayName" type="xs:string">
            <xs:annotation>
              <xs:documentation>Name of the user</xs:documentation>
            </xs:annotation>
        </xs:element>
        <xs:element name="email" type="xs:string">
            <xs:annotation>
              <xs:documentation>Email of the user</xs:documentation>
            </xs:annotation>
        </xs:element>
      </xs:sequence>
    </xs:complexType>
  </xs:element>
</xs:schema>

This schema can be used to validate XML messages that contain user information, ensuring they have the required displayName and email elements with proper string values.

Other Formats

AsyncAPI also supports several other schema formats:

RAML

RAML (RESTful API Modeling Language) is a YAML-based language for describing RESTful APIs.

application/raml+yaml;version=1.0 - RAML 1.0 schema format

Google Protobuf

Protocol Buffers (Protobuf) is Google's language-neutral, platform-neutral, extensible mechanism for serializing structured data.

application/vnd.google.protobuf;version=2 - Protobuf version 2 schema format
application/vnd.google.protobuf;version=3 - Protobuf version 3 schema format

Special Cases

The Multi-Format Schema Object handles several special cases:

Empty schemaFormat

When the schemaFormat property is empty, the schema is treated as an AsyncAPI Schema Object.

Null schemaFormat

When the schemaFormat property is null, the schema is treated as an AsyncAPI Schema Object.

Without schemaFormat

When the schemaFormat property is not provided, the schema defaults to the AsyncAPI Schema Object format.

HTTP Security Schema

OAuth2 Security Schema

Flows

SASL Security Schema

Multi-Format Schema ​

What is Multi-Format Schema Object in AsyncAPI? ​

Avro ​

1.9.0 ​

1.9.1 ​

1.9.2 ​

1.10.0 ​

1.10.1 ​

1.10.2 ​

1.11.0 ​

1.11.1 ​

JSON Schema ​

Draft-07 ​

AsyncAPI Schema ​

2.0.0 ​

2.1.0 ​

2.2.0 ​

2.3.0 ​

2.4.0 ​

2.5.0 ​

2.6.0 ​

3.0.0 ​

OpenAPI Schema ​

3.0.0 ​

3.0.1 ​

3.0.2 ​

3.0.3 ​

XML ​

When to Use XML Schemas in AsyncAPI ​

Examples ​

Other Formats ​

RAML ​

Google Protobuf ​

Special Cases ​

Empty schemaFormat ​

Null schemaFormat ​

Without schemaFormat ​

Multi-Format Schema

What is Multi-Format Schema Object in AsyncAPI?

Avro

1.9.0

1.9.1

1.9.2

1.10.0

1.10.1

1.10.2

1.11.0

1.11.1

JSON Schema

Draft-07

AsyncAPI Schema

2.0.0

2.1.0

2.2.0

2.3.0

2.4.0

2.5.0

2.6.0

3.0.0

OpenAPI Schema

3.0.0

3.0.1

3.0.2

3.0.3

XML

When to Use XML Schemas in AsyncAPI

Examples

Other Formats

RAML

Google Protobuf

Special Cases

Empty schemaFormat

Null schemaFormat

Without schemaFormat