Skip to content

feat: check AsyncAPI sources in Arazzo source validation - #324

Merged
TristanSpeakEasy merged 7 commits into
feat/asyncapi-stage3-referencesfrom
feat/asyncapi-stage5-arazzo-sources
Nov 18, 2026
Merged

TristanSpeakEasy merged 7 commits into
feat/asyncapi-stage3-referencesfrom
feat/asyncapi-stage5-arazzo-sources

Conversation

@TristanSpeakEasy

@TristanSpeakEasy TristanSpeakEasy commented Nov 18, 2026 •

Copy link
Copy Markdown
Member

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 feat!: add Arazzo 1.1 support with source validation, lint, graph, bootstrap and explore commands #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 feat!: add Arazzo 1.1 support with source validation, lint, graph, bootstrap and explore commands #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.

Written for commit cc972a1. Summary will update on new commits.

View guided diff

@TristanSpeakEasy
TristanSpeakEasy requested a review from a team as a code owner November 18, 2026 00:48

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 13 files

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

Comment thread arazzo/sourcevalidation_asyncapi.go Resolved
Comment thread arazzo/sourcevalidation_asyncapi.go Resolved
Comment thread arazzo/arazzo_examples_test.go Resolved

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 6 files (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Shadow auto-approve: would require human review. Adds AsyncAPI source loading and validation with new errors and warnings; the dismissed additionalProperties-header warning still applies, and the new validation semantics are product decisions needing human sign-off.

View guided diff | Turn on auto-fix | Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment •

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

All reported issues were addressed across 2 files (changes from recent commits).

Shadow auto-approve: would not auto-approve because issues were found.

View guided diff | Turn on auto-fix | Re-trigger cubic

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

0 issues found across 1 file (changes from recent commits).

Confidence score: 5/5

  • Automated review surfaced no issues in the provided summaries.
  • No files require special attention.

Shadow auto-approve: would require human review. Adds AsyncAPI source loading and validation with new errors and warnings; the dismissed additionalProperties-header warning still applies, and validation strictness/spec choices remain human decisions.

View guided diff | Turn on auto-fix | Re-trigger cubic

* feat: add openapi asyncapi validate command

* chore: update cmd/openapi to the root module with the asyncapi package

* docs: describe the AsyncAPI header check in arazzo validate help

* chore: pin the CLI to the latest AsyncAPI stack root module

* test: cover the asyncapi CLI command wiring and resolution errors

* test: don't execute the process-exiting asyncapi command in tests
@TristanSpeakEasy
TristanSpeakEasy merged commit b6b4880 into feat/asyncapi-stage3-references Nov 18, 2026
2 checks passed
@TristanSpeakEasy
TristanSpeakEasy deleted the feat/asyncapi-stage5-arazzo-sources branch November 18, 2026 10:40
TristanSpeakEasy added a commit that referenced this pull request Nov 18, 2026
…t rules (#323)

* feat: resolve AsyncAPI references, apply traits and check cross-object rules

* fix: address AsyncAPI reference resolution review feedback

* perf: skip the explicit null lookup for fields that are set

* test: drop the AsyncAPI channel SyncChanges error test now that null handling is generic

* fix: report AsyncAPI diagnostics on trait-merged mappings at the winning contributor

* test: cover AsyncAPI reference resolution, traits, checks and null syncing

* test: address review feedback on AsyncAPI stage 3 coverage tests

* feat: check AsyncAPI sources in Arazzo source validation (#324)

* feat: check AsyncAPI sources in Arazzo source validation

* fix: treat an empty AsyncAPI operation messages list as no messages

* test: cover AsyncAPI step target edge cases in Arazzo source validation

* test: assert the load warning in the AsyncAPI source edge case tests

* feat: add openapi asyncapi validate command (#326)

* feat: add openapi asyncapi validate command

* chore: update cmd/openapi to the root module with the asyncapi package

* docs: describe the AsyncAPI header check in arazzo validate help

* chore: pin the CLI to the latest AsyncAPI stack root module

* test: cover the asyncapi CLI command wiring and resolution errors

* test: don't execute the process-exiting asyncapi command in tests
TristanSpeakEasy added a commit that referenced this pull request Nov 18, 2026
…and walking (#322)

* feat: add complete AsyncAPI 3.x document model with local validation and walking

* fix: address AsyncAPI document model review feedback

* test: cover the AsyncAPI stage 2 document model, walker and references

* feat: resolve AsyncAPI references, apply traits and check cross-object rules (#323)

* feat: resolve AsyncAPI references, apply traits and check cross-object rules

* fix: address AsyncAPI reference resolution review feedback

* perf: skip the explicit null lookup for fields that are set

* test: drop the AsyncAPI channel SyncChanges error test now that null handling is generic

* fix: report AsyncAPI diagnostics on trait-merged mappings at the winning contributor

* test: cover AsyncAPI reference resolution, traits, checks and null syncing

* test: address review feedback on AsyncAPI stage 3 coverage tests

* feat: check AsyncAPI sources in Arazzo source validation (#324)

* feat: check AsyncAPI sources in Arazzo source validation

* fix: treat an empty AsyncAPI operation messages list as no messages

* test: cover AsyncAPI step target edge cases in Arazzo source validation

* test: assert the load warning in the AsyncAPI source edge case tests

* feat: add openapi asyncapi validate command (#326)

* feat: add openapi asyncapi validate command

* chore: update cmd/openapi to the root module with the asyncapi package

* docs: describe the AsyncAPI header check in arazzo validate help

* chore: pin the CLI to the latest AsyncAPI stack root module

* test: cover the asyncapi CLI command wiring and resolution errors

* test: don't execute the process-exiting asyncapi command in tests
TristanSpeakEasy added a commit that referenced this pull request Nov 18, 2026
* feat: add AsyncAPI stage 1 foundations (version policy, root/info models, AsyncAPI JSON Schema)

* fix: address AsyncAPI stage 1 review feedback

* fix: don't repeat the location in AsyncAPI schema type mismatch messages

* test: cover the AsyncAPI stage 1 schema, info and version models

* feat: add complete AsyncAPI 3.x document model with local validation and walking (#322)

* feat: add complete AsyncAPI 3.x document model with local validation and walking

* fix: address AsyncAPI document model review feedback

* test: cover the AsyncAPI stage 2 document model, walker and references

* feat: resolve AsyncAPI references, apply traits and check cross-object rules (#323)

* feat: resolve AsyncAPI references, apply traits and check cross-object rules

* fix: address AsyncAPI reference resolution review feedback

* perf: skip the explicit null lookup for fields that are set

* test: drop the AsyncAPI channel SyncChanges error test now that null handling is generic

* fix: report AsyncAPI diagnostics on trait-merged mappings at the winning contributor

* test: cover AsyncAPI reference resolution, traits, checks and null syncing

* test: address review feedback on AsyncAPI stage 3 coverage tests

* feat: check AsyncAPI sources in Arazzo source validation (#324)

* feat: check AsyncAPI sources in Arazzo source validation

* fix: treat an empty AsyncAPI operation messages list as no messages

* test: cover AsyncAPI step target edge cases in Arazzo source validation

* test: assert the load warning in the AsyncAPI source edge case tests

* feat: add openapi asyncapi validate command (#326)

* feat: add openapi asyncapi validate command

* chore: update cmd/openapi to the root module with the asyncapi package

* docs: describe the AsyncAPI header check in arazzo validate help

* chore: pin the CLI to the latest AsyncAPI stack root module

* test: cover the asyncapi CLI command wiring and resolution errors

* test: don't execute the process-exiting asyncapi command in tests

* refactor: return AsyncAPI reference chain results by value

* chore: pin cmd/openapi to the merged AsyncAPI root module commit

* test: use a platform absolute path in the AsyncAPI absolute reference test

* test: cover the remaining AsyncAPI patch lines and drop unreachable error branches

* chore: pin cmd/openapi to the latest AsyncAPI root module commit
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant