Skip to content

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

Merged
TristanSpeakEasy merged 12 commits into
mainfrom
feat/asyncapi-stage1-foundations
Nov 18, 2026
Merged

TristanSpeakEasy merged 12 commits into
mainfrom
feat/asyncapi-stage1-foundations

Conversation

@TristanSpeakEasy

@TristanSpeakEasy TristanSpeakEasy commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

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.

@TristanSpeakEasy TristanSpeakEasy added enhancement New feature or request jsonschema Related to JSON Schema handling validation Related to validation logic labels Nov 17, 2026
@TristanSpeakEasy
TristanSpeakEasy requested a review from a team as a code owner November 17, 2026 06:27

@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 22 files

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

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

Comment thread jsonschema/asyncapi/validation.go Resolved
Comment thread jsonschema/asyncapi/validation.go Resolved
Comment thread asyncapi/asyncapi.go Resolved
Comment thread asyncapi/info.go Resolved
Comment thread asyncapi/asyncapi.go Resolved
@codecov

codecov Bot commented Nov 17, 2026 •

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

@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 7 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 auto-approve. Adds new AsyncAPI 3.x parsing/validation foundation: version policy, root/info models, Draft 07 schema package, and an unsupported-format warning rule. Fully additive with unit tests and no existing behavior, rollout, or operational tradeoffs.

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 13 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 auto-approve. Adds AsyncAPI 3.x parsing/validation foundation: version policy, root/info models, Draft 07 schema package, and an unsupported-format warning. Fully additive with extensive unit tests and no existing behavior, rollout, or operational tradeoffs.

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

TristanSpeakEasy and others added 4 commits November 18, 2026 20:40
…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

@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 auto-approve. Adds AsyncAPI 3.x modeling and validation, plus Arazzo target checks, following established patterns and backed by extensive tests; only routine correctness risk remains.

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 3 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 auto-approve. Adds AsyncAPI 3.x modeling and validation, including arazzo source checks and a new CLI validate command, following established patterns and backed by extensive tests; only routine correctness risk remains.

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 auto-approve. Adds complete AsyncAPI 3.x support (models, validation, resolution, CLI validate) and Arazzo source checking, following existing package patterns with extensive tests; only routine correctness risk remains.

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

@TristanSpeakEasy TristanSpeakEasy changed the title feat: add AsyncAPI stage 1 foundations (version policy, root/info models, AsyncAPI JSON Schema) feat: add AsyncAPI 3.x support and AsyncAPI sources in Arazzo Nov 18, 2026

@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 11 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 auto-approve. Adds AsyncAPI 3.x parsing/validation/resolution and Arazzo source checks plus a CLI validate command, mirroring existing package patterns with comprehensive tests; the post-review delta is refactors and tests only, so no new product or operational tradeoffs.

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

@TristanSpeakEasy
TristanSpeakEasy merged commit 6693aa2 into main Nov 18, 2026
14 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

enhancement New feature or request jsonschema Related to JSON Schema handling validation Related to validation logic

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant