feat: check AsyncAPI sources in Arazzo source validation
Stacked on #323, which is stacked on #322 and #321. Review those first; this PR's base is the #323 branch. It doesn't depend on the Stage 4 CLI command.
Why
Arazzo 1.1 steps can target AsyncAPI documents with operationId or channelPath, but since #305 LoadSourceDescriptions skips AsyncAPI sources with a hint and ValidateSources never checks those steps. A typo in an AsyncAPI operation key or channel pointer only shows up at runtime. With the asyncapi package from #321 to #323 the gap is wiring, so this connects the two.
What changed
- Loading: AsyncAPI sources go through the same loader as OpenAPI ones and are resolved with the caller's
VirtualFSandHTTPClient.SourceDocumentgets anAsyncAPIfield. Declared type mismatches work as before. AsyncAPI 2.x sources get an "unsupported version" warning and aren't checked. Unresolved references give the same "some checks may be skipped" warning as OpenAPI, while warnings from resolution (such as an Avro schema that isn't validated) are ignored. - Targets:
operationIdis looked up by key in the rootoperationsmap.channelPathis a JSON Pointer to a channel key under/channelsor/components/channels, never itsaddress.operationPathinto an AsyncAPI source is an error. - Checks against the messages the step can send or receive (the operation's
messages, or all messages of its channel, with traits applied):- Errors: missing operation or channel, a
channelPathinto a non-AsyncAPI source, an untyped source detected as AsyncAPI with noaction, andactionon a step whose untyped source turns out to be OpenAPI. - Warnings: a header parameter no message declares, any non-header parameter location,
requestBodyon areceivestep, andcorrelationIdwhen no message declares one.
- Errors: missing operation or channel, a
- Docs:
arazzo/README.mdgets an "AsyncAPI sources" section covering what's checked and what deliberately isn't, and the CLI README is updated.arazzo validateandarazzo lintneed no code change.
Review notes
operationPathis rejected rather than supported. Arazzo 1.1 only namesoperationIdandchannelPathfor AsyncAPI steps, and #305 already requiresactionfor AsyncAPI steps while forbidding it withoperationPath. Supporting it would make a step that can never be valid look fine.- Step
actionisn't compared with the AsyncAPI operationaction. The step describes the workflow's side and the operation the application's, and Arazzo doesn't define how they relate.async-valid.arazzo.yamlhas a step with the opposite action to show it's accepted. - Channel address parameters (
{orderId}) have no matching Arazzo parameter location, so any non-header location is a warning rather than being mapped to channel parameters. - Partial targets stay quiet. "Not declared" warnings are skipped when a message or operation reference couldn't be resolved, or a headers schema uses composition,
if,patternPropertiesor a non JSON Schema format. Header names are matched case-insensitively. - Spec example deviation: the Arazzo 1.1 async example writes
$message.payload.orderId, which the 1.1 expression grammar (as implemented in #305) rejects, so the regression fixture uses$message.payload#/orderId. I didn't loosen the grammar here. - The
cmd/openapimodule picks this up once its root module dependency is bumped. Noreplacedirective.
Testing
arazzo/sourcevalidation_asyncapi_test.gowith new fixtures underarazzo/testdata/sources/:- a mixed OpenAPI and AsyncAPI workflow based on the Arazzo 1.1 spec's async example (
placeOrdersend,confirmOrderreceive), including a message from another file with a header and correlation ID from a trait,/components/channels, an escaped channel key (orders~1legacy), a composed headers schema and a differing action. It validates cleanly. - an error fixture covering each error and warning above, including a components operation key and a channel address that must not match.
- partial targets (unresolved operation or messages) that report nothing.
- a mixed OpenAPI and AsyncAPI workflow based on the Arazzo 1.1 spec's async example (
arazzo/sources_test.go: AsyncAPI 3.0 and 3.1 loading from a file and over HTTP, 2.x warning, type mismatches in both directions, unresolved references, and resolution warnings being ignored.- Linter:
source_description_typenow suggestsasyncapifor an untyped AsyncAPI source. mise test ./arazzo/... ./asyncapi/...andmise cipass locally.mise ciruns outside the sandbox because the JSON Schema suite needslocalhost:1234.
Summary by cubic
Validates Arazzo 1.1 steps that target AsyncAPI sources, closing the gap where operationId, channelPath, and operationPath steps were only checked structurally, and adds an openapi asyncapi validate command.
AsyncAPI source checks
- AsyncAPI 3.0 and 3.1 sources are loaded and reference-resolved via the
asyncapipackage using the caller'sVirtualFSandHTTPClient; 2.x sources warn as unsupported. operationIdmust be a key in the rootoperationsmap;channelPathmust be a JSON Pointer to a channel key under/channelsor/components/channels;operationPathis an error for AsyncAPI sources.- Header parameters must be declared by the target's messages (including traits in referenced files), matched case-insensitively; other locations warn.
requestBodyon areceivestep andcorrelationIdwith no message declaration warn, andactionis required on an untyped source detected as AsyncAPI. - Missing-declaration checks are skipped when a reference can't be resolved or a headers schema uses composition,
if,patternProperties, or a non-JSON Schema format. An explicitly emptymessageslist means the operation has no messages rather than falling back to the channel's. - The linter's
source_description_typefix now suggestsasyncapifor loaded untyped sources.
AsyncAPI CLI
openapi asyncapi validatechecks AsyncAPI 3.x documents with--resolve,--base-uri, and--strict, and lists unfollowed references and unvalidated schema formats as "Not checked" so a passing result isn't mistaken for complete validation.