feat: add AsyncAPI 3.x support and AsyncAPI sources in Arazzo

Merged
TR
2d ago
+20347-95

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 AsyncAPI 3.0.x and 3.1.x (latest 3.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) with Unmarshal, Marshal, Sync, Walk and Validate, matching the openapi package API.
  • References, traits and checks: ResolveAllReferences resolves 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 from jsonschema/oas3, because AsyncAPI schemas are a Draft 07 superset (string discriminator, deprecated, externalDocs, boolean schemas, dependencies, items as 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. operationId and channelPath targets must exist, sent headers must be declared, action must suit the source type, and correlationId is only used with messages that declare one.
  • CLI: new openapi asyncapi validate command, documented in README.md and the command README.
  • Shared code: a new validation-unsupported-format warning rule, and marshaller/syncer.go now 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-format warning instead.
  • The core Items/Dependency unions are dedicated struct types rather than recursive generic aliases, which triggered a Go compiler panic.
  • cmd/openapi/go.mod is 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 ci passes locally, and CI passes on Linux and Windows.