asyncapi

package
v1.28.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: MIT Imports: 32 Imported by: 0

README

AsyncAPI Parser

An API for working with AsyncAPI 3.x documents including: read, walk, create, mutate, resolve and validate.

[!NOTE] This package is new, so its API may still change in minor releases.

To validate a document from the command line, use openapi asyncapi validate.

Supported versions

AsyncAPI version Support
3.1.x Read, write, walk, resolve and validate. Adds ros2 bindings.
3.0.x Read, write, walk, resolve and validate.

Any patch release of a supported minor version is accepted. AsyncAPI 2.x documents are reported as unsupported. Where the specification text and its JSON Schema disagree, validation follows the specification text.

Usage

Read, edit, validate and write a document

Unmarshal returns a fatal error only when the document can't be read or parsed. Problems with its content are returned as validation errors, with error, warning or hint severity.

doc, validationErrs, err := asyncapi.Unmarshal(ctx, f)
if err != nil {
	return err
}
for _, vErr := range validationErrs {
	fmt.Println(vErr)
}

doc.Info.Title = "Order events"

if err := asyncapi.Marshal(ctx, doc, os.Stdout); err != nil {
	return err
}

Unmarshal, Validate and Walk never read files or make network requests. They check each object locally and leave references unresolved.

Resolve references

ResolveAllReferences is the explicit step that loads referenced resources. It follows chains of references, applies traits and runs the checks that need referenced objects, such as whether an operation's messages belong to its channel.

validationErrs, err := doc.ResolveAllReferences(ctx, asyncapi.ResolveAllOptions{
	AsyncAPILocation: "/specs/orders.yaml", // relative references resolve against this
	VirtualFS:        fsys,                 // optional, defaults to the local file system
	HTTPClient:       client,               // optional, defaults to http.DefaultClient
})
if err != nil {
	return err // only for failures that stop resolution, such as a cancelled context
}
for _, vErr := range validationErrs {
	fmt.Println(vErr)
}

operation := doc.Operations.GetOrZero("placeOrder").GetObject()
fmt.Println(operation.Channel.GetChannel().GetAddress())
for _, message := range operation.Messages {
	fmt.Println(message.GetMessage().GetName())
}
  • Reference problems (missing or wrong-kind targets, cycles, disallowed external references) are returned as validation errors at the referring $ref. Diagnostics found in other documents set DocumentLocation.
  • Set DisableExternalRefs to keep resolution within the document. Without AsyncAPILocation, relative references to other documents are reported rather than resolved against the working directory.
  • The default HTTP client isn't a sandbox. If a document might come from someone you don't trust, provide a client and file system that only allow the locations you expect.
  • Each call rebuilds resolution from the current document, so edits are picked up. Resolution never changes the document, and references stay as written.

Effective operations and messages

After resolution, GetEffective returns an operation or message with its traits applied, as a separate snapshot. An operation or message without traits is returned as itself.

effective := operation.GetEffective()
fmt.Println(effective.GetSummary())

// index is the position in Traits, or -1 if the operation sets the field itself.
if index, ok := operation.GetTraitSource("summary"); ok {
	fmt.Println("summary comes from", index)
}

Traits are applied with JSON Merge Patch in declaration order, and the object's own values win:

effective = {}
for each trait: effective = MergePatch(effective, trait)
effective = MergePatch(effective, object without traits)

So objects merge recursively, later traits win over earlier ones, arrays are replaced and null deletes a value, including the object's own null deleting an inherited value. Fields a trait must not set (action, channel, messages and traits for operations, payload and traits for messages) are reported by Validate and ignored when merging. Diagnostics that only appear once traits are applied are reported by ResolveAllReferences.

Walk a document

for item := range asyncapi.Walk(ctx, doc) {
	err := item.Match(asyncapi.Matcher{
		Operation: func(o *asyncapi.Operation) error {
			fmt.Println(item.Location.ToJSONPointer(), o.GetAction())
			return nil
		},
	})
	if err != nil {
		return err
	}
}

Walking visits what was written, in document order. It doesn't follow references, even after they're resolved.

Support limits

Area Support
Document objects All AsyncAPI 3.x objects are modelled, with getters, editing and round-tripping. Unknown properties are kept and reported as warnings.
References All Reference Objects are resolved, within the document and across files and URLs, including chains and relative references between documents.
Schemas Native AsyncAPI and JSON Schema Draft 07 schemas are parsed and validated. A schema $ref and a Multi Format Schema Object whose schema is a $ref are resolved. $refs nested inside schemas aren't resolved yet.
Other schema formats Avro, RAML, OpenAPI and other formats are kept unchanged and reported as not validated. A $ref to a JSON or YAML resource in those formats is loaded and kept unchanged. References to Protocol Buffers text resources aren't loaded.
Bindings Kept unchanged for every protocol. Only their shape and bindingVersion are checked; protocol-specific fields aren't validated.
Effective views References in an effective view are resolved when all of its traits come from the same document as the object.
Message instances Examples and runtime messages aren't validated against their schemas.

Documentation

Overview

Package asyncapi provides an API for working with AsyncAPI 3.x documents including reading, creating, mutating, walking and validating them.

The package supports the AsyncAPI 3.0 and 3.1 minor lines and models the complete 3.x document. Unmarshal and Validate check each object locally without reading files or making network requests. ResolveAllReferences is the explicit step that loads referenced resources, applies traits and runs the checks that need referenced objects. Protocol bindings and schemas in formats other than AsyncAPI and JSON Schema are preserved unchanged but their contents are not validated. See the package README for the full list of support limits.

Index

Constants

Version is the latest version of the AsyncAPI Specification that this package supports, used for new documents.

Variables

View Source
var ErrExternalReferencesDisabled = errors.New("external references are disabled")

ErrExternalReferencesDisabled is wrapped by the diagnostics reported for references to other documents when ResolveAllOptions.DisableExternalRefs is set, so callers can tell references that weren't followed apart from broken ones with errors.Is.

Functions

func IsSupportedVersion

func IsSupportedVersion(v string) bool

IsSupportedVersion returns true if the provided AsyncAPI version string is valid and belongs to a supported minor version.

func Marshal

func Marshal(ctx context.Context, asyncAPI *AsyncAPI, w io.Writer) error

Marshal will marshal the provided AsyncAPI document to the provided io.Writer, syncing any changes first.

func SupportedMinorVersions

func SupportedMinorVersions() []string

SupportedMinorVersions returns a copy of the `major.minor` AsyncAPI Specification versions supported by this package. Any patch release (and permitted suffix) of a supported minor version is accepted.

func Walk

func Walk(ctx context.Context, asyncAPI *AsyncAPI) iter.Seq[WalkItem]

Walk returns an iterator that yields an item for each model in the AsyncAPI document, in document order. Callers can break out of the loop at any time to stop walking. Walking never reads files or makes network requests.

Types

type AsyncAPI

type AsyncAPI struct {
	marshaller.Model[core.AsyncAPI]

	// AsyncAPI is the version of the AsyncAPI Specification the document conforms to.
	AsyncAPI string
	// ID is the identifier of the application the document is defining. It must be a URI.
	ID *string
	// Info provides metadata about the API.
	Info Info
	// Servers are the connection details of servers, keyed by server name.
	Servers *sequencedmap.Map[string, *ReferencedServer]
	// DefaultContentType is the default content type used to encode and decode message payloads.
	DefaultContentType *string
	// Channels are the channels used by the application, keyed by channel ID. A channel ID is not its address.
	Channels *sequencedmap.Map[string, *ReferencedChannel]
	// Operations are the operations the application implements, keyed by operation ID.
	Operations *sequencedmap.Map[string, *ReferencedOperation]
	// Components hold reusable objects.
	Components *Components
	// Extensions provides a list of extensions to the AsyncAPI Object.
	Extensions *extensions.Extensions
	// contains filtered or unexported fields
}

AsyncAPI is the root object of an AsyncAPI document.

func NewAsyncAPI

func NewAsyncAPI() *AsyncAPI

NewAsyncAPI creates a new AsyncAPI document for the latest supported version.

func Unmarshal

func Unmarshal(ctx context.Context, doc io.Reader, opts ...Option[UnmarshalOptions]) (*AsyncAPI, []error, error)

Unmarshal will unmarshal and validate an AsyncAPI document from the provided io.Reader. The returned error is reserved for failures to read or parse the document, while problems with its content are returned as validation errors. Validation can be skipped with WithSkipValidation.

Validation does not read any files or make any network requests.

func (*AsyncAPI) GetAsyncAPI

func (a *AsyncAPI) GetAsyncAPI() string

GetAsyncAPI returns the AsyncAPI Specification version of the document.

func (*AsyncAPI) GetChannels

func (a *AsyncAPI) GetChannels() *sequencedmap.Map[string, *ReferencedChannel]

GetChannels returns the channels, or nil if not set.

func (*AsyncAPI) GetComponents

func (a *AsyncAPI) GetComponents() *Components

GetComponents returns the components, or nil if not set.

func (*AsyncAPI) GetDefaultContentType

func (a *AsyncAPI) GetDefaultContentType() string

GetDefaultContentType returns the default content type, or an empty string if not set.

func (*AsyncAPI) GetExtensions

func (a *AsyncAPI) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions of the document. Returns an empty extensions map if not set.

func (*AsyncAPI) GetID

func (a *AsyncAPI) GetID() string

GetID returns the application identifier, or an empty string if not set.

func (*AsyncAPI) GetInfo

func (a *AsyncAPI) GetInfo() *Info

GetInfo returns the Info Object, or nil if the document is nil.

func (*AsyncAPI) GetOperations

func (a *AsyncAPI) GetOperations() *sequencedmap.Map[string, *ReferencedOperation]

GetOperations returns the operations, or nil if not set.

func (*AsyncAPI) GetResolvedExternalDocs

func (a *AsyncAPI) GetResolvedExternalDocs(docs *ExternalDocumentation) *ExternalDocumentation

GetResolvedExternalDocs returns the external documentation itself, or for a Reference Object the documentation it resolved to in the last call to ResolveAllReferences. Returns nil for an unresolved Reference Object.

func (*AsyncAPI) GetResolvedSchema

func (a *AsyncAPI) GetResolvedSchema(schema *jsonschema.SchemaUnion) *ResolvedSchema

GetResolvedSchema returns the resolved target of a schema Reference Object, either a native schema `$ref` or a Multi Format Schema Object whose `schema` is a Reference Object, from the last call to ResolveAllReferences. Returns nil if the schema isn't a reference or hasn't been resolved.

func (*AsyncAPI) GetServers

func (a *AsyncAPI) GetServers() *sequencedmap.Map[string, *ReferencedServer]

GetServers returns the servers, or nil if not set.

func (*AsyncAPI) ResolveAllReferences

func (a *AsyncAPI) ResolveAllReferences(ctx context.Context, opts ResolveAllOptions) ([]error, error)

ResolveAllReferences resolves every reference in the document, applies traits and runs the checks that need referenced objects. It is the only part of this package that reads files or makes network requests, and only does so for references the document contains, using the provided options.

Each call rebuilds the resolution state from the current document, so edits made since an earlier call are reflected and no stale targets are returned. Resolution doesn't change the authored document: references stay as written and are not bundled.

Problems with references, such as missing or wrong-kind targets, cycles, references to other documents that aren't allowed and diagnostics from loaded documents, are returned as validation errors. The returned error is reserved for failures that stop resolution, such as a cancelled context.

func (*AsyncAPI) Sync

func (a *AsyncAPI) Sync(ctx context.Context) error

Sync will sync any changes made to the AsyncAPI document models back to the core models.

func (*AsyncAPI) Validate

func (a *AsyncAPI) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the AsyncAPI document against the AsyncAPI Specification.

type Bindings

type Bindings struct {
	marshaller.Model[core.Bindings]
	*sequencedmap.Map[string, values.Value]

	// Extensions provides a list of extensions to the Bindings Object.
	Extensions *extensions.Extensions
}

Bindings holds protocol-specific information for a server, channel, operation or message, keyed by protocol name.

Each protocol binding is kept as a raw value, so bindings for any protocol (and any binding version) are preserved unchanged. Only the shape of each binding is validated; protocol-specific rules are not checked.

func NewBindings

func NewBindings() *Bindings

NewBindings creates a new Bindings object with the embedded map initialized.

func (*Bindings) All

func (b *Bindings) All() iter.Seq2[string, values.Value]

All returns an iterator over the protocol bindings. nil safe.

func (*Bindings) GetBindingVersion

func (b *Bindings) GetBindingVersion(protocol string) string

GetBindingVersion returns the `bindingVersion` of the binding for the provided protocol, or an empty string if the binding or its version is not set.

func (*Bindings) GetExtensions

func (b *Bindings) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Bindings) Len

func (b *Bindings) Len() int

Len returns the number of protocol bindings. nil safe.

func (*Bindings) Validate

func (b *Bindings) Validate(_ context.Context, opts ...validation.Option) []error

Validate validates the shape of each protocol binding. Bindings for unknown protocols produce a warning and bindings for known protocols a hint, as their protocol-specific contents are preserved but not validated.

type Channel

type Channel struct {
	marshaller.Model[core.Channel]

	// Address is the address of the channel, e.g. a topic or queue name. It may include Channel Address Expressions
	// such as `users.{userId}`. A nil address means the address is unknown or dynamic, which is also the case when the
	// document sets it to null explicitly.
	Address *string
	// Messages are the messages that can be sent on this channel, keyed by message ID.
	Messages *sequencedmap.Map[string, *ReferencedMessage]
	// Title is a human-friendly title for the channel.
	Title *string
	// Summary is a short summary of the channel.
	Summary *string
	// Description is a description of the channel. May contain CommonMark syntax.
	Description *string
	// Servers are references to the root servers this channel is available on. When empty, it is available on all servers.
	Servers []*ReferenceObject
	// Parameters are the parameters included in the channel address.
	Parameters *sequencedmap.Map[string, *ReferencedParameter]
	// Tags are used for logical grouping and categorization of channels.
	Tags []*Tag
	// ExternalDocs is additional external documentation for this channel.
	ExternalDocs *ExternalDocumentation
	// Bindings are protocol-specific definitions for the channel.
	Bindings *ReferencedBindings
	// Extensions provides a list of extensions to the Channel Object.
	Extensions *extensions.Extensions
}

Channel describes a shared communication channel.

func (*Channel) GetAddress

func (c *Channel) GetAddress() string

GetAddress returns the address, or an empty string if the address is unknown (absent or null).

func (*Channel) GetBindings

func (c *Channel) GetBindings() *ReferencedBindings

GetBindings returns the channel bindings, or nil if not set.

func (*Channel) GetDescription

func (c *Channel) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Channel) GetExtensions

func (c *Channel) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Channel) GetExternalDocs

func (c *Channel) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*Channel) GetMessages

func (c *Channel) GetMessages() *sequencedmap.Map[string, *ReferencedMessage]

GetMessages returns the messages, or nil if not set.

func (*Channel) GetParameters

func (c *Channel) GetParameters() *sequencedmap.Map[string, *ReferencedParameter]

GetParameters returns the parameters, or nil if not set.

func (*Channel) GetServers

func (c *Channel) GetServers() []*ReferenceObject

GetServers returns the server references, or nil if not set.

func (*Channel) GetSummary

func (c *Channel) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*Channel) GetTags

func (c *Channel) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*Channel) GetTitle

func (c *Channel) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*Channel) Validate

func (c *Channel) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Channel Object against the AsyncAPI Specification.

type Components

type Components struct {
	marshaller.Model[core.Components]

	// Schemas are reusable schemas, either native AsyncAPI schemas or Multi Format Schema Objects.
	Schemas *sequencedmap.Map[string, *jsonschema.SchemaUnion]
	// Servers are reusable Server Objects.
	Servers *sequencedmap.Map[string, *ReferencedServer]
	// Channels are reusable Channel Objects.
	Channels *sequencedmap.Map[string, *ReferencedChannel]
	// Operations are reusable Operation Objects.
	Operations *sequencedmap.Map[string, *ReferencedOperation]
	// Messages are reusable Message Objects.
	Messages *sequencedmap.Map[string, *ReferencedMessage]
	// SecuritySchemes are reusable Security Scheme Objects.
	SecuritySchemes *sequencedmap.Map[string, *ReferencedSecurityScheme]
	// ServerVariables are reusable Server Variable Objects.
	ServerVariables *sequencedmap.Map[string, *ReferencedServerVariable]
	// Parameters are reusable Parameter Objects.
	Parameters *sequencedmap.Map[string, *ReferencedParameter]
	// CorrelationIDs are reusable Correlation ID Objects.
	CorrelationIDs *sequencedmap.Map[string, *ReferencedCorrelationID]
	// Replies are reusable Operation Reply Objects.
	Replies *sequencedmap.Map[string, *ReferencedOperationReply]
	// ReplyAddresses are reusable Operation Reply Address Objects.
	ReplyAddresses *sequencedmap.Map[string, *ReferencedOperationReplyAddress]
	// ExternalDocs are reusable External Documentation Objects.
	ExternalDocs *sequencedmap.Map[string, *ExternalDocumentation]
	// Tags are reusable Tag Objects.
	Tags *sequencedmap.Map[string, *Tag]
	// OperationTraits are reusable Operation Trait Objects.
	OperationTraits *sequencedmap.Map[string, *ReferencedOperationTrait]
	// MessageTraits are reusable Message Trait Objects.
	MessageTraits *sequencedmap.Map[string, *ReferencedMessageTrait]
	// ServerBindings are reusable Server Bindings Objects.
	ServerBindings *sequencedmap.Map[string, *ReferencedBindings]
	// ChannelBindings are reusable Channel Bindings Objects.
	ChannelBindings *sequencedmap.Map[string, *ReferencedBindings]
	// OperationBindings are reusable Operation Bindings Objects.
	OperationBindings *sequencedmap.Map[string, *ReferencedBindings]
	// MessageBindings are reusable Message Bindings Objects.
	MessageBindings *sequencedmap.Map[string, *ReferencedBindings]
	// Extensions provides a list of extensions to the Components Object.
	Extensions *extensions.Extensions
}

