Skip to content

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

Merged
TristanSpeakEasy merged 9 commits into
feat/asyncapi-stage2-document-modelfrom
feat/asyncapi-stage3-references
Nov 18, 2026
Merged

TristanSpeakEasy merged 9 commits into
feat/asyncapi-stage2-document-modelfrom
feat/asyncapi-stage3-references

Conversation

@TristanSpeakEasy

@TristanSpeakEasy TristanSpeakEasy commented Nov 17, 2026 •

Copy link
Copy Markdown
Member

Stacked on #322, which is stacked on #321. Review those first; this PR's base is the #322 branch.

Why

After Stage 2 the asyncapi package models a whole document, but every $ref stays unresolved. So callers can't follow an operation to its channel or messages, traits are never applied, and rules that span objects (like "an operation's messages must belong to its channel") can't be checked. This PR adds the explicit resolution step from the plan. That makes Stages 1 to 3 together the usable library.

What changed

  • (*AsyncAPI).ResolveAllReferences(ctx, ResolveAllOptions) with the same options as OpenAPI: AsyncAPILocation, DisableExternalRefs, VirtualFS and HTTPClient. It resolves every Reference Object, within the document and across files and URLs, following chains and resolving each relative reference against the document that contains it. Unmarshal, Validate and Walk still never do I/O.
  • Resolved accessors: GetObject() on Referenced* wrappers now returns the resolved object (same as OpenAPI). It also adds GetResolvedReference(), ReferenceObject.GetChannel/GetMessage/GetServer(), Tag.GetResolved(), AsyncAPI.GetResolvedExternalDocs() and AsyncAPI.GetResolvedSchema().
  • Schema references: a native schema $ref resolves to a typed schema. A Multi Format Schema Object whose schema is a $ref is resolved according to its format. JSON Schema based formats come back typed. Other formats, such as the spec's Avro schema: {$ref: './user-create.avsc'}, are loaded and kept unchanged, and a target that declares a different schemaFormat is reported. Protocol Buffers text resources aren't loaded and get a warning.
  • Traits (asyncapi/traits.go): Operation.GetEffective() and Message.GetEffective() return a separate snapshot with traits applied using ordered JSON Merge Patch, with the object's own values winning. GetTraitSource(field) reports which trait each top-level field came from. Diagnostics that only appear once traits are applied are reported, and ones already reported on the object or trait are not repeated.
  • Cross-object checks (asyncapi/checks.go): root operations must use a root channel, an operation's or reply's messages must be messages of its channel, root channels must use root servers, and a reply with a runtime address needs a channel without a fixed address.
  • asyncapi/README.md with usage and a support-limits table.
  • Shared marshaller fix: syncing used to delete an authored key: null whenever the public field was nil, so every Marshal dropped explicit nulls (in all packages, not just AsyncAPI). Explicit nulls are kept now while the value is unset. This replaces the Stage 2 workaround in core.Channel.SyncChanges, which is removed.

Review notes

  • Failures are diagnostics, not errors. Missing and wrong-kind targets, cycles, disallowed external refs and problems in loaded documents come back as validation errors at the referring $ref. Errors found in another document have DocumentLocation set. The returned error is only for things that stop resolution, such as a cancelled context.
  • No guessing a base directory. Without AsyncAPILocation, a relative reference to another document is reported rather than resolved against the working directory. The default HTTP client isn't a sandbox; the README says so and tells callers to pass their own client for untrusted input.
  • Cache and refresh. The shared references.Resolve is used behind an AsyncAPI-owned ResolutionTarget that namespaces cached objects by kind and schema format, so one location is never reused as the wrong type. Each call starts with a fresh cache and clears the previous call's state, so edits are picked up and stale targets aren't returned. Effective views from earlier calls stay as snapshots.
  • Resolution doesn't change the document. ResolveAllReferences syncs public edits into the backing nodes so traits see them. That's why the explicit-null fix was needed: without it, syncing removed description: null from traits, which changed both the document and the merge result.
  • Walking is unchanged. It still visits only authored locations and doesn't follow resolved references.
  • Known limits, also in the README:
    • $refs nested inside schema bodies aren't resolved yet.
    • An effective view's own references are only resolved when all its traits come from the same document as the object.
    • Wrong-kind targets in other documents are caught by validating the loaded object rather than by checking its location.

