feat: add AsyncAPI 3.x support and AsyncAPI sources in Arazzo
Merged
TR
2d ago+20347+20347+01234567890123456789012345678901234567890123456789-95-95-01234567890123456789
Why
Arazzo 1.1 lets workflows target AsyncAPI documents as source descriptions, but this repo couldn't parse or validate AsyncAPI, so those steps went unchecked. This PR adds an asyncapi package that reuses the existing marshaller, values, extensions, references and validation plumbing, so it works the same way as the openapi and arazzo packages, and wires it into Arazzo source validation and the CLI.
It was built as a stack (#322, #323, #324, #326) that has been squash-merged into this branch, so this is the whole feature.
What changed
- Version policy (
internal/asyncapiversion): supports AsyncAPI3.0.xand3.1.x(latest3.1.0), and parses schema formats (native AsyncAPI, JSON Schema Draft 07, and foreign formats such as Avro, RAML, Protobuf and OpenAPI schemas). - Document model (
asyncapi): the complete 3.x document (info, servers, channels, operations, messages, components, security schemes, bindings, traits) withUnmarshal,Marshal,Sync,WalkandValidate, matching theopenapipackage API. - References, traits and checks:
ResolveAllReferencesresolves typed references within and across documents (local files,VirtualFS, HTTP), reports cycles and wrong-kind targets, applies operation and message traits to an effective view, and runs cross-object checks (for example an operation's messages must belong to its channel). - Schemas (
jsonschema/asyncapi): a separate package fromjsonschema/oas3, because AsyncAPI schemas are a Draft 07 superset (stringdiscriminator,deprecated,externalDocs, boolean schemas,dependencies,itemsas schema or array). Supports{schemaFormat, schema}multi format schemas and validates against the bundled Draft 07 metaschema, so no network access is needed. - Arazzo sources (
arazzo): AsyncAPI source descriptions are loaded and checked.operationIdandchannelPathtargets must exist, sent headers must be declared,actionmust suit the source type, andcorrelationIdis only used with messages that declare one. - CLI: new
openapi asyncapi validatecommand, documented inREADME.mdand the command README. - Shared code: a new
validation-unsupported-formatwarning rule, andmarshaller/syncer.gonow handles explicit nulls when syncing.
Review notes
- Foreign schema formats (Avro, Protobuf, etc.) are preserved as raw YAML and round-trip, but they aren't validated. They get a
validation-unsupported-formatwarning instead. - The core
Items/Dependencyunions are dedicated struct types rather than recursive generic aliases, which triggered a Go compiler panic. cmd/openapi/go.modis pinned to a commit on this branch (per AGENTS.md). It will need re-pinning to a release after merge as usual.
Testing
- Unit and integration tests across all new packages. Patch coverage is 100% locally against
main. - CLI integration tests cover
openapi asyncapi validate. mise cipasses locally, and CI passes on Linux and Windows.