Components holds a set of reusable objects. Objects defined here have no effect unless they are referenced from outside the Components Object.

func (*Components) GetChannelBindings

func (c *Components) GetChannelBindings() *sequencedmap.Map[string, *ReferencedBindings]

GetChannelBindings returns the reusable channel bindings, or nil if not set.

func (*Components) GetChannels

func (c *Components) GetChannels() *sequencedmap.Map[string, *ReferencedChannel]

GetChannels returns the reusable channels, or nil if not set.

func (*Components) GetCorrelationIDs

func (c *Components) GetCorrelationIDs() *sequencedmap.Map[string, *ReferencedCorrelationID]

GetCorrelationIDs returns the reusable correlation IDs, or nil if not set.

func (*Components) GetExtensions

func (c *Components) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Components) GetExternalDocs

func (c *Components) GetExternalDocs() *sequencedmap.Map[string, *ExternalDocumentation]

GetExternalDocs returns the reusable external documentation, or nil if not set.

func (*Components) GetMessageBindings

func (c *Components) GetMessageBindings() *sequencedmap.Map[string, *ReferencedBindings]

GetMessageBindings returns the reusable message bindings, or nil if not set.

func (*Components) GetMessageTraits

func (c *Components) GetMessageTraits() *sequencedmap.Map[string, *ReferencedMessageTrait]

GetMessageTraits returns the reusable message traits, or nil if not set.

func (*Components) GetMessages

func (c *Components) GetMessages() *sequencedmap.Map[string, *ReferencedMessage]

GetMessages returns the reusable messages, or nil if not set.

func (*Components) GetOperationBindings

func (c *Components) GetOperationBindings() *sequencedmap.Map[string, *ReferencedBindings]

GetOperationBindings returns the reusable operation bindings, or nil if not set.

func (*Components) GetOperationTraits

func (c *Components) GetOperationTraits() *sequencedmap.Map[string, *ReferencedOperationTrait]

GetOperationTraits returns the reusable operation traits, or nil if not set.

func (*Components) GetOperations

func (c *Components) GetOperations() *sequencedmap.Map[string, *ReferencedOperation]

GetOperations returns the reusable operations, or nil if not set.

func (*Components) GetParameters

func (c *Components) GetParameters() *sequencedmap.Map[string, *ReferencedParameter]

GetParameters returns the reusable parameters, or nil if not set.

func (*Components) GetReplies

GetReplies returns the reusable replies, or nil if not set.

func (*Components) GetReplyAddresses

GetReplyAddresses returns the reusable reply addresses, or nil if not set.

func (*Components) GetSchemas

GetSchemas returns the reusable schemas, or nil if not set.

func (*Components) GetSecuritySchemes

func (c *Components) GetSecuritySchemes() *sequencedmap.Map[string, *ReferencedSecurityScheme]

GetSecuritySchemes returns the reusable security schemes, or nil if not set.

func (*Components) GetServerBindings

func (c *Components) GetServerBindings() *sequencedmap.Map[string, *ReferencedBindings]

GetServerBindings returns the reusable server bindings, or nil if not set.

func (*Components) GetServerVariables

func (c *Components) GetServerVariables() *sequencedmap.Map[string, *ReferencedServerVariable]

GetServerVariables returns the reusable server variables, or nil if not set.

func (*Components) GetServers

func (c *Components) GetServers() *sequencedmap.Map[string, *ReferencedServer]

GetServers returns the reusable servers, or nil if not set.

func (*Components) GetTags

func (c *Components) GetTags() *sequencedmap.Map[string, *Tag]

GetTags returns the reusable tags, or nil if not set.

func (*Components) Validate

func (c *Components) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Components Object against the AsyncAPI Specification.

type Contact

type Contact struct {
	marshaller.Model[core.Contact]

	// Name is the identifying name of the contact person or organization.
	Name *string
	// URL is the URL pointing to the contact information.
	URL *string
	// Email is the email address of the contact person or organization.
	Email *string
	// Extensions provides a list of extensions to the Contact Object.
	Extensions *extensions.Extensions
}

Contact is the contact information for the exposed API.

func (*Contact) GetEmail

func (c *Contact) GetEmail() string

GetEmail returns the email address, or an empty string if not set.

func (*Contact) GetExtensions

func (c *Contact) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Contact) GetName

func (c *Contact) GetName() string

GetName returns the name, or an empty string if not set.

func (*Contact) GetURL

func (c *Contact) GetURL() string

GetURL returns the URL, or an empty string if not set.

func (*Contact) Validate

func (c *Contact) Validate(_ context.Context, _ ...validation.Option) []error

Validate will validate the Contact Object against the AsyncAPI Specification.

type CorrelationID

type CorrelationID struct {
	marshaller.Model[core.CorrelationID]

	// Description is a description of the identifier. May contain CommonMark syntax.
	Description *string
	// Location is a runtime expression specifying the location of the correlation ID, e.g. `$message.header#/correlationId`. Required.
	Location string
	// Extensions provides a list of extensions to the Correlation ID Object.
	Extensions *extensions.Extensions
}

CorrelationID specifies an identifier at design time that can be used for message tracing and correlation.

func (*CorrelationID) GetDescription

func (c *CorrelationID) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*CorrelationID) GetExtensions

func (c *CorrelationID) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*CorrelationID) GetLocation

func (c *CorrelationID) GetLocation() string

GetLocation returns the location runtime expression, or an empty string if not set.

func (*CorrelationID) Validate

func (c *CorrelationID) Validate(_ context.Context, _ ...validation.Option) []error

Validate will validate the Correlation ID Object against the AsyncAPI Specification.

type ExternalDocumentation

type ExternalDocumentation = jsonschema.ExternalDocumentation

ExternalDocumentation allows referencing an external resource for extended documentation, or is a Reference Object to one.

type Info

type Info struct {
	marshaller.Model[core.Info]

	// Title is the title of the application.
	Title string
	// Version is the version of the application API, distinct from the AsyncAPI Specification version.
	Version string
	// Description is a description of the application. May contain CommonMark syntax.
	Description *string
	// TermsOfService is a URL to the Terms of Service for the API.
	TermsOfService *string
	// Contact is the contact information for the exposed API.
	Contact *Contact
	// License is the license information for the exposed API.
	License *License
	// Tags are used for logical grouping and categorization of the application.
	Tags []*Tag
	// ExternalDocs is additional external documentation for the application.
	ExternalDocs *ExternalDocumentation
	// Extensions provides a list of extensions to the Info Object.
	Extensions *extensions.Extensions
}

Info provides metadata about the API.

func (*Info) GetContact

func (i *Info) GetContact() *Contact

GetContact returns the contact information, or nil if not set.

func (*Info) GetDescription

func (i *Info) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Info) GetExtensions

func (i *Info) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Info) GetExternalDocs

func (i *Info) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*Info) GetLicense

func (i *Info) GetLicense() *License

GetLicense returns the license information, or nil if not set.

func (*Info) GetTags

func (i *Info) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*Info) GetTermsOfService

func (i *Info) GetTermsOfService() string

GetTermsOfService returns the Terms of Service URL, or an empty string if not set.

func (*Info) GetTitle

func (i *Info) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*Info) GetVersion

func (i *Info) GetVersion() string

GetVersion returns the application API version, or an empty string if not set.

func (*Info) Validate

func (i *Info) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Info Object against the AsyncAPI Specification.

