How to Validate an AsyncAPI Document in JSON

Most developers know OpenAPI, the format for describing request-and-response APIs. AsyncAPI is its counterpart for event-driven systems: instead of endpoints that you call, it describes channels that carry messages, operations that publish or subscribe to them, and the message shapes that travel across them. A team building on message brokers, websockets or event streams needs that description to be right, because code generators, documentation tools and other teams all read the same document. A single structural mistake, such as a missing info block or a malformed channel, can break every tool downstream. The AsyncAPI Validator and Viewer checks an AsyncAPI document pasted as JSON and shows its channels, so you can catch those mistakes before you share the file.

The idea behind AsyncAPI is worth understanding before the validation details. A channel is a named address where messages flow, such as user/signedup. An operation on a channel is either a publish, meaning a sender puts a message there, or a subscribe, meaning a receiver listens there. Each operation carries a message, and each message has a payload with a defined shape. The document also carries an info block with its title and version, and an asyncapi field stating which version of the specification it follows. Validation is mostly structural: it checks that the required pieces exist, that they have the expected types, and that references between them make sense. It does not prove that your event design is good, only that the document is well formed.

How the tool works

You paste an AsyncAPI document as JSON, and the tool reports errors and lists the channels it found. Everything runs in your browser, so the document never leaves your device, which matters when an API description contains internal channel names or payload fields you would rather not upload. One scope limit is important and stated on the tool itself: it parses JSON only. If your document is written in YAML, you need to convert it to JSON first before pasting it in. That is a real constraint, but it is also an honest one. A validator that claimed to parse YAML while only half handling it would produce worse outcomes than one that tells you plainly to convert first.

The viewer side matters as much as the error list. A long AsyncAPI document is hard to read as raw text, and a channel list gives you a quick map of the system: which channels exist, and which operations sit on each. When you are reviewing someone else's document, that map is often the fastest way to spot a missing channel, a duplicated name or an operation attached to the wrong place. Validation plus a readable overview is a better review workflow than either alone.

A worked example

Consider a small sample document. It declares asyncapi version 2.6.0, an info block naming the API "User API" at version 1.0.0, and a single channel called user/signedup with a publish operation carrying a message named userSignedUp. Pasted into the validator, this document returns zero errors and one channel. That result tells you two things: the structure is sound, and the document describes exactly one event flow. Both facts are worth confirming, because a document that validates but describes three channels when you expected one has a different kind of problem, a design problem rather than a syntax problem.

Now remove the info block. The validator reports an error naming info, because the specification requires it. That is the most useful kind of validation error: it names the missing piece rather than failing silently or producing a vague message. The fix is equally direct, which is to restore the info block with a title and version. The same pattern applies to other required pieces. If a channel entry is malformed, the error should point at the channel. If an operation is missing its message, the error should say so. When you read validation output, always fix the first error first and re-validate, because one structural break can cascade into several secondary messages that disappear once the root problem is fixed.

Common mistakes

The most common mistake is confusing AsyncAPI versions. Fields that are valid in one version may be renamed or restructured in another, so a document copied from an example written for a different version can fail in confusing ways. Always check the asyncapi field at the top of your document against the examples you are copying from. A second mistake is writing YAML and pasting it into a JSON-only validator, then concluding the document is broken when only the format is wrong. Convert YAML to JSON first, and validate the converted result.

A third mistake is describing operations from the wrong perspective. In AsyncAPI, publish and subscribe are described from the application's point of view, and teams sometimes swap them, describing what the other side does rather than what their own application does. The document still validates, because the structure is fine, but every consumer reads it backwards. A fourth mistake is leaving message payloads vague. A message with no payload definition validates in some shapes but gives code generators and consumers nothing to work with, which defeats much of the purpose of writing the document at all.

Honest limitations

A structural validator checks form, not meaning. It cannot tell you whether user/signedup is a sensible channel name, whether your payload design will evolve cleanly, or whether your events carry too much or too little data. It cannot reach your message broker to confirm that the channels actually exist, and it cannot verify that producers and consumers agree on the payload in practice. It also handles JSON only, so YAML documents need a conversion step, and very large documents may be slower to review in a browser pane than in a dedicated editor. Treat validation as the first gate, not the whole review: a document that passes still deserves a human read for design sense.

Closing

AsyncAPI documents are contracts between teams, and contracts deserve a check before they are signed. Validate the JSON, confirm the channel list matches what you intended, and fix the first error first. A document with zero errors and exactly the channels you expected is a solid starting point for documentation and code generation. For neighbouring work, the JSON Schema Validator checks payload shapes and the OpenAPI Specification Diff Checker compares API descriptions, while HTTP Status Codes Explained for Troubleshooting covers the request-and-response side of API work.