Supported specifications
This page lists the specification versions each part of the package family reads, validates, or emits. Version numbers below are the ones the code and the test suites actually cover.
| Specification | Versions | Generated by | Read / validated by |
|---|---|---|---|
| AsyncAPI | 3.1.0 (default), 2.6.0 | Bielu.AspNetCore.AsyncApi |
Bielu.AspNetCore.AsyncApi.Cli, Bielu.AspNetCore.AsyncApi.Merger |
| Arazzo | 1.0.x, 1.1.x | Bielu.AspNetCore.Arazzo (1.1.0 by default, set with ArazzoOptions.Version; also written at build time) |
Bielu.Arazzo, Bielu.Arazzo.Readers, Bielu.Arazzo.Cli |
| Overlay | 1.0.x, 1.1.x | not generated; applied by Bielu.Overlay |
Bielu.Overlay, Bielu.Overlay.Readers, Bielu.Overlay.Cli |
| Protocol Buffers | proto2, proto3 (schemaFormat version 2 or 3); editions files keep their JSON Schema |
Bielu.AspNetCore.AsyncApi.Protobuf, as .proto payload sources rendered from descriptors |
not read |
| xRegistry | 1.0-rc4 (core, HTTP binding, message and schema registries; read-only) | Bielu.AspNetCore.XRegistry, served from the AsyncAPI documents |
not read |
| Model Context Protocol | as negotiated by the ModelContextProtocol C# SDK 2.3 |
Bielu.AspNetCore.ApiDescriptions.Mcp (experimental), as tools and resources over the served documents |
not read |
| API Catalog (RFC 9727) | RFC 9727, as an RFC 9264 Linkset | Bielu.AspNetCore.ApiCatalog (see API catalog) |
not read |
| CloudEvents | 1.0 (binary and structured mode; HTTP, Kafka, AMQP, MQTT bindings) | Bielu.AspNetCore.AsyncApi.CloudEvents, as AsyncAPI message headers or payload |
not read |
| Apache Avro | 1.9.0 declared (schemaFormat), configurable |
Bielu.AspNetCore.AsyncApi.Avro, as AsyncAPI message payloads |
not read |
AsyncAPI
AsyncApiOptions.AsyncApiVersion selects the output version:
| Option value | Document declares |
|---|---|
AsyncApiVersion.AsyncApi3_0 (default) |
3.1.0 |
AsyncApiVersion.AsyncApi2_0 |
2.6.0 |
Generated documents for both versions are validated against the official AsyncAPI JSON Schemas in the test suite
(AsyncApiOfficialSchemaConformanceTests), so output that drifts from the spec fails CI.
Some features only exist in one version of the specification. reply on operations, for example, is an AsyncAPI 3.x
concept and has no equivalent in 2.6.0.
Protocol bindings come from ByteBard.AsyncAPI.NET.Bindings 4.0. The bindings that 3.0.1 serialized in a form the
official 3.1.0 schema rejects are fixed there; see Broker bindings.
Arazzo
The object model, readers, validator, and CLI accept arazzo: 1.0.x and arazzo: 1.1.x. Following section 5.1 of the
spec, patch versions are not distinguished. Any other value, including 1.10.0, is rejected.
Overlay
Bielu.Overlay accepts overlay: 1.0.x and overlay: 1.1.x.
Note
The Overlay Specification is defined for OpenAPI documents. Applying an overlay to an AsyncAPI or Arazzo document is an extension of this project, not behavior sanctioned by the specification. The OpenAPI Initiative closed Overlay-Specification#268 as "not planned", and we filed #367 to revisit it. See the Overlay overview for how targeting works.