type License

type License struct {
	marshaller.Model[core.License]

	// Name is the license name used for the API.
	Name string
	// URL is a URL to the license used for the API.
	URL *string
	// Extensions provides a list of extensions to the License Object.
	Extensions *extensions.Extensions
}

License is the license information for the exposed API.

func (*License) GetExtensions

func (l *License) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*License) GetName

func (l *License) GetName() string

GetName returns the license name, or an empty string if not set.

func (*License) GetURL

func (l *License) GetURL() string

GetURL returns the license URL, or an empty string if not set.

func (*License) Validate

func (l *License) Validate(_ context.Context, _ ...validation.Option) []error

Validate will validate the License Object against the AsyncAPI Specification.

type LocationContext

type LocationContext = walkpkg.LocationContext[MatchFunc]

LocationContext is the context of where an item is located within its parent.

type Locations

type Locations = walkpkg.Locations[MatchFunc]

Locations is the path from the document root to an item, convertible to a JSON pointer.

type MatchFunc

type MatchFunc func(Matcher) error

MatchFunc represents a particular model in the AsyncAPI document that can be matched. Pass it a Matcher with the appropriate functions populated to match the model type(s) you are interested in.

type Matcher

type Matcher struct {
	AsyncAPI                        func(*AsyncAPI) error
	Info                            func(*Info) error
	Contact                         func(*Contact) error
	License                         func(*License) error
	Tag                             func(*Tag) error
	ExternalDocumentation           func(*ExternalDocumentation) error
	Server                          func(*Server) error
	ServerVariable                  func(*ServerVariable) error
	Channel                         func(*Channel) error
	Parameter                       func(*Parameter) error
	Operation                       func(*Operation) error
	OperationTrait                  func(*OperationTrait) error
	OperationReply                  func(*OperationReply) error
	OperationReplyAddress           func(*OperationReplyAddress) error
	Message                         func(*Message) error
	MessageTrait                    func(*MessageTrait) error
	MessageExample                  func(*MessageExample) error
	CorrelationID                   func(*CorrelationID) error
	SecurityScheme                  func(*SecurityScheme) error
	OAuthFlows                      func(*OAuthFlows) error
	OAuthFlow                       func(*OAuthFlow) error
	Bindings                        func(*Bindings) error
	Components                      func(*Components) error
	ReferenceObject                 func(*ReferenceObject) error
	SchemaUnion                     func(*jsonschema.SchemaUnion) error
	ReferencedServer                func(*ReferencedServer) error
	ReferencedServerVariable        func(*ReferencedServerVariable) error
	ReferencedChannel               func(*ReferencedChannel) error
	ReferencedParameter             func(*ReferencedParameter) error
	ReferencedOperation             func(*ReferencedOperation) error
	ReferencedOperationTrait        func(*ReferencedOperationTrait) error
	ReferencedOperationReply        func(*ReferencedOperationReply) error
	ReferencedOperationReplyAddress func(*ReferencedOperationReplyAddress) error
	ReferencedMessage               func(*ReferencedMessage) error
	ReferencedMessageTrait          func(*ReferencedMessageTrait) error
	ReferencedCorrelationID         func(*ReferencedCorrelationID) error
	ReferencedSecurityScheme        func(*ReferencedSecurityScheme) error
	ReferencedBindings              func(*ReferencedBindings) error
	Extensions                      func(*extensions.Extensions) error
	Any                             func(any) error // Any will be called along with the other functions above on a match of a model
}

Matcher is used to match specific models in the AsyncAPI document. Populate the functions for the model types you are interested in. Returning walk.ErrTerminate from a function can be used to signal the caller to stop.

Reference wrappers (the Referenced* types) are visited at their location, followed by their inline object if they are not a Reference Object. Walking doesn't follow references, even after AsyncAPI.ResolveAllReferences, so the objects they point to are visited only at their own authored location. Schemas are visited as SchemaUnion values but are not descended into.

type Message

type Message struct {
	marshaller.Model[core.Message]

	// Headers is the schema of the application headers. It must be a schema of type object.
	Headers *jsonschema.SchemaUnion
	// Payload is the schema of the message payload.
	Payload *jsonschema.SchemaUnion
	// CorrelationID is the definition of the correlation ID used for message tracing or matching.
	CorrelationID *ReferencedCorrelationID
	// ContentType is the content type to use when encoding/decoding the payload, e.g. `application/json`.
	ContentType *string
	// Name is a machine-friendly name for the message.
	Name *string
	// Title is a human-friendly title for the message.
	Title *string
	// Summary is a short summary of what the message is about.
	Summary *string
	// Description is a description of the message. May contain CommonMark syntax.
	Description *string
	// Tags are used for logical grouping and categorization of messages.
	Tags []*Tag
	// ExternalDocs is additional external documentation for this message.
	ExternalDocs *ExternalDocumentation
	// Bindings are protocol-specific definitions for the message.
	Bindings *ReferencedBindings
	// Examples are examples of the message.
	Examples []*MessageExample
	// Traits are applied to the message, in order, using the traits merge mechanism.
	Traits []*ReferencedMessageTrait
	// Extensions provides a list of extensions to the Message Object.
	Extensions *extensions.Extensions
	// contains filtered or unexported fields
}

Message describes a message received on a given channel and operation.

func (*Message) GetBindings

func (m *Message) GetBindings() *ReferencedBindings

GetBindings returns the message bindings, or nil if not set.

func (*Message) GetContentType

func (m *Message) GetContentType() string

GetContentType returns the content type, or an empty string if not set.

func (*Message) GetCorrelationID

func (m *Message) GetCorrelationID() *ReferencedCorrelationID

GetCorrelationID returns the correlation ID, or nil if not set.

func (*Message) GetDescription

func (m *Message) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Message) GetEffective

func (m *Message) GetEffective() *Message

GetEffective returns the message with its traits applied, as computed by the last call to AsyncAPI.ResolveAllReferences. Returns nil if the message has traits that haven't been applied.

For a message with traits the result is a separate snapshot: editing it has no effect on the document. A message without traits is its own effective view, so GetEffective returns the message itself and editing the result edits the document.

func (*Message) GetExamples

func (m *Message) GetExamples() []*MessageExample

GetExamples returns the examples, or nil if not set.

func (*Message) GetExtensions

func (m *Message) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Message) GetExternalDocs

func (m *Message) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*Message) GetHeaders

func (m *Message) GetHeaders() *jsonschema.SchemaUnion

GetHeaders returns the headers schema, or nil if not set.

func (*Message) GetName

func (m *Message) GetName() string

GetName returns the name, or an empty string if not set.

func (*Message) GetPayload

func (m *Message) GetPayload() *jsonschema.SchemaUnion

GetPayload returns the payload schema, or nil if not set.

func (*Message) GetSummary

func (m *Message) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*Message) GetTags

func (m *Message) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*Message) GetTitle

func (m *Message) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*Message) GetTraitSource

func (m *Message) GetTraitSource(field string) (index int, ok bool)

GetTraitSource reports where a top-level field of the effective message came from: the index in Traits of the trait that supplied it, or -1 if the message sets it itself. ok is false if the field isn't in the effective message or traits haven't been applied. For a message without traits, fields written in the document report -1.

func (*Message) GetTraits

func (m *Message) GetTraits() []*ReferencedMessageTrait

GetTraits returns the message traits, or nil if not set.

func (*Message) Validate

func (m *Message) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Message Object against the AsyncAPI Specification.

type MessageExample

type MessageExample struct {
	marshaller.Model[core.MessageExample]

	// Headers is the example value of the message headers. It must be an object.
	Headers values.Value
	// Payload is the example value of the message payload.
	Payload values.Value
	// Name is a machine-friendly name for the example.
	Name *string
	// Summary is a short summary of the example.
	Summary *string
	// Extensions provides a list of extensions to the Message Example Object.
	Extensions *extensions.Extensions
}

MessageExample is an example of a message's headers and/or payload.

func (*MessageExample) GetExtensions

func (e *MessageExample) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*MessageExample) GetHeaders

func (e *MessageExample) GetHeaders() values.Value

GetHeaders returns the example headers, or nil if not set.

func (*MessageExample) GetName

func (e *MessageExample) GetName() string

GetName returns the name, or an empty string if not set.

func (*MessageExample) GetPayload

func (e *MessageExample) GetPayload() values.Value

GetPayload returns the example payload, or nil if not set.

func (*MessageExample) GetSummary

func (e *MessageExample) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*MessageExample) Validate

func (e *MessageExample) Validate(_ context.Context, _ ...validation.Option) []error

Validate will validate the Message Example Object against the AsyncAPI Specification. Example values are not validated against the message schemas.

type MessageTrait

type MessageTrait struct {
	marshaller.Model[core.MessageTrait]

	// Headers is the schema of the application headers. It must be a schema of type object.
	Headers *jsonschema.SchemaUnion
	// CorrelationID is the definition of the correlation ID used for message tracing or matching.
	CorrelationID *ReferencedCorrelationID
	// ContentType is the content type to use when encoding/decoding the payload.
	ContentType *string
	// Name is a machine-friendly name for the message.
	Name *string
	// Title is a human-friendly title for the message.
	Title *string
	// Summary is a short summary of what the message is about.
	Summary *string
	// Description is a description of the message. May contain CommonMark syntax.
	Description *string
	// Tags are used for logical grouping and categorization of messages.
	Tags []*Tag
	// ExternalDocs is additional external documentation for the message.
	ExternalDocs *ExternalDocumentation
	// Bindings are protocol-specific definitions for the message.
	Bindings *ReferencedBindings
	// Examples are examples of the message.
	Examples []*MessageExample
	// Extensions provides a list of extensions to the Message Trait Object.
	Extensions *extensions.Extensions
}

MessageTrait describes a trait that may be applied to a Message Object. It can contain any message property except payload and traits.

func (*MessageTrait) GetBindings

func (t *MessageTrait) GetBindings() *ReferencedBindings

GetBindings returns the message bindings, or nil if not set.

func (*MessageTrait) GetContentType

func (t *MessageTrait) GetContentType() string

GetContentType returns the content type, or an empty string if not set.

func (*MessageTrait) GetCorrelationID

func (t *MessageTrait) GetCorrelationID() *ReferencedCorrelationID

GetCorrelationID returns the correlation ID, or nil if not set.

func (*MessageTrait) GetDescription

func (t *MessageTrait) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*MessageTrait) GetExamples

func (t *MessageTrait) GetExamples() []*MessageExample

GetExamples returns the examples, or nil if not set.

func (*MessageTrait) GetExtensions

func (t *MessageTrait) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*MessageTrait) GetExternalDocs

func (t *MessageTrait) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*MessageTrait) GetHeaders

func (t *MessageTrait) GetHeaders() *jsonschema.SchemaUnion

GetHeaders returns the headers schema, or nil if not set.

func (*MessageTrait) GetName

func (t *MessageTrait) GetName() string

GetName returns the name, or an empty string if not set.

func (*MessageTrait) GetSummary

func (t *MessageTrait) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*MessageTrait) GetTags

func (t *MessageTrait) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*MessageTrait) GetTitle

func (t *MessageTrait) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*MessageTrait) Validate

func (t *MessageTrait) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Message Trait Object against the AsyncAPI Specification.

type OAuthFlow

type OAuthFlow struct {
	marshaller.Model[core.OAuthFlow]

	// AuthorizationURL is the authorization URL for this flow. Required for `implicit` and `authorizationCode`.
	AuthorizationURL *string
	// TokenURL is the token URL for this flow. Required for `password`, `clientCredentials` and `authorizationCode`.
	TokenURL *string
	// RefreshURL is the URL used for obtaining refresh tokens.
	RefreshURL *string
	// AvailableScopes are the available scopes for the OAuth2 security scheme, mapping scope names to descriptions. Required.
	AvailableScopes *sequencedmap.Map[string, string]
	// Extensions provides a list of extensions to the OAuth Flow Object.
	Extensions *extensions.Extensions
}

OAuthFlow is the configuration details for a supported OAuth flow.

func (*OAuthFlow) GetAuthorizationURL

func (f *OAuthFlow) GetAuthorizationURL() string

GetAuthorizationURL returns the authorization URL, or an empty string if not set.

func (*OAuthFlow) GetAvailableScopes

func (f *OAuthFlow) GetAvailableScopes() *sequencedmap.Map[string, string]

GetAvailableScopes returns the available scopes, or nil if not set.

func (*OAuthFlow) GetExtensions

func (f *OAuthFlow) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*OAuthFlow) GetRefreshURL

func (f *OAuthFlow) GetRefreshURL() string

GetRefreshURL returns the refresh URL, or an empty string if not set.

func (*OAuthFlow) GetTokenURL

func (f *OAuthFlow) GetTokenURL() string

GetTokenURL returns the token URL, or an empty string if not set.

func (*OAuthFlow) Validate

func (f *OAuthFlow) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the OAuth Flow Object against the AsyncAPI Specification. The URLs a flow requires depend on its kind, which is checked when validating the parent OAuth Flows Object.

type OAuthFlows

type OAuthFlows struct {
	marshaller.Model[core.OAuthFlows]

	// Implicit is the configuration for the OAuth Implicit flow.
	Implicit *OAuthFlow
	// Password is the configuration for the OAuth Resource Owner Protected Credentials flow.
	Password *OAuthFlow
	// ClientCredentials is the configuration for the OAuth Client Credentials flow.
	ClientCredentials *OAuthFlow
	// AuthorizationCode is the configuration for the OAuth Authorization Code flow.
	AuthorizationCode *OAuthFlow
	// Extensions provides a list of extensions to the OAuth Flows Object.
	Extensions *extensions.Extensions
}

OAuthFlows allows configuration of the supported OAuth flows.

func (*OAuthFlows) GetAuthorizationCode

func (f *OAuthFlows) GetAuthorizationCode() *OAuthFlow

GetAuthorizationCode returns the authorization code flow, or nil if not set.

func (*OAuthFlows) GetClientCredentials

func (f *OAuthFlows) GetClientCredentials() *OAuthFlow

GetClientCredentials returns the client credentials flow, or nil if not set.

func (*OAuthFlows) GetExtensions

func (f *OAuthFlows) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*OAuthFlows) GetImplicit

func (f *OAuthFlows) GetImplicit() *OAuthFlow

GetImplicit returns the implicit flow, or nil if not set.

func (*OAuthFlows) GetPassword

func (f *OAuthFlows) GetPassword() *OAuthFlow

GetPassword returns the password flow, or nil if not set.

func (*OAuthFlows) Validate

func (f *OAuthFlows) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the OAuth Flows Object against the AsyncAPI Specification.

type Operation

type Operation struct {
	marshaller.Model[core.Operation]

	// Action is whether the application sends or receives messages. Required.
	Action OperationAction
	// Channel is a reference to the channel in the root channels map this operation is performed on. Required.
	Channel ReferenceObject
	// Title is a human-friendly title for the operation.
	Title *string
	// Summary is a short summary of the operation.
	Summary *string
	// Description is a description of the operation. May contain CommonMark syntax.
	Description *string
	// Security are the security schemes associated with this operation. Only one needs to be satisfied.
	Security []*ReferencedSecurityScheme
	// Tags are used for logical grouping and categorization of operations.
	Tags []*Tag
	// ExternalDocs is additional external documentation for this operation.
	ExternalDocs *ExternalDocumentation
	// Bindings are protocol-specific definitions for the operation.
	Bindings *ReferencedBindings
	// Traits are applied to the operation, in order, using the traits merge mechanism.
	Traits []*ReferencedOperationTrait
	// Messages are references to the channel's messages this operation supports. When nil (omitted) all of the
	// channel's messages are supported; when empty no messages are.
	Messages []*ReferenceObject
	// Reply is the definition of the reply in a request-reply operation.
	Reply *ReferencedOperationReply
	// Extensions provides a list of extensions to the Operation Object.
	Extensions *extensions.Extensions
	// contains filtered or unexported fields
}

Operation describes a specific operation. Operations are identified by their key in the operations map; there is no separate operation ID field.

func (*Operation) GetAction

func (o *Operation) GetAction() OperationAction

GetAction returns the action, or an empty action if not set.

func (*Operation) GetBindings

func (o *Operation) GetBindings() *ReferencedBindings

GetBindings returns the operation bindings, or nil if not set.

func (*Operation) GetChannel

func (o *Operation) GetChannel() *ReferenceObject

GetChannel returns the channel reference, or nil if the operation is nil.

func (*Operation) GetDescription

func (o *Operation) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Operation) GetEffective

func (o *Operation) GetEffective() *Operation

GetEffective returns the operation with its traits applied, as computed by the last call to AsyncAPI.ResolveAllReferences. Returns nil if the operation has traits that haven't been applied.

For an operation with traits the result is a separate snapshot: editing it has no effect on the document. An operation without traits is its own effective view, so GetEffective returns the operation itself and editing the result edits the document.

func (*Operation) GetExtensions

func (o *Operation) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Operation) GetExternalDocs

func (o *Operation) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*Operation) GetMessages

func (o *Operation) GetMessages() []*ReferenceObject

GetMessages returns the message references. A nil result means messages were omitted, so all of the channel's messages apply; an empty result means no messages apply.

func (*Operation) GetReply

func (o *Operation) GetReply() *ReferencedOperationReply

GetReply returns the reply, or nil if not set.

func (*Operation) GetSecurity

func (o *Operation) GetSecurity() []*ReferencedSecurityScheme

GetSecurity returns the security schemes, or nil if not set.

func (*Operation) GetSummary

func (o *Operation) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*Operation) GetTags

func (o *Operation) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*Operation) GetTitle

func (o *Operation) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*Operation) GetTraitSource

func (o *Operation) GetTraitSource(field string) (index int, ok bool)

GetTraitSource reports where a top-level field of the effective operation came from: the index in Traits of the trait that supplied it, or -1 if the operation sets it itself. ok is false if the field isn't in the effective operation or traits haven't been applied. For an operation without traits, fields written in the document report -1.

func (*Operation) GetTraits

func (o *Operation) GetTraits() []*ReferencedOperationTrait

GetTraits returns the operation traits, or nil if not set.

func (*Operation) Validate

func (o *Operation) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Operation Object against the AsyncAPI Specification.

type OperationAction

type OperationAction string

OperationAction is the action an application performs for an operation.

const (
	// OperationActionSend means the application sends messages to the channel.
	OperationActionSend OperationAction = "send"
	// OperationActionReceive means the application receives messages from the channel.
	OperationActionReceive OperationAction = "receive"
)

type OperationReply

type OperationReply struct {
	marshaller.Model[core.OperationReply]

	// Address is where the reply should be sent, determined at runtime.
	Address *ReferencedOperationReplyAddress
	// Channel is a reference to the channel used for the reply.
	Channel *ReferenceObject
	// Messages are references to the channel's messages that can be used as the reply.
	Messages []*ReferenceObject
	// Extensions provides a list of extensions to the Operation Reply Object.
	Extensions *extensions.Extensions
}

OperationReply describes the reply part of a request-reply operation.

func (*OperationReply) GetAddress

GetAddress returns the reply address, or nil if not set.

func (*OperationReply) GetChannel

func (r *OperationReply) GetChannel() *ReferenceObject

GetChannel returns the reply channel reference, or nil if not set.

func (*OperationReply) GetExtensions

func (r *OperationReply) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*OperationReply) GetMessages

func (r *OperationReply) GetMessages() []*ReferenceObject

GetMessages returns the reply message references, or nil if not set.

func (*OperationReply) Validate

func (r *OperationReply) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Operation Reply Object against the AsyncAPI Specification.

type OperationReplyAddress

type OperationReplyAddress struct {
	marshaller.Model[core.OperationReplyAddress]

	// Description is a description of the address. May contain CommonMark syntax.
	Description *string
	// Location is a runtime expression specifying the location of the reply address, e.g. `$message.header#/replyTo`. Required.
	Location string
	// Extensions provides a list of extensions to the Operation Reply Address Object.
	Extensions *extensions.Extensions
}

OperationReplyAddress is a runtime expression identifying where a reply should be sent.

func (*OperationReplyAddress) GetDescription

func (a *OperationReplyAddress) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*OperationReplyAddress) GetExtensions

func (a *OperationReplyAddress) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*OperationReplyAddress) GetLocation

func (a *OperationReplyAddress) GetLocation() string

GetLocation returns the location runtime expression, or an empty string if not set.

func (*OperationReplyAddress) Validate

Validate will validate the Operation Reply Address Object against the AsyncAPI Specification.

type OperationTrait

type OperationTrait struct {
	marshaller.Model[core.OperationTrait]

	// Title is a human-friendly title for the operation.
	Title *string
	// Summary is a short summary of the operation.
	Summary *string
	// Description is a description of the operation. May contain CommonMark syntax.
	Description *string
	// Security are the security schemes associated with the operation.
	Security []*ReferencedSecurityScheme
	// Tags are used for logical grouping and categorization of operations.
	Tags []*Tag
	// ExternalDocs is additional external documentation for the operation.
	ExternalDocs *ExternalDocumentation
	// Bindings are protocol-specific definitions for the operation.
	Bindings *ReferencedBindings
	// Reply is the definition of the reply in a request-reply operation.
	Reply *ReferencedOperationReply
	// Extensions provides a list of extensions to the Operation Trait Object.
	Extensions *extensions.Extensions
}

OperationTrait describes a trait that may be applied to an Operation Object. It can contain any operation property except action, channel, messages and traits.

func (*OperationTrait) GetBindings

func (t *OperationTrait) GetBindings() *ReferencedBindings

GetBindings returns the operation bindings, or nil if not set.

func (*OperationTrait) GetDescription

func (t *OperationTrait) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*OperationTrait) GetExtensions

func (t *OperationTrait) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*OperationTrait) GetExternalDocs

func (t *OperationTrait) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*OperationTrait) GetReply

GetReply returns the reply, or nil if not set.

func (*OperationTrait) GetSecurity

func (t *OperationTrait) GetSecurity() []*ReferencedSecurityScheme

GetSecurity returns the security schemes, or nil if not set.

func (*OperationTrait) GetSummary

func (t *OperationTrait) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*OperationTrait) GetTags

func (t *OperationTrait) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*OperationTrait) GetTitle

func (t *OperationTrait) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*OperationTrait) Validate

func (t *OperationTrait) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Operation Trait Object against the AsyncAPI Specification.

type Option

type Option[T any] func(o *T)

Option is an option for working with AsyncAPI documents.

func WithSkipValidation

func WithSkipValidation() Option[UnmarshalOptions]

WithSkipValidation will skip validation of the AsyncAPI document during unmarshalling. Useful to quickly load a document that will be mutated and validated later.

type Parameter

type Parameter struct {
	marshaller.Model[core.Parameter]

	// Enum is the set of values the parameter may take.
	Enum []string
	// Default is the value to use when no other value is supplied.
	Default *string
	// Description is a description of the parameter. May contain CommonMark syntax.
	Description *string
	// Examples are examples of the parameter's value.
	Examples []string
	// Location is a runtime expression specifying the location of the parameter value, e.g. `$message.payload#/user/id`.
	Location *string
	// Extensions provides a list of extensions to the Parameter Object.
	Extensions *extensions.Extensions
}

Parameter describes a parameter included in a channel address.

func (*Parameter) GetDefault

func (p *Parameter) GetDefault() string

GetDefault returns the default value, or an empty string if not set.

func (*Parameter) GetDescription

func (p *Parameter) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Parameter) GetEnum

func (p *Parameter) GetEnum() []string

GetEnum returns the allowed values, or nil if not set.

func (*Parameter) GetExamples

func (p *Parameter) GetExamples() []string

GetExamples returns the examples, or nil if not set.

func (*Parameter) GetExtensions

func (p *Parameter) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Parameter) GetLocation

func (p *Parameter) GetLocation() string

GetLocation returns the location runtime expression, or an empty string if not set.

func (*Parameter) Validate

func (p *Parameter) Validate(_ context.Context, _ ...validation.Option) []error

Validate will validate the Parameter Object against the AsyncAPI Specification.

type Reference

type Reference[T any, V interfaces.Validator[T], C marshaller.CoreModeler] struct {
	marshaller.Model[core.Reference[C]]

	// Reference is the URI of the referenced object. Set when this is a Reference Object.
	Reference *references.Reference
	// Object is the inline object. Set when this is not a Reference Object.
	Object *T
	// contains filtered or unexported fields
}

Reference is either an inline object or an AsyncAPI Reference Object to one.

Reference Objects are resolved explicitly by AsyncAPI.ResolveAllReferences. Until then GetObject only returns inline objects.

func (*Reference[T, V, C]) GetNavigableNode

func (r *Reference[T, V, C]) GetNavigableNode() (any, error)

GetNavigableNode returns the inline or resolved object so JSON pointers can navigate through references.

func (*Reference[T, V, C]) GetObject

func (r *Reference[T, V, C]) GetObject() *T

GetObject returns the inline object. For a Reference Object it returns the object it resolved to in the last call to AsyncAPI.ResolveAllReferences, following any chain of references, or nil if it hasn't been resolved.

func (*Reference[T, V, C]) GetReference

func (r *Reference[T, V, C]) GetReference() references.Reference

GetReference returns the reference, or an empty reference if this is an inline object.

func (*Reference[T, V, C]) GetResolvedReference

func (r *Reference[T, V, C]) GetResolvedReference() references.Reference

GetResolvedReference returns the absolute location of the object a Reference Object resolved to, after following any chain of references. It is empty for inline objects and unresolved references.

func (*Reference[T, V, C]) IsReference

func (r *Reference[T, V, C]) IsReference() bool

IsReference returns true if this is a Reference Object rather than an inline object.

func (*Reference[T, V, C]) IsResolved

func (r *Reference[T, V, C]) IsResolved() bool

IsResolved returns true if this is an inline object, or a Reference Object that has been resolved.

func (*Reference[T, V, C]) Populate

func (r *Reference[T, V, C]) Populate(source any) error

func (*Reference[T, V, C]) Validate

func (r *Reference[T, V, C]) Validate(ctx context.Context, opts ...validation.Option) []error

Validate validates the reference, or the inline object.

type ReferenceObject

type ReferenceObject struct {
	marshaller.Model[core.ReferenceObject]

	// Reference is the URI of the referenced object.
	Reference references.Reference
	// contains filtered or unexported fields
}

ReferenceObject is a field that must be an AsyncAPI Reference Object, such as an operation's channel.

func NewReferenceObject

func NewReferenceObject(ref references.Reference) *ReferenceObject

NewReferenceObject creates a Reference Object for the provided reference.

func (*ReferenceObject) GetChannel

func (r *ReferenceObject) GetChannel() *Channel

GetChannel returns the resolved channel, or nil if unresolved or the reference is not to a channel.

func (*ReferenceObject) GetMessage

func (r *ReferenceObject) GetMessage() *Message

GetMessage returns the resolved message, or nil if unresolved or the reference is not to a message.

func (*ReferenceObject) GetReference

func (r *ReferenceObject) GetReference() references.Reference

GetReference returns the reference, or an empty reference if not set.

func (*ReferenceObject) GetResolvedObject

func (r *ReferenceObject) GetResolvedObject() any

GetResolvedObject returns the object the reference resolved to in the last call to AsyncAPI.ResolveAllReferences: a *Channel, *Message or *Server depending on where the Reference Object is used. Returns nil if it hasn't been resolved.

func (*ReferenceObject) GetResolvedReference

func (r *ReferenceObject) GetResolvedReference() references.Reference

GetResolvedReference returns the absolute location of the resolved object, or an empty reference if unresolved.

func (*ReferenceObject) GetServer

func (r *ReferenceObject) GetServer() *Server

GetServer returns the resolved server, or nil if unresolved or the reference is not to a server.

func (*ReferenceObject) IsResolved

func (r *ReferenceObject) IsResolved() bool

IsResolved returns true if the reference has been resolved.

func (*ReferenceObject) Validate

func (r *ReferenceObject) Validate(_ context.Context, _ ...validation.Option) []error

Validate validates the Reference Object.

type ReferencedBindings

type ReferencedBindings = Reference[Bindings, *Bindings, *core.Bindings]

ReferencedBindings is a Bindings Object or a Reference Object to one.

type ReferencedChannel

type ReferencedChannel = Reference[Channel, *Channel, *core.Channel]

ReferencedChannel is a Channel Object or a Reference Object to one.

type ReferencedCorrelationID

type ReferencedCorrelationID = Reference[CorrelationID, *CorrelationID, *core.CorrelationID]

ReferencedCorrelationID is a Correlation ID Object or a Reference Object to one.

type ReferencedMessage

type ReferencedMessage = Reference[Message, *Message, *core.Message]

ReferencedMessage is a Message Object or a Reference Object to one.

type ReferencedMessageTrait

type ReferencedMessageTrait = Reference[MessageTrait, *MessageTrait, *core.MessageTrait]

ReferencedMessageTrait is a Message Trait Object or a Reference Object to one.

type ReferencedOperation

type ReferencedOperation = Reference[Operation, *Operation, *core.Operation]

ReferencedOperation is an Operation Object or a Reference Object to one.

type ReferencedOperationReply

type ReferencedOperationReply = Reference[OperationReply, *OperationReply, *core.OperationReply]

ReferencedOperationReply is an Operation Reply Object or a Reference Object to one.

type ReferencedOperationReplyAddress

ReferencedOperationReplyAddress is an Operation Reply Address Object or a Reference Object to one.

type ReferencedOperationTrait

type ReferencedOperationTrait = Reference[OperationTrait, *OperationTrait, *core.OperationTrait]

ReferencedOperationTrait is an Operation Trait Object or a Reference Object to one.

type ReferencedParameter

type ReferencedParameter = Reference[Parameter, *Parameter, *core.Parameter]

ReferencedParameter is a Parameter Object or a Reference Object to one.

type ReferencedSecurityScheme

type ReferencedSecurityScheme = Reference[SecurityScheme, *SecurityScheme, *core.SecurityScheme]

ReferencedSecurityScheme is a Security Scheme Object or a Reference Object to one.

type ReferencedServer

type ReferencedServer = Reference[Server, *Server, *core.Server]

ReferencedServer is a Server Object or a Reference Object to one.

type ReferencedServerVariable

type ReferencedServerVariable = Reference[ServerVariable, *ServerVariable, *core.ServerVariable]

ReferencedServerVariable is a Server Variable Object or a Reference Object to one.

type ResolveAllOptions

type ResolveAllOptions struct {
	// AsyncAPILocation is the absolute file path or URL of the document. Relative references to other documents are
	// resolved against it. Without it, only references within the document and absolute references can be resolved.
	AsyncAPILocation string
	// DisableExternalRefs reports references to other documents as errors instead of loading them. The errors wrap
	// ErrExternalReferencesDisabled.
	DisableExternalRefs bool
	// VirtualFS is used for file based references. If not provided the local file system is used.
	VirtualFS system.VirtualFS
	// HTTPClient is used for URL based references. If not provided http.DefaultClient is used. It is not a sandbox:
	// callers that need to restrict which hosts are contacted must provide a client that enforces it.
	HTTPClient system.Client
}

ResolveAllOptions are the options available when resolving all references in an AsyncAPI document.

type ResolvedSchema

type ResolvedSchema struct {
	// Schema is the resolved schema for native AsyncAPI and JSON Schema based formats, and for references within the
	// document.
	Schema *jsonschema.SchemaUnion
	// Raw is the resolved resource for other formats, such as an Avro schema file, preserved unchanged.
	Raw *yaml.Node
	// SchemaFormat is the format the resource was interpreted with.
	SchemaFormat string
	// Reference is the absolute location the schema was resolved from.
	Reference references.Reference
}

ResolvedSchema is a schema Reference Object resolved by ResolveAllReferences.

type SecurityScheme

type SecurityScheme struct {
	marshaller.Model[core.SecurityScheme]

	// Type is the type of the security scheme. Required.
	Type SecuritySchemeType
	// Description is a description of the security scheme. May contain CommonMark syntax.
	Description *string
	// Name is the name of the header, query or cookie parameter to be used. Required for `httpApiKey`.
	Name *string
	// In is the location of the API key. Required for `apiKey` (`user` or `password`) and `httpApiKey` (`query`, `header` or `cookie`).
	In *string
	// Scheme is the name of the HTTP Authorization scheme to be used. Required for `http`.
	Scheme *string
	// BearerFormat is a hint to the client to identify how the bearer token is formatted.
	BearerFormat *string
	// Flows contains configuration information for the supported flows. Required for `oauth2`.
	Flows *OAuthFlows
	// OpenIDConnectURL is the OpenID Connect URL to discover OAuth2 configuration values. Required for `openIdConnect`.
	OpenIDConnectURL *string
	// Scopes are the scopes needed to access the resource for `oauth2` and `openIdConnect`. Empty means no scopes are needed.
	Scopes []string
	// Extensions provides a list of extensions to the Security Scheme Object.
	Extensions *extensions.Extensions
}

SecurityScheme defines a security scheme that can be used by servers and operations.

func (*SecurityScheme) GetBearerFormat

func (s *SecurityScheme) GetBearerFormat() string

GetBearerFormat returns the bearer format, or an empty string if not set.

func (*SecurityScheme) GetDescription

func (s *SecurityScheme) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*SecurityScheme) GetExtensions

func (s *SecurityScheme) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*SecurityScheme) GetFlows

func (s *SecurityScheme) GetFlows() *OAuthFlows

GetFlows returns the OAuth flows, or nil if not set.

func (*SecurityScheme) GetIn

func (s *SecurityScheme) GetIn() string

GetIn returns the location of the API key, or an empty string if not set.

func (*SecurityScheme) GetName

