feat: add complete AsyncAPI 3.x document model with local validation and walking
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
asyncapiandasyncapi/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 asReferencedServerandReferencedMessage) for fields that accept an inline object or$ref, plusReferenceObjectfor fields that must be a$ref(operationchannel/messages, channelservers, replychannel/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,
bindingVersionis a string) but not protocol-specific fields. - Local validation covering:
- required fields
send/receiveactions- 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-propertiesrule 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
Validnow 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 awarning, so callers can tell "not checked" apart from "invalid" without every real document showing warnings.ros2counts as known from 3.1 onwards and as unknown in 3.0. This is the only version-specific difference. address: nullis treated the same as a missing address (unknown at design time). The public model usesnilfor both, andcore.Channel.SyncChangesputs an authoredaddress: nullback when writing the document so it round-trips unchanged.- Leaving operation
messagesout givesnil(all of the channel's messages), andmessages: []gives an empty slice (no messages). Both round-trip unchanged. OperationTraitmodelsreply. The spec's prose allows any operation field exceptaction,channel,messagesandtraits, even though its field table leavesreplyout.- I kept
TagandExternalDocumentationin the Stage 1 style (an optionalReffield on the object) rather than moving them to the genericReference.ExternalDocumentationlives 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 cipasses 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
ResolveAllReferencesloads 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
messageslists mean no messages.
Arazzo source validation
LoadSourceDescriptionsnow loads AsyncAPI sources and detects them from content whentypeis omitted.- Arazzo steps targeting AsyncAPI sources check
operationIdandchannelPathtargets exist, headers sent are declared by the target's messages, andcorrelationIdis only used with messages that declare one.
CLI
- New
openapi asyncapi validatecommand 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.