feat: check AsyncAPI sources in Arazzo source validation

Merged
TR
3d ago
+1708-84

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 VirtualFS and HTTPClient. SourceDocument gets an AsyncAPI field. 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: operationId is looked up by key in the root operations map. channelPath is a JSON Pointer to a channel key under /channels or /components/channels, never its address. operationPath into 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 channelPath into a non-AsyncAPI source, an untyped source detected as AsyncAPI with no action, and action on a step whose untyped source turns out to be OpenAPI.
    • Warnings: a header parameter no message declares, any non-header parameter location, requestBody on a receive step, and correlationId when no message declares one.
  • Docs: arazzo/README.md gets an "AsyncAPI sources" section covering what's checked and what deliberately isn't, and the CLI README is updated. arazzo validate and arazzo lint need no code change.

Review notes

  • operationPath is rejected rather than supported. Arazzo 1.1 only names operationId and channelPath for AsyncAPI steps, and #305 already requires action for AsyncAPI steps while forbidding it with operationPath. Supporting it would make a step that can never be valid look fine.
  • Step action isn't compared with the AsyncAPI operation action. The step describes the workflow's side and the operation the application's, and Arazzo doesn't define how they relate. async-valid.arazzo.yaml has 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, patternProperties or 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/openapi module picks this up once its root module dependency is bumped. No replace directive.

Testing

  • arazzo/sourcevalidation_asyncapi_test.go with new fixtures under arazzo/testdata/sources/:
    • a mixed OpenAPI and AsyncAPI workflow based on the Arazzo 1.1 spec's async example (placeOrder send, confirmOrder receive), 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.
  • 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_type now suggests asyncapi for an untyped AsyncAPI source.
  • mise test ./arazzo/... ./asyncapi/... and mise ci pass locally. mise ci runs outside the sandbox because the JSON Schema suite needs localhost: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 asyncapi package using the caller's VirtualFS and HTTPClient; 2.x sources warn as unsupported.
  • operationId must be a key in the root operations map; channelPath must be a JSON Pointer to a channel key under /channels or /components/channels; operationPath is 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. requestBody on a receive step and correlationId with no message declaration warn, and action is 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 empty messages list means the operation has no messages rather than falling back to the channel's.
  • The linter's source_description_type fix now suggests asyncapi for loaded untyped sources.

AsyncAPI CLI

  • openapi asyncapi validate checks 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.