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

Merged
TR
3d ago
+13515-148

Stacked on #321. Review that first; this PR's base is its branch.

Why

Stage 1 only modelled the AsyncAPI root and info, and kept servers, channels, operations and components as raw YAML. So callers couldn't read or edit most of a document, and validation couldn't look inside it. This PR models the whole AsyncAPI 3.x document. Version handling, the AsyncAPI JSON Schema package and the overall approach are unchanged from Stage 1.

What changed

  • Typed models for every 3.x object in asyncapi and asyncapi/core: servers, server variables, channels, parameters, operations, operation traits, replies, reply addresses, messages, message traits, message examples, correlation IDs, security schemes, OAuth flows, bindings and all 19 component maps. Each has nil-safe getters and factory registrations.
  • References: a generic Reference[T, V, C] (aliases such as ReferencedServer and ReferencedMessage) for fields that accept an inline object or $ref, plus ReferenceObject for fields that must be a $ref (operation channel/messages, channel servers, reply channel/messages). References are parsed and syntax-checked but not resolved yet; that's Stage 3.
  • Bindings keep each protocol's contents as raw YAML. We check the shape (each binding is an object, bindingVersion is a string) but not protocol-specific fields.
  • Local validation covering:
    • required fields
    • send/receive actions
    • server host and pathname variables, and channel address parameters, in both directions
    • runtime expressions ($message.header#/..., $message.payload#/...)
    • security scheme variants and OAuth flow URLs
    • message headers being object schemas
    • example shape
    • component and server key patterns
    • duplicate tags
  • New validation-unknown-properties rule constant, with the same ID OpenAPI's index already emits. Unknown fields produce a warning and are kept in the document.
  • asyncapi.Walk, following the Arazzo walk API. It visits reference wrappers and then their inline objects, in document order. It stops when the caller breaks out of the loop or the context is cancelled, and never reads files or makes network requests.

Review notes

  • Valid now means no error-severity diagnostics. Warnings and hints, such as unknown fields or content we keep but don't check, no longer make a document invalid.
  • Bindings for known protocols produce a hint, and unknown protocols a warning, so callers can tell "not checked" apart from "invalid" without every real document showing warnings. ros2 counts as known from 3.1 onwards and as unknown in 3.0. This is the only version-specific difference.
  • address: null is treated the same as a missing address (unknown at design time). The public model uses nil for both, and core.Channel.SyncChanges puts an authored address: null back when writing the document so it round-trips unchanged.
  • Leaving operation messages out gives nil (all of the channel's messages), and messages: [] gives an empty slice (no messages). Both round-trip unchanged.
  • OperationTrait models reply. The spec's prose allows any operation field except action, channel, messages and traits, even though its field table leaves reply out.
  • I kept Tag and ExternalDocumentation in the Stage 1 style (an optional Ref field on the object) rather than moving them to the generic Reference. ExternalDocumentation lives in the schema package and is shared with schemas, so it can't depend on the document package's reference type.
  • Checks that need references followed are deferred to Stage 3: operation messages belonging to the operation's channel, which objects a reference may point to (servers, channels and so on), traits, and reply address versus channel address.

Testing

  • New 3.1 fixture using every object (asyncapi/testdata/complete-3.1.yaml) and a 3.0 streetlights fixture. Both parse with no errors and round-trip byte-for-byte in YAML. The 3.1 fixture also round-trips as JSON.
  • Validation tables for servers, channels, operations, messages, security schemes, bindings and components.
  • Mutation tests for each object type. Each checks that only the edited value changes, that scalar styles are kept, and that the edited document is still valid.
  • Walk tests: JSON pointer locations and visit order, each location visited once, stopping early, cancelled context, and a nil document.
  • mise ci passes locally (format, lint, tests, build, CLI integration).

Summary by cubic

Adds reference resolution, trait application, cross-object checks, and Arazzo source validation to the complete AsyncAPI 3.x document model, plus a new openapi asyncapi validate CLI command.

Resolution and traits

  • ResolveAllReferences loads referenced files and URLs, applies operation and message traits, and reports each trait-merged field at its contributing source.
  • Checks needing referenced objects now run: root operation channels must point to root channels, operation messages must belong to their channel, and reply addresses are validated against channel addresses.
  • Unresolvable references or missing targets produce errors; empty operation messages lists mean no messages.

Arazzo source validation

  • LoadSourceDescriptions now loads AsyncAPI sources and detects them from content when type is omitted.
  • Arazzo steps targeting AsyncAPI sources check operationId and channelPath targets exist, headers sent are declared by the target's messages, and correlationId is only used with messages that declare one.

CLI

  • New openapi asyncapi validate command with local and resolve-against-references modes, reporting unsupported versions such as 2.x.

Also updates the marshaller to keep authored null values when syncing unset fields, so address: null round-trips unchanged.