func (s *SecurityScheme) GetName() string

GetName returns the name, or an empty string if not set.

func (*SecurityScheme) GetOpenIDConnectURL

func (s *SecurityScheme) GetOpenIDConnectURL() string

GetOpenIDConnectURL returns the OpenID Connect URL, or an empty string if not set.

func (*SecurityScheme) GetScheme

func (s *SecurityScheme) GetScheme() string

GetScheme returns the HTTP Authorization scheme, or an empty string if not set.

func (*SecurityScheme) GetScopes

func (s *SecurityScheme) GetScopes() []string

GetScopes returns the scopes, or nil if not set.

func (*SecurityScheme) GetType

func (s *SecurityScheme) GetType() SecuritySchemeType

GetType returns the type, or an empty type if not set.

func (*SecurityScheme) Validate

func (s *SecurityScheme) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Security Scheme Object against the AsyncAPI Specification.

type SecuritySchemeType

type SecuritySchemeType string

SecuritySchemeType is the type of a security scheme.

const (
	SecuritySchemeTypeUserPassword         SecuritySchemeType = "userPassword"
	SecuritySchemeTypeAPIKey               SecuritySchemeType = "apiKey"
	SecuritySchemeTypeX509                 SecuritySchemeType = "X509"
	SecuritySchemeTypeSymmetricEncryption  SecuritySchemeType = "symmetricEncryption"
	SecuritySchemeTypeAsymmetricEncryption SecuritySchemeType = "asymmetricEncryption"
	SecuritySchemeTypeHTTPAPIKey           SecuritySchemeType = "httpApiKey"
	SecuritySchemeTypeHTTP                 SecuritySchemeType = "http"
	SecuritySchemeTypeOAuth2               SecuritySchemeType = "oauth2"
	SecuritySchemeTypeOpenIDConnect        SecuritySchemeType = "openIdConnect"
	SecuritySchemeTypePlain                SecuritySchemeType = "plain"
	SecuritySchemeTypeScramSha256          SecuritySchemeType = "scramSha256"
	SecuritySchemeTypeScramSha512          SecuritySchemeType = "scramSha512"
	SecuritySchemeTypeGSSAPI               SecuritySchemeType = "gssapi"
)

type Server

type Server struct {
	marshaller.Model[core.Server]

	// Host is the server host name. It may include the port and Server Variables. Required.
	Host string
	// Protocol is the protocol this server supports for connection, e.g. `kafka` or `mqtt`. Required.
	Protocol string
	// ProtocolVersion is the version of the protocol used for connection.
	ProtocolVersion *string
	// Pathname is the path to a resource in the host. It may include Server Variables.
	Pathname *string
	// Description is a description of the server. May contain CommonMark syntax.
	Description *string
	// Title is a human-friendly title for the server.
	Title *string
	// Summary is a short summary of the server.
	Summary *string
	// Variables are the variables used for substitution in the host and pathname.
	Variables *sequencedmap.Map[string, *ReferencedServerVariable]
	// Security are the security schemes that can be used with this server. Only one needs to be satisfied.
	Security []*ReferencedSecurityScheme
	// Tags are used for logical grouping and categorization of servers.
	Tags []*Tag
	// ExternalDocs is additional external documentation for this server.
	ExternalDocs *ExternalDocumentation
	// Bindings are protocol-specific definitions for the server.
	Bindings *ReferencedBindings
	// Extensions provides a list of extensions to the Server Object.
	Extensions *extensions.Extensions
}

Server describes a message broker, a server or any other kind of computer program capable of sending and/or receiving data.

func (*Server) GetBindings

func (s *Server) GetBindings() *ReferencedBindings

GetBindings returns the server bindings, or nil if not set.

func (*Server) GetDescription

func (s *Server) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Server) GetExtensions

func (s *Server) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Server) GetExternalDocs

func (s *Server) GetExternalDocs() *ExternalDocumentation

GetExternalDocs returns the external documentation, or nil if not set.

func (*Server) GetHost

func (s *Server) GetHost() string

GetHost returns the host, or an empty string if not set.

func (*Server) GetPathname

func (s *Server) GetPathname() string

GetPathname returns the pathname, or an empty string if not set.

func (*Server) GetProtocol

func (s *Server) GetProtocol() string

GetProtocol returns the protocol, or an empty string if not set.

func (*Server) GetProtocolVersion

func (s *Server) GetProtocolVersion() string

GetProtocolVersion returns the protocol version, or an empty string if not set.

func (*Server) GetSecurity

func (s *Server) GetSecurity() []*ReferencedSecurityScheme

GetSecurity returns the security schemes, or nil if not set.

func (*Server) GetSummary

func (s *Server) GetSummary() string

GetSummary returns the summary, or an empty string if not set.

func (*Server) GetTags

func (s *Server) GetTags() []*Tag

GetTags returns the tags, or nil if not set.

func (*Server) GetTitle

func (s *Server) GetTitle() string

GetTitle returns the title, or an empty string if not set.

func (*Server) GetVariables

func (s *Server) GetVariables() *sequencedmap.Map[string, *ReferencedServerVariable]

GetVariables returns the server variables, or nil if not set.

func (*Server) Validate

func (s *Server) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Server Object against the AsyncAPI Specification.

type ServerVariable

type ServerVariable struct {
	marshaller.Model[core.ServerVariable]

	// Enum is the set of values the variable may take.
	Enum []string
	// Default is the value to use for substitution when no other value is supplied.
	Default *string
	// Description is a description of the variable. May contain CommonMark syntax.
	Description *string
	// Examples are examples of the variable's value.
	Examples []string
	// Extensions provides a list of extensions to the Server Variable Object.
	Extensions *extensions.Extensions
}

ServerVariable is a variable for server host and pathname substitution.

func (*ServerVariable) GetDefault

func (v *ServerVariable) GetDefault() string

GetDefault returns the default value, or an empty string if not set.

func (*ServerVariable) GetDescription

func (v *ServerVariable) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*ServerVariable) GetEnum

func (v *ServerVariable) GetEnum() []string

GetEnum returns the allowed values, or nil if not set.

func (*ServerVariable) GetExamples

func (v *ServerVariable) GetExamples() []string

GetExamples returns the examples, or nil if not set.

func (*ServerVariable) GetExtensions

func (v *ServerVariable) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*ServerVariable) Validate

func (v *ServerVariable) Validate(_ context.Context, _ ...validation.Option) []error

Validate will validate the Server Variable Object against the AsyncAPI Specification.

type Tag

type Tag struct {
	marshaller.Model[core.Tag]

	// Ref is set when this is a Reference Object, in which case the other fields are ignored.
	Ref *references.Reference
	// Name is the name of the tag. Required unless this is a Reference Object.
	Name *string
	// Description is a description of the tag. May contain CommonMark syntax.
	Description *string
	// ExternalDocs is additional external documentation for the tag.
	ExternalDocs *ExternalDocumentation
	// Extensions provides a list of extensions to the Tag Object.
	Extensions *extensions.Extensions
	// contains filtered or unexported fields
}

Tag allows adding metadata to a single tag, or is a Reference Object to a Tag Object.

func (*Tag) GetDescription

func (t *Tag) GetDescription() string

GetDescription returns the description, or an empty string if not set.

func (*Tag) GetExtensions

func (t *Tag) GetExtensions() *extensions.Extensions

GetExtensions returns the extensions. Returns an empty extensions map if not set.

func (*Tag) GetName

func (t *Tag) GetName() string

GetName returns the tag name, or an empty string if not set.

func (*Tag) GetResolved

func (t *Tag) GetResolved() *Tag

GetResolved returns the tag itself, or for a Reference Object the tag it resolved to in the last call to AsyncAPI.ResolveAllReferences. Returns nil for an unresolved Reference Object.

func (*Tag) IsReference

func (t *Tag) IsReference() bool

IsReference returns true if the tag is a Reference Object.

func (*Tag) Validate

func (t *Tag) Validate(ctx context.Context, opts ...validation.Option) []error

Validate will validate the Tag Object against the AsyncAPI Specification.

type UnmarshalOptions

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

UnmarshalOptions are the options available when unmarshalling an AsyncAPI document.

type WalkItem

type WalkItem struct {
	Match    MatchFunc
	Location Locations
	AsyncAPI *AsyncAPI
}

WalkItem represents a single item yielded by the Walk iterator.

Directories

Path Synopsis
Package core contains the backing models for AsyncAPI documents, retaining the YAML/JSON nodes they were parsed from.
Package core contains the backing models for AsyncAPI documents, retaining the YAML/JSON nodes they were parsed from.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL