Supported capabilities
This reference summarizes the production workflows supported by
asyncapi-generator. The implemented parser profile supports the
AsyncAPI 3.0 specification line,
so 3.0.x documents are accepted, including suffixed versions such as
3.0.0-rc1. AsyncAPI 3.1.x is recognized but rejected because that parser
profile is not implemented. Support is not extended automatically when a new
AsyncAPI version is published.
The matrix describes supported workflow boundaries rather than every AsyncAPI field or JSON Schema keyword. See the linked references for configuration and the linked approvals or focused tests for executable examples.
| Capability | Supported input | Result | Important limitations | Verified example |
|---|---|---|---|---|
| Input documents | UTF-8 YAML (.yaml or .yml) and JSON (.json) documents declaring AsyncAPI 3.0.x. |
A source-aware AsyncAPI domain model after structural parsing and semantic validation. | Format is selected by extension. Unsupported extensions, malformed input, duplicate keys, invalid UTF-8, and resource-limit violations fail explicitly. See the parser contract. | AsyncApiDocumentLoaderTest loads equivalent YAML and JSON and verifies the unsupported 3.1.x diagnostic. |
| Local and external references | Internal JSON Pointers, relative local paths, and file: URIs to complete AsyncAPI documents, selected fragments, and supported native schema assets. |
References are loaded eagerly, resolved relative to the owning source, and tracked in the load result with their canonical source files. Cycles and repeated targets are deduplicated. | HTTP and other remote schemes are not supported. Raw external containers require a pointer to the requested object; unrelated surrounding content is not imported. Referenced local files are trusted build input and are not restricted to a project root. | The focused external/main.yaml fixture and ExternalReferenceLoadingTest cover local resolution, fragments, identity, cycles, and failures. |
| Structured diagnostics and semantic validation | Reader failures, parser failures, unresolved references, semantic validation errors, and advisories from the root document or loaded external sources. | Parser failures expose a stable category and code, path, actual and expected values where applicable, and source location. Validation findings expose a rule code, authority, severity, path, and source location; warnings are returned without preventing generation. | Rendered prose is for people; callers should use structured fields for programmatic handling. Output-specific incompatibilities that depend on the requested target are reported during generation rather than by coercing or rejecting the parsed contract. | AsyncApiDocumentLoaderTest verifies structured parser locations, validation errors, external warnings, and warning formatting. |
| Document bundling | A parsed and validated AsyncAPI 3.0.x model whose supported local references have been loaded. |
A self-contained domain document: supported external objects are inlined, and recursive external schemas are promoted to local components while internal contract topology is preserved. | Bundling does not fetch remote references or import unrelated content from foreign documents. A promoted component-name collision fails explicitly instead of overwriting a root component. | BundledDocumentApprovalTest protects fixture-backed multi-file, fragment, recursive, component-catalog, and interoperability outputs. |
| Kotlin models | Supported component Schema Objects, discovered message payload schemas, and supported object-valued Kafka key schemas. | Kotlin data classes with nullability, JVM type mappings, and Jakarta Validation annotations where supported. | Requires the kotlin profile and modelPackage; kotlin-data-class is its only regular model shape. Applications provide JSON serialization and invoke validation. Configuration and schema restrictions are listed in Model types. |
JSON-compatible Kotlin DTO links the source fixture, approval test, and complete approved model. |
| Java classes and records | Supported component Schema Objects, discovered message payload schemas, and supported object-valued Kafka key schemas. | Java classes by default, or Java records with modelConfig.modelType=java-record, including supported JVM type and validation-annotation mappings. |
Requires the java profile and modelPackage. Records are immutable and do not have generated no-argument constructors or setters. |
Java record is fixture-backed; the same approval test also protects the complete default Java class. |
| Spring Kafka producer and consumer contracts | Supported Kafka channels and messages, including supported payload, record-key, header, and channel-parameter schemas. | Java or Kotlin producer and consumer interfaces with typed methods, topic expressions, headers, and optional configured validation annotations. Producer and consumer interfaces can be enabled independently. | Requires a Java or Kotlin source profile, both package fields, clientType=spring-kafka, and clientContract=interface. AsyncAPI operation actions do not select producer or consumer generation. Applications implement the interfaces and supply Spring and Kafka runtime wiring. |
Spring Kafka contracts with typed headers links the contract, approvals, and complete producer and consumer interfaces. |
| Additional serialized producer payload methods | A supported Spring Kafka producer contract plus byte-array, string, or both in producer.additionalPayloadTypes. |
Additional producer methods accepting byte-array and/or string payloads alongside the typed-model method. | The methods are additive and duplicate settings are removed. The application is responsible for serialization; payload validation annotations are not applied to these additional methods. | SpringKafkaClientApprovalTest protects complete Java and Kotlin producers with both additional payload forms. |
| Avro Projection | The supported projection subset of AsyncAPI Schema Objects. | .avsc schema artifacts through generatorName=avro-schema. |
Projection maps supported AsyncAPI schema structure to Avro; it is not native Avro passthrough and does not generate SpecificRecord source. schemaPackage is required. |
Avro Projection from an AsyncAPI Schema Object links the fixture, approval test, and complete .avsc output. |
| Native Avro | Native Avro payloads embedded by an AsyncAPI Multi Format Schema Object or loaded from a local schema asset. | Native .avsc artifacts; modelType=avro-specific-record additionally generates Java SpecificRecord source with either Java or Kotlin source profile. |
SpecificRecord generation requires an Avro namespace exactly matching modelPackage. Generated runtime models are Java source, and the application must provide the Avro runtime. The schema-only avro-schema profile does not generate SpecificRecords. |
Native Avro schema and SpecificRecord links the contract, approval test, and both approved artifacts. |
| Native Protobuf | Native Protobuf payloads embedded by an AsyncAPI Multi Format Schema Object or loaded from a local schema asset. | .proto artifacts through protobuf-schema; modelType=protobuf-message additionally generates Java messages, plus the official Kotlin DSL for the Kotlin source profile. |
Runtime-model generation requires modelPackage to match option java_package, or the Protobuf package when that option is absent, and requires option java_multiple_files = true. schemaPackage controls the output path but does not rewrite declarations. |
Native Protobuf schema artifact links the contract, approval test, and complete .proto output. Frontend integration tests also compile the generated runtime models. |
| JSON Schema | Supported AsyncAPI Schema Objects and supported native JSON Schema Draft 7 payloads. | Draft 7 .schema.json artifacts through generatorName=json-schema. |
schemaPackage is required. This profile emits schemas without runtime model source and does not promise complete JSON Schema keyword coverage. Unsupported generation features fail at the compatibility boundary. |
JsonSchemaApprovalTest protects the complete approved Draft 7 schema. |
| Maven frontend | One configured plugin execution with an input document, generator profile, and the output fields required by that profile. | Generated sources and resources under the configured directory, registered with the Maven project; bundled document output is written to outputFile when configured. |
Each execution is one generation request. Configuration uses the public Maven XML shape in the generator configuration reference. | AsyncApiGeneratorMojoTest exercises models, clients, every schema family, and YAML/JSON document output. |
| Gradle frontend | One or more named Gradle executions with an input document, generator profile, and compatible output fields. | One task per execution plus an aggregate task; generated JVM sources and schema resources are registered by artifact type. | clientConfig is shared and applies only to named executions that configure client output. Each execution has its own default output directory. See the frontend mapping. |
AsyncApiPluginTest exercises Kotlin and Groovy DSLs, incremental inputs, compiled models, schema resources, clients, and document output. |
| CLI frontend | One invocation with an input document, generator profile, and compatible output options. | The same core models, contracts, schemas, and bundled documents as the build-tool frontends, written below the selected output paths. | The CLI does not register generated files with a build tool. It has no named executions or shared configuration block; repeatable options form lists and maps for one request. See the frontend mapping. | AsyncApiGeneratorCliTest exercises all generator profiles and major configuration failures. |
| Bundled YAML and JSON documents | Any supported, successfully loaded and validated contract, including supported multi-file local references. | asyncapi-yaml and asyncapi-json write one self-contained document to outputFile. Source and schema profiles can also write an optional bundled YAML document. |
Document-only profiles require outputFile and reject model, client, and schema configuration. Serialization preserves parsed semantics, not comments, anchors, quoting, or collection style; see the YAML output contract. |
AsyncApiGeneratorCliTest verifies both document profiles; the bundler approvals contain complete self-contained outputs. |
Explicit non-goals
- The project does not promise complete AsyncAPI or JSON Schema coverage. It supports the documented production workflows and fails explicitly when a requested output cannot represent a valid parsed contract safely.
- It does not support remote reference retrieval or automatically adopt new AsyncAPI specification versions.
- Generated Spring Kafka interfaces do not configure brokers, serializers, Spring beans, listener containers, consumer groups, retries, transactions, or deployment infrastructure. Applications provide that runtime behavior.
- Schema generation does not replace the Avro, Protobuf, JSON, validation, or Spring Kafka runtimes required by generated application code.