Testing

  • asyncapi/resolve_test.go covers:
    • in-document resolution through chains, including messages reached via #/channels/x/messages/y through a referenced channel
    • multi-file relative chains with an in-memory VirtualFS
    • remote relative chains with a fake HTTP client
    • preserving an Avro resource unchanged
    • a table of error cases: missing, wrong-kind, cycles, disabled, no location, missing file, denied client, each scope rule, format mismatch, Protocol Buffers, invalid external object
    • trait precedence and null deletion, provenance, an inherited diagnostic, ignored forbidden trait fields
    • refresh after edits and stale-target clearing
    • no implicit I/O (counting filesystem and client)
    • cancellation, walk unchanged after resolution, concurrent reads during resolution
  • marshaller/syncing_test.go covers the explicit-null fix.
  • mise ci passes locally, including race detection. It has to run outside the sandbox because the JSON Schema suite needs localhost:1234.

Summary by cubic

Adds explicit reference resolution for AsyncAPI documents so $refs can be followed, traits are applied, and rules spanning objects can be checked. Previously references stayed unresolved, traits were never applied, and cross-object rules couldn't be checked, while Unmarshal, Validate, and Walk still never perform I/O.

  • ResolveAllReferences resolves references in-document, across files and URLs, using the same options as OpenAPI (AsyncAPILocation, DisableExternalRefs, VirtualFS, HTTPClient); missing targets, cycles, and wrong-kind references come back as validation diagnostics.
  • Schema $refs resolve by format: JSON Schema–based ones come back typed, other formats load unchanged, and a mismatched schemaFormat is reported.
  • Resolved accessors: GetObject() on Referenced* wrappers, GetResolvedReference(), ReferenceObject.GetChannel/GetMessage/GetServer(), Tag.GetResolved(), and AsyncAPI.GetResolvedExternalDocs()/GetResolvedSchema().
  • Operation.GetEffective() and Message.GetEffective() return snapshots with traits applied via ordered JSON Merge Patch; GetTraitSource() reports the originating trait, and diagnostics on trait-merged fields are reported at the contributor.
  • Cross-object checks: root operations use root channels, an operation's or reply's messages belong to its channel, root channels use root servers, and a reply with a runtime address needs a channel without a fixed address.

Tooling

  • New openapi asyncapi validate command validates AsyncAPI 3.0/3.1 documents, optionally resolving external references.
  • Arazzo source validation now loads AsyncAPI sources and checks channelPath targets, that steps only send headers declared by the target's effective messages, and that correlationId is only used with messages that declare one.
  • Fixes a shared marshaller bug that deleted authored key: null entries during syncing; explicit nulls are preserved while the value is unset, replacing the workaround in core.Channel.SyncChanges, which is removed.

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

View guided diff Turn on auto-fix

@TristanSpeakEasy
TristanSpeakEasy requested a review from a team as a code owner November 17, 2026 11:07
@TristanSpeakEasy TristanSpeakEasy added enhancement New feature or request validation Related to validation logic labels Nov 17, 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.

All reported issues were addressed across 14 files

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

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

Comment thread asyncapi/operation.go Resolved
Comment thread asyncapi/message.go Resolved
Comment thread asyncapi/operation.go Resolved
Comment thread asyncapi/traits.go Resolved
Comment thread marshaller/syncer.go Resolved
Comment thread asyncapi/message.go Resolved
Comment thread asyncapi/reference.go Resolved
Comment thread asyncapi/README.md Resolved
Comment thread asyncapi/README.md 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.

All reported issues were addressed across 8 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

Comment thread marshaller/syncer.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 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 reference resolution, trait application and cross-object checks, plus a shared marshaller fix preserving explicit nulls. The resolver introduces file/URL loading with permissive defaults; that security boundary and the trait-merge contract need 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 15 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

Comment thread marshaller/syncer_null_test.go Resolved
Comment thread asyncapi/resolve_test.go Resolved
Comment thread asyncapi/checks_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 4 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 not auto-approve. Auto-approval blocked by 1 unresolved issue from previous reviews.

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

* 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
TristanSpeakEasy merged commit 04c5645 into feat/asyncapi-stage2-document-model Nov 18, 2026
2 checks passed
@TristanSpeakEasy
TristanSpeakEasy deleted the feat/asyncapi-stage3-references branch November 18, 2026 10:40
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

enhancement New feature or request validation Related to validation logic

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant