asyncapi

README

go-asyncapi

Loads AsyncAPI 3 documents in Go. Point it at a YAML or JSON file and you get servers, channels, operations and messages as plain structs, with every $ref followed, across files too, and every trait merged in. gen-asyncapi is built on it.

Install

go get github.com/psyb0t/go-asyncapi

Usage

document, err := asyncapi.Load("asyncapi.yaml")
if err != nil {
	return err
}

for _, server := range document.Servers {
	fmt.Println(server.Name, server.URL()) // production wss://eu.example.com:443/v2/ws
}

for _, operation := range document.Operations {
	for _, message := range operation.Messages {
		fmt.Println(operation.Action, operation.Channel.Address, message.Name)
	}
}

Everything comes back in the order the document lists it. A message used by several channels is one *Message, so you can compare pointers. Traits are already merged: a trait fills what the message or operation leaves out and never overrides what it sets.

Schemas

Payload and header schemas stay as they are in the document, as *asyncapi.Object trees that keep key order. Object.Get, Object.String and Object.Object read them, and the document's Resolver follows the $refs inside:

message := document.Messages[0]

schema, at, err := document.Resolver.Deref(message.Payload, message.PayloadAt)
if err != nil {
	return err
}

object, ok := schema.(*asyncapi.Object) // false for a `true`/`false` schema
if !ok {
	return nil
}

properties := object.Object("properties") // nil without a properties keyword
if properties == nil {
	return nil
}

for _, name := range properties.Keys {
	fmt.Println(name)
}

Deref returns the resolved value and its Location, a file plus a JSON pointer. Two $refs that land on the same Location point at the same schema, so it works as a map key when you need each schema once.

Payloads in AsyncAPI, JSON Schema or OpenAPI format load as schemas. Any other schemaFormat, such as Avro, leaves Payload nil and names the format in UnsupportedFormat.

What it reads

• servers with variables, enums and defaults, plus URL() and URLTemplate()
• channels with addresses, parameters and messages; a null address stays empty
• operations with action, channel, messages and replies, including dynamic reply addresses
• messages with payload, headers, correlationId, content type (falling back to defaultContentType), bindings and the deprecated flag
• components, with every $ref into them resolved, and components.schemas listed in order
• local and relative-file $refs, chains included; a cycle or a remote URL is an error

Errors wrap ctxerrors/commerr sentinels, so errors.Is(err, commerr.ErrNotFound) catches a dangling $ref and commerr.ErrInvalidValue catches a malformed section.

Agent integrations

The skill teaches a coding agent how to use go-asyncapi when it writes Go. It works in any agent that reads .agents/skills/, and installs natively in the clients below.

Claude Code

claude plugin marketplace add psyb0t/agents
claude plugin install go-asyncapi@psyb0t

Codex

codex plugin marketplace add psyb0t/agents
codex plugin add go-asyncapi@psyb0t

Codex also picks the skill up with no install in any checkout of this repo.

OpenClaw

The skill is published to ClawHub on every release:

openclaw skills install @psyb0t/go-asyncapi

Development

Everything runs in the Dockerfile.dev image. You need Docker and Make.

make help           # list targets
make lint           # shellcheck, shfmt, go fix, golangci-lint
make test-coverage  # go test -race with a 90% coverage gate
make sec            # gitleaks, govulncheck, semgrep

License

MIT.

Documentation

Overview

Package asyncapi loads AsyncAPI 3 documents. Load follows $refs across files, merges message and operation traits, and returns servers, channels, operations and messages in document order. Schemas stay as ordered Object trees, and the Document's Resolver dereferences the $refs inside them.

Index

• type Action
• type Channel
• type Document
  • func Load(path string) (*Document, error)
• type Located
• type Location
  • func (l Location) Child(key string) Location
  • func (l Location) LastToken() string
  • func (l Location) String() string
• type Message
• type Object
  • func (o *Object) Get(key string) (any, bool)
  • func (o *Object) Object(key string) *Object
  • func (o *Object) String(key string) string
• type Operation
• type Parameter
• type Reply
• type Resolver
  • func NewResolver() *Resolver
  • func (r *Resolver) Deref(value any, location Location) (any, Location, error)
  • func (r *Resolver) Document(path string) (any, error)
  • func (r *Resolver) Lookup(location Location) (any, error)
• type SchemaComponent
• type Server
  • func (s *Server) URL() string
  • func (s *Server) URLTemplate() string
• type ServerVariable

Types

type Action

type Action string

Action is what an operation does: send or receive.

const (
	// ActionSend marks an operation the application sends.
	ActionSend Action = "send"
	// ActionReceive marks an operation the application receives.
	ActionReceive Action = "receive"
)

Operation actions.

type Channel

type Channel struct {
	Name        string
	Address     string
	Description string
	Parameters  []*Parameter
	Messages    []*Message
	Location    Location
}

Channel is one entry of the channels object.

type Document

type Document struct {
	AsyncAPIVersion string
	Title           string
	Version         string
	Description     string
	// DefaultContentType applies to messages that set no contentType.
	DefaultContentType string
	Servers            []*Server
	Channels           []*Channel
	Operations         []*Operation
	// Messages lists every distinct message, in first-seen order.
	Messages []*Message
	// ComponentSchemas lists components.schemas in document order.
	ComponentSchemas []SchemaComponent

	// Resolver holds every loaded file and dereferences $refs inside schemas.
	Resolver *Resolver
	// Root is the location of the document's top level.
	Root Location
	// contains filtered or unexported fields
}

Document is a loaded AsyncAPI 3 document.

func Load

func Load(path string) (*Document, error)

Load reads the AsyncAPI document at path and every document it references.

type Located

type Located struct {
	Value any
	At    Location
}

Located is a value merged in from a trait, together with where it was defined, so $refs inside it still resolve against the trait's document.

type Location

type Location struct {
	File    string
	Pointer string
}

Location identifies a value inside a loaded document by file and JSON pointer. Two $refs that resolve to the same Location point at the same value, so it works as a map key for deduplicating schemas.

func (Location) Child

func (l Location) Child(key string) Location

Child returns the location of key inside location.

func (Location) LastToken

func (l Location) LastToken() string

LastToken returns the unescaped final JSON pointer token, or "" at the root.

func (Location) String

func (l Location) String() string

String renders the location as a JSON reference, file#/pointer.

type Message

type Message struct {
	// Key is the components.messages key, or channel_message for an inline
	// message. Keys are unique within a document.
	Key         string
	Name        string
	Title       string
	Summary     string
	Description string
	// ContentType is the message's contentType, or the document's
	// defaultContentType.
	ContentType string
	Deprecated  bool
	// Payload is the payload schema as loaded, usually an *Object. It is nil
	// when the message has no payload or its schemaFormat is not AsyncAPI,
	// JSON Schema or OpenAPI; UnsupportedFormat names that format.
	Payload any
	// PayloadAt is where Payload sits, for resolving $refs inside it.
	PayloadAt         Location
	UnsupportedFormat string
	// Headers is the application headers schema, or nil.
	Headers   any
	HeadersAt Location
	// CorrelationIDLocation is the runtime expression of the correlationId,
	// such as "$message.payload#/id", or "".
	CorrelationIDLocation string
	// Bindings is the protocol bindings object after traits are merged in,
	// or nil.
	Bindings *Object
	Location Location
}

Message is a message definition. Messages referenced from several channels are the same *Message.

type Object

type Object struct {
	Keys   []string
	Values map[string]any
}

Object is a JSON/YAML mapping that keeps its keys in the order the document lists them. Values are string, int64, float64, bool, nil, []any or *Object.

func (*Object) Get

func (o *Object) Get(key string) (any, bool)

Get returns the value stored under key and whether it exists.

func (*Object) Object

func (o *Object) Object(key string) *Object

Object returns the mapping stored under key, or nil.

func (*Object) String

func (o *Object) String(key string) string

String returns the string stored under key, or "" when it is missing or not a string.

type Operation

type Operation struct {
	Name        string
	Action      Action
	Summary     string
	Description string
	Channel     *Channel
	Messages    []*Message
	Reply       *Reply
}

Operation is one entry of the operations object.

type Parameter

type Parameter struct {
	Name        string
	Description string
	Enum        []string
	Default     string
}

Parameter is a channel address parameter.

type Reply

type Reply struct {
	Channel  *Channel
	Messages []*Message
	// AddressLocation is the runtime expression of a dynamic reply address,
	// such as "$message.header#/replyTo", or "".
	AddressLocation string
}

Reply is the expected reply to an operation.

type Resolver

type Resolver struct {
	// contains filtered or unexported fields
}

Resolver loads documents and follows $ref values between and inside them.

func NewResolver

func NewResolver() *Resolver

NewResolver returns a resolver with no documents loaded.

func (*Resolver) Deref

func (r *Resolver) Deref(value any, location Location) (any, Location, error)

Deref follows $ref chains starting at value, which lives at location. It returns the first value that is not a reference and where that value lives.

func (*Resolver) Document

func (r *Resolver) Document(path string) (any, error)

Document returns the root value of the document at path, loading and caching it on first use. Both JSON and YAML documents are accepted.

func (*Resolver) Lookup

func (r *Resolver) Lookup(location Location) (any, error)

Lookup returns the raw value at location without following references.

type SchemaComponent

type SchemaComponent struct {
	Name  string
	Value any
	At    Location
}

SchemaComponent is one components.schemas entry.

type Server

type Server struct {
	Name            string
	Host            string
	Pathname        string
	Protocol        string
	ProtocolVersion string
	Description     string
	Variables       []*ServerVariable
}

Server is one entry of the servers object.

func (*Server) URL

func (s *Server) URL() string

URL returns the server URL with every variable set to its default.

func (*Server) URLTemplate

func (s *Server) URLTemplate() string

URLTemplate returns protocol://host/pathname with variables unfilled.

type ServerVariable

type ServerVariable struct {
	Name        string
	Default     string
	Enum        []string
	Description string
}

ServerVariable is a {name} placeholder in a server's host or pathname.