asyncapi

package module
v0.0.0-...-da7576a Latest Latest
Warning

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

 Go to latest Published: Aug 27, 2026 License: Apache-2.0 Imports: 21 Imported by: 0

README

Go Reference Go Report Card Code Coverage

Transform and master your event-driven API specs with ease.

Package asyncapi provides a suite of tools for working with AsyncAPI specifications, making it easier to parse, format, manipulate, and generate code from these specs.

It is the counterpart of MarkRosemaker/openapi for event-driven APIs and follows the same design, so both packages can be used side by side.

Introduction

The primary goals of this package are:

  • Parsing AsyncAPI specifications into a structured format.
  • Validating the specifications strictly against the rules of the specification.
  • Formatting the parsed specifications, including sorting maps and merging duplicate content.
  • Adding information programmatically to the specifications.
  • Marshalling the modified specifications back into their original format.
  • Utilizing the parsed specification for code generation.

Features

  • Comprehensive parsing of AsyncAPI 3.1.0 specifications, in JSON as well as in YAML.
  • Strict validation against the rules of the specification: required fields, enumerations, key and address patterns, absolute URLs, runtime expressions, and the rules that span several objects, e.g. that the messages of an operation "MUST contain a subset of the messages defined in the channel referenced in this operation". Every error names the exact location of the problem, e.g. channels["userSignedup"].messages["userSignedUp"].contentType: mime: expected slash after first token.
  • Marshalling back to JSON and to YAML, to a file, to a writer or to a byte slice.
  • Reference resolution of every referencable object, including references that point to other references, e.g. an operation that refers to a message of a channel which in turn refers to a message of the components object.
  • Order preservation: maps keep the order in which their keys were defined, so writing a specification back doesn't reshuffle it.
  • Multi format schemas: schemas in other formats (Avro, Protobuf, RAML, ...) are kept as they are, AsyncAPI schemas are parsed, including boolean schemas and multiple types.
  • Bindings of all 20 protocols are preserved as they were given, so nothing is lost when a specification is written back.
  • Documented in line with the specification: every object, field and rule quotes the official documentation and links to the section it comes from.

Usage

package main

import (
    "fmt"

    "github.com/MarkRosemaker/asyncapi"
)

func main() {
    doc, err := asyncapi.LoadFromFile("path/to/asyncapi.json") // or asyncapi.yaml
    if err != nil {
        fmt.Println("Error parsing spec:", err)
        return
    }

    if err := doc.Validate(); err != nil {
        fmt.Println("Error validating spec:", err)
        return
    }

    // sort the keys of the servers, channels, operations and components in alphabetical order
    doc.SortMaps()

    // write an improved version of your spec, as JSON or as YAML
    if err := doc.WriteToFile("path/to/asyncapi.json"); err != nil {
        fmt.Println("Error writing to file:", err)
        return
    }
}

Additional Information

Contributing

If you have any contributions to make, please submit a pull request or open an issue on the GitHub repository.

License

This project is licensed under the Apache 2.0 License.

Documentation

Overview

Package asyncapi parses, validates, formats and writes AsyncAPI specifications.

It implements version 3.1.0 of the AsyncAPI Specification, which describes an event-driven API: "The AsyncAPI Specification defines a set of files required to describe an application's API. These files can then be used to create utilities, such as documentation, code, integration, or testing tools."

Reading a document

A document is read with LoadFromFile, LoadFromData or LoadFromReader, each of which determines whether the document is JSON or YAML, since "an AsyncAPI document can be JSON or YAML format" (Format). Use the JSON or YAML variants, e.g. LoadFromDataJSON, if the format is already known.

While reading, every reference is resolved, i.e. the Reference and the object it points to are both available. References that point to other references are followed, e.g. an operation that refers to a message of a channel which in turn refers to a message of the Components object.

Validating a document

Document.Validate checks the document against the rules of the specification: required fields, enumerations, patterns of keys and addresses, absolute URLs, runtime expressions, as well as the rules that span several objects, e.g. that the messages of an operation "MUST contain a subset of the messages defined in the channel referenced in this operation" (Operation Object).

An error tells where the problem is, e.g. 

channels["userSignedup"].messages["userSignedUp"].contentType: mime: expected slash after first token

Validation also normalizes a document where the specification allows it, e.g. by trimming the whitespace around a description or by adding the https scheme to a URL that is missing one.

Writing a document

Document.ToJSON, Document.ToYAML, Document.WriteJSON, Document.WriteYAML and Document.WriteToFile write the document back. Everything that was read is written back: the order of the keys of every map is preserved, specification extensions are kept where they were, and the definitions of bindings and of schemas in other formats (Avro, Protobuf, ...) are kept as they were given. Document.SortMaps sorts the maps of the document by key if a canonical order is preferred over the original one.

Index

Constants

View Source 
const (
	// SecuritySchemeBearer is the value of SecurityScheme.Scheme for bearer tokens.
	SecuritySchemeBearer = "bearer"
	// SecuritySchemeBasic is the value of SecurityScheme.Scheme for basic authentication.
	SecuritySchemeBasic = "basic"
)

Variables

View Source 
var (
	// ErrServerNotInRoot is returned when a channel of the root Channels Object refers to a
	// server that is not defined in the root Servers Object.
	ErrServerNotInRoot = errors.New("must point to a server of the root servers object")
	// ErrChannelNotInRoot is returned when an operation of the root Operations Object refers to
	// a channel that is not defined in the root Channels Object.
	ErrChannelNotInRoot = errors.New("must point to a channel of the root channels object")
)
View Source 
var ErrEmptyDocument = errors.New("document must contain at least a channels field, an operations field or a components field")

ErrEmptyDocument is thrown if the AsyncAPI document neither defines channels nor operations nor components.

View Source 
var ErrEmptyMessageExample = errors.New("must contain either headers and/or payload")

ErrEmptyMessageExample is returned when a message example neither has headers nor a payload.

View Source 
var ErrMessageNotOfChannel = errors.New("must be a message of the channel of this operation")

ErrMessageNotOfChannel is returned when an operation or an operation reply refers to a message that is not one of the messages of the channel it operates on.

View Source 
var ErrMustBeReference = errors.New("must be a reference object")

ErrMustBeReference is returned when the specification demands a reference object but the object itself was given, e.g. for the channel of an operation: "Please note the `channel` property value MUST be a Reference Object and, therefore, MUST NOT contain a Channel Object." (Specification)

View Source 
var ErrUnknownField = errors.New(`unknown field or extension without "x-" prefix`)

ErrUnknownField is returned when a field is not recognized and also doesn't have a "x-" prefix signifying it is an extension.

Functions

This section is empty.

Types

type AnySchema 

type AnySchema struct {
	// The name of the schema format that is used to define the information.
	// If it is missing, it defaults to an AsyncAPI schema format, i.e. the schema is a [Schema] object.
	SchemaFormat SchemaFormat `json:"schemaFormat,omitempty" yaml:"schemaFormat,omitempty"`
	// The schema as an AsyncAPI Schema Object.
	// It is set if the schema format is missing or denotes an AsyncAPI schema format.
	Schema *Schema `json:"-" yaml:"-"`
	// The schema in a format other than the AsyncAPI Schema Object, e.g. Avro or Protobuf.
	// Non-JSON-based schemas (e.g. Protobuf or XSD) are inlined as a string.
	Raw jsontext.Value `json:"-" yaml:"-"`
	// A Multi Format Schema Object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

AnySchema is a schema definition, wherever the specification allows a Schema object as well as a MultiFormatSchema object.

A Schema Object is equivalent to a Multi Format Schema Object with the default schema format, which is why both are represented by this one type: if no schema format is given, the schema itself is the AsyncAPI schema, otherwise the schema is wrapped in a Multi Format Schema Object. (Specification)

func (*AnySchema) MarshalJSONTo 

func (s *AnySchema) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals either a Schema Object or a Multi Format Schema Object.

func (*AnySchema) SortMaps 

func (s *AnySchema) SortMaps()

SortMaps sorts the maps of the underlying AsyncAPI schema by key.

func (*AnySchema) UnmarshalJSONFrom 

func (s *AnySchema) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals either a Schema Object or a Multi Format Schema Object.

func (*AnySchema) Validate 

func (s *AnySchema) Validate() error

Validate checks the schema for correctness.

type AnySchemaRef 

type AnySchemaRef = refOrValue[AnySchema, *AnySchema]

AnySchemaRef is a reference to a schema or an actual schema.

type AnySchemaRefList 

type AnySchemaRefList []*AnySchemaRef

AnySchemaRefList is a slice of AnySchemaRef.

func (AnySchemaRefList) Validate 

func (ss AnySchemaRefList) Validate() error

Validate validates each schema of the list.

type Binding 

type Binding struct {
	// The protocol-specific definition as defined by the bindings specification.
	Value jsontext.Value
	// contains filtered or unexported fields
}

Binding holds the protocol-specific definitions of a single protocol.

func (*Binding) MarshalJSONTo 

func (b *Binding) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the value of the binding.

func (*Binding) UnmarshalJSONFrom 

func (b *Binding) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the value of the binding.

func (*Binding) Validate 

func (b *Binding) Validate() error

Validate checks that the binding holds a value.

type Bindings 

type Bindings map[Protocol]*Binding

Bindings is a map describing protocol-specific definitions for a server, a channel, an operation or a message.

The keys describe the name of the protocol, the values describe the protocol-specific definitions. The definitions themselves are described by the bindings specification and are therefore kept as raw JSON values. (Specification)

func (Bindings) ByIndex 

func (bs Bindings) ByIndex() iter.Seq2[Protocol, *Binding]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Bindings) MarshalJSONTo 

func (bs *Bindings) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Bindings) Set 

func (bs *Bindings) Set(key Protocol, b *Binding)

Set sets a value in the map, adding it at the end of the order.

func (Bindings) Sort 

func (bs Bindings) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Bindings) UnmarshalJSONFrom 

func (bs *Bindings) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Bindings) Validate 

func (bs Bindings) Validate() error

Validate checks that the protocols are known and that the definitions are valid JSON.

type BindingsByName 

type BindingsByName map[string]*BindingsRef

BindingsByName is a map of bindings objects. (Specification)

func (BindingsByName) ByIndex 

func (bs BindingsByName) ByIndex() iter.Seq2[string, *BindingsRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*BindingsByName) MarshalJSONTo 

func (bs *BindingsByName) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*BindingsByName) Set 

func (bs *BindingsByName) Set(key string, b *BindingsRef)

Set sets a value in the map, adding it at the end of the order.

func (BindingsByName) Sort 

func (bs BindingsByName) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*BindingsByName) UnmarshalJSONFrom 

func (bs *BindingsByName) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (BindingsByName) Validate 

func (bs BindingsByName) Validate() error

Validate validates each bindings object.

type BindingsRef 

type BindingsRef = refOrValue[Bindings, *Bindings]

BindingsRef is a reference to a Bindings object or an actual Bindings object.

type Channel 

type Channel struct {
	// An optional string representation of this channel's address.
	// The address is typically the "topic name", "routing key", "event type", or "path".
	// When null or absent, it MUST be interpreted as unknown.
	// This is useful when the address is generated dynamically at runtime or can't be known upfront.
	// It MAY contain Channel Address Expressions.
	// Query parameters and fragments SHALL NOT be used, instead use bindings to define them.
	Address string `json:"address,omitempty" yaml:"address,omitempty"`
	// A map of the messages that will be sent to this channel by any application at any time.
	// Every message sent to this channel MUST be valid against one, and only one, of the message objects defined in this map.
	Messages Messages `json:"messages,omitempty" yaml:"messages,omitempty"`
	// A human-friendly title for the channel.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short summary of the channel.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// An optional description of this channel. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// An array of $ref pointers to the definition of the servers in which this channel is available.
	// If the channel is located in the root Channels Object, it MUST point to a subset of server definitions located in the root Servers Object.
	// If `servers` is absent or empty, this channel MUST be available on all the servers defined in the Servers Object.
	Servers ServerRefList `json:"servers,omitempty" yaml:"servers,omitempty"`
	// A map of the parameters included in the channel address.
	// It MUST be present only when the address contains Channel Address Expressions.
	Parameters Parameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// A list of tags for logical grouping of channels.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation for this channel.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the channel.
	Bindings *BindingsRef `json:"bindings,omitempty" yaml:"bindings,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Channel describes a shared communication channel. (Specification)

func (*Channel) AddressExpressions 

func (c *Channel) AddressExpressions() []string

AddressExpressions returns the names of the Channel Address Expressions used in the address, i.e. the names of the parameters that are enclosed in curly braces.

func (*Channel) Validate 

func (c *Channel) Validate() error

Validate checks the channel for correctness.

type ChannelRef 

type ChannelRef = refOrValue[Channel, *Channel]

ChannelRef is a reference to a Channel or an actual Channel.

type Channels 

type Channels map[string]*ChannelRef

Channels is an object containing all the Channel Object definitions the application MUST use during runtime.

The key of each entry is an identifier for the described channel. The channel ID is case-sensitive. Tools and libraries MAY use it to uniquely identify a channel, therefore, it is RECOMMENDED to follow common programming naming conventions. (Specification)

func (Channels) ByIndex 

func (cs Channels) ByIndex() iter.Seq2[string, *ChannelRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Channels) MarshalJSONTo 

func (cs *Channels) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Channels) Set 

func (cs *Channels) Set(key string, c *ChannelRef)

Set sets a value in the map, adding it at the end of the order.

func (Channels) Sort 

func (cs Channels) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Channels) UnmarshalJSONFrom 

func (cs *Channels) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Channels) Validate 

func (cs Channels) Validate() error

Validate validates each channel.

type Components 

type Components struct {
	// An object to hold reusable Schema Objects.
	Schemas Schemas `json:"schemas,omitempty" yaml:"schemas,omitempty"`
	// An object to hold reusable Server Objects.
	Servers Servers `json:"servers,omitempty" yaml:"servers,omitempty"`
	// An object to hold reusable Channel Objects.
	Channels Channels `json:"channels,omitempty" yaml:"channels,omitempty"`
	// An object to hold reusable Operation Objects.
	Operations Operations `json:"operations,omitempty" yaml:"operations,omitempty"`
	// An object to hold reusable Message Objects.
	Messages Messages `json:"messages,omitempty" yaml:"messages,omitempty"`
	// An object to hold reusable Security Scheme Objects.
	SecuritySchemes SecuritySchemes `json:"securitySchemes,omitempty" yaml:"securitySchemes,omitempty"`
	// An object to hold reusable Server Variable Objects.
	ServerVariables ServerVariables `json:"serverVariables,omitempty" yaml:"serverVariables,omitempty"`
	// An object to hold reusable Parameter Objects.
	Parameters Parameters `json:"parameters,omitempty" yaml:"parameters,omitempty"`
	// An object to hold reusable Correlation ID Objects.
	CorrelationIDs CorrelationIDs `json:"correlationIds,omitempty" yaml:"correlationIds,omitempty"`
	// An object to hold reusable Operation Reply Objects.
	Replies Replies `json:"replies,omitempty" yaml:"replies,omitempty"`
	// An object to hold reusable Operation Reply Address Objects.
	ReplyAddresses ReplyAddresses `json:"replyAddresses,omitempty" yaml:"replyAddresses,omitempty"`
	// An object to hold reusable External Documentation Objects.
	ExternalDocs ExternalDocsByName `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// An object to hold reusable Tag Objects.
	Tags TagsByName `json:"tags,omitempty" yaml:"tags,omitempty"`
	// An object to hold reusable Operation Trait Objects.
	OperationTraits OperationTraits `json:"operationTraits,omitempty" yaml:"operationTraits,omitempty"`
	// An object to hold reusable Message Trait Objects.
	MessageTraits MessageTraits `json:"messageTraits,omitempty" yaml:"messageTraits,omitempty"`
	// An object to hold reusable Server Bindings Objects.
	ServerBindings BindingsByName `json:"serverBindings,omitempty" yaml:"serverBindings,omitempty"`
	// An object to hold reusable Channel Bindings Objects.
	ChannelBindings BindingsByName `json:"channelBindings,omitempty" yaml:"channelBindings,omitempty"`
	// An object to hold reusable Operation Bindings Objects.
	OperationBindings BindingsByName `json:"operationBindings,omitempty" yaml:"operationBindings,omitempty"`
	// An object to hold reusable Message Bindings Objects.
	MessageBindings BindingsByName `json:"messageBindings,omitempty" yaml:"messageBindings,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Components holds a set of reusable objects for different aspects of the AsyncAPI specification. All objects defined within the components object will have no effect on the API unless they are explicitly referenced from properties outside the components object. (Specification)

All the fixed fields are objects that MUST use keys that match the regular expression: 

^[a-zA-Z0-9\.\-_]+$

Field name examples: 

User
User_1
User_Name
user-name
my.org.User

func (*Components) SortMaps 

func (c *Components) SortMaps()

SortMaps sorts each field that is a map by key.

func (*Components) Validate 

func (c *Components) Validate() error

Validate checks the components object for correctness.

type Contact 

type Contact struct {
	// The identifying name of the contact person/organization.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// The URL pointing to the contact information. This MUST be in the form of an absolute URL.
	URL *url.URL `json:"url,omitempty" yaml:"url,omitempty"`
	// The email address of the contact person/organization. MUST be in the format of an email address.
	Email types.Email `json:"email,omitempty" yaml:"email,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Contact information for the exposed API. (Specification)

func (*Contact) Validate 

func (c *Contact) Validate() error

Validate checks the contact for consistency.

type CorrelationID 

type CorrelationID struct {
	// An optional description of the identifier. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// REQUIRED. A runtime expression that specifies the location of the correlation ID.
	Location RuntimeExpression `json:"location" yaml:"location"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

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

For specifying and computing the location of a Correlation ID, a RuntimeExpression is used. (Specification)

func (*CorrelationID) Validate 

func (c *CorrelationID) Validate() error

Validate checks the correlation ID for correctness.

type CorrelationIDRef 

type CorrelationIDRef = refOrValue[CorrelationID, *CorrelationID]

CorrelationIDRef is a reference to a CorrelationID or an actual CorrelationID.

type CorrelationIDs 

type CorrelationIDs map[string]*CorrelationIDRef

CorrelationIDs is a map of Correlation ID Objects. (Specification)

func (CorrelationIDs) ByIndex 

func (cs CorrelationIDs) ByIndex() iter.Seq2[string, *CorrelationIDRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*CorrelationIDs) MarshalJSONTo 

func (cs *CorrelationIDs) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*CorrelationIDs) Set 

func (cs *CorrelationIDs) Set(key string, c *CorrelationIDRef)

Set sets a value in the map, adding it at the end of the order.

func (CorrelationIDs) Sort 

func (cs CorrelationIDs) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*CorrelationIDs) UnmarshalJSONFrom 

func (cs *CorrelationIDs) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (CorrelationIDs) Validate 

func (cs CorrelationIDs) Validate() error

Validate validates each correlation ID.

type DataType 

type DataType string

DataType is the type of a schema, based on the types supported by the JSON Schema Specification Draft 07. (Specification) 

const (
	// TypeInteger is a JSON number without a fraction or exponent part. Format: int32, int64
	TypeInteger DataType = "integer"
	// TypeNumber is a JSON number. Format: float, double
	TypeNumber DataType = "number"
	// TypeString is a JSON string. Format: byte, binary, date, date-time, password
	TypeString DataType = "string"
	// TypeArray is a JSON array.
	TypeArray DataType = "array"
	// TypeBoolean is a JSON boolean.
	TypeBoolean DataType = "boolean"
	// TypeObject is a JSON object.
	TypeObject DataType = "object"
	// TypeNull is the JSON null value.
	TypeNull DataType = "null"
)

func (DataType) Validate 

func (d DataType) Validate() error

Validate validates the data type.

type DataTypes 

type DataTypes []DataType

DataTypes is the value of the `type` keyword of a schema.

JSON Schema allows a single type as well as a list of types, e.g. `"type": "string"` and `"type": ["string", "null"]` are both valid. A single type is marshalled back as a single type, not as a list.

func (DataTypes) Contains 

func (ds DataTypes) Contains(d DataType) bool

Contains reports whether the schema is of the given type.

func (*DataTypes) MarshalJSONTo 

func (ds *DataTypes) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals a single type as a string and multiple types as a list.

func (DataTypes) String 

func (ds DataTypes) String() string

String returns the types as a comma-separated list.

func (*DataTypes) UnmarshalJSONFrom 

func (ds *DataTypes) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals either a single type or a list of types.

func (DataTypes) Validate 

func (ds DataTypes) Validate() error

Validate validates each data type.

type Document 

type Document struct {
	// REQUIRED. Specifies the AsyncAPI Specification version being used.
	// It can be used by tooling Specifications and clients to interpret the version.
	// The structure shall be `major`.`minor`.`patch`, where `patch` versions MUST be compatible
	// with the existing `major`.`minor` tooling.
	AsyncAPI string `json:"asyncapi" yaml:"asyncapi"`
	// Identifier of the application the AsyncAPI document is defining.
	// It must conform to the URI format.
	// It is RECOMMENDED to use a URN to globally and uniquely identify the application
	// during long periods of time, even after it becomes unavailable or ceases to exist.
	ID *url.URL `json:"id,omitempty" yaml:"id,omitempty"`
	// REQUIRED. Provides metadata about the API. The metadata can be used by the clients if needed.
	Info *Info `json:"info,omitempty" yaml:"info,omitempty"`
	// Provides connection details of servers.
	Servers Servers `json:"servers,omitempty" yaml:"servers,omitempty"`
	// Default content type to use when encoding/decoding a message's payload.
	// The value MUST be a specific media type (e.g. `application/json`).
	// This value MUST be used by schema parsers when the contentType property is omitted.
	DefaultContentType MediaType `json:"defaultContentType,omitempty" yaml:"defaultContentType,omitempty"`
	// The channels used by this application.
	Channels Channels `json:"channels,omitempty" yaml:"channels,omitempty"`
	// The operations this application MUST implement.
	Operations Operations `json:"operations,omitempty" yaml:"operations,omitempty"`
	// An element to hold various reusable objects for the specification.
	// Everything that is defined inside this object represents a resource that MAY or MAY NOT be
	// used in the rest of the document and MAY or MAY NOT be used by the implemented application.
	Components Components `json:"components,omitzero" yaml:"components,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Document is an AsyncAPI document, the root object. It combines resource listing and API declaration together into one document. (Specification)

func LoadFromData 

func LoadFromData(data []byte) (*Document, error)

LoadFromData reads an AsyncAPI specification from a byte array and parses it into a structured format.

func LoadFromDataJSON 

func LoadFromDataJSON(data []byte) (*Document, error)

LoadFromDataJSON reads an AsyncAPI specification from a byte array in JSON format and parses it into a structured format.

func LoadFromDataYAML 

func LoadFromDataYAML(data []byte) (*Document, error)

LoadFromDataYAML reads an AsyncAPI specification from a byte array in YAML format and parses it into a structured format.

func LoadFromFile 

func LoadFromFile(location string) (*Document, error)

LoadFromFile reads an AsyncAPI specification from a file and parses it into a structured format.

func LoadFromReader 

func LoadFromReader(r io.Reader) (*Document, error)

LoadFromReader reads an AsyncAPI specification from an io.Reader and parses it into a structured format. It will try to determine the format of the data and load it accordingly. If you know the format of the data, use LoadFromReaderJSON or LoadFromReaderYAML instead.

func (*Document) SortMaps 

func (d *Document) SortMaps()

SortMaps sorts the servers, channels, operations and the fields of the components that are maps by key.

func (*Document) ToJSON 

func (d *Document) ToJSON() ([]byte, error)

ToJSON marshals the document into JSON.

func (*Document) ToYAML 

func (d *Document) ToYAML() ([]byte, error)

ToYAML marshals the document into YAML.

func (*Document) Validate 

func (d *Document) Validate() error

Validate checks the AsyncAPI document for correctness.

func (Document) WriteJSON 

func (d Document) WriteJSON(w io.Writer) error

WriteJSON writes the document in JSON format to the given writer.

"An AsyncAPI document can be JSON or YAML format." (Specification)

func (*Document) WriteToFile 

func (d *Document) WriteToFile(path string) error

WriteToFile writes the document to a file, in JSON or in YAML format, depending on the extension of the given path.

func (Document) WriteYAML 

func (d Document) WriteYAML(w io.Writer) error

WriteYAML writes the document in YAML format to the given writer.

"An AsyncAPI document can be JSON or YAML format. [...] In order to preserve the ability to round-trip between YAML and JSON formats, YAML version 1.2 is RECOMMENDED along with some additional constraints." (Specification)

type Extensions 

type Extensions = jsontext.Value

Extensions represents additional fields that can be added to AsyncAPI objects.

While the AsyncAPI Specification tries to accommodate most use cases, additional data can be added to extend the specification at certain points.

The extensions properties are implemented as patterned fields that are always prefixed by `x-`, for example, x-internal-id. The value can be null, a primitive, an array or an object. (Specification)

It is here an alias of jsontext.Value to allow inlining within structs, enabling seamless marshalling and unmarshalling. Using jsontext.Value preserves the order of fields, preventing unnecessary changes when parsing and writing AsyncAPI specifications. Although a map could be used, it doesn't maintain the order, leading to potential inconsistencies in the output. Custom marshalling for an inlined object is not possible, which prevents the use of an ordered map.

Note: For convenience, certain common extensions are implemented as fields directly within the respective structs.

type ExternalDocs 

type ExternalDocs struct {
	// A short description of the target documentation. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// REQUIRED. The URL for the target documentation. This MUST be in the form of an absolute URL.
	URL *url.URL `json:"url,omitempty" yaml:"url,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

ExternalDocs allows referencing an external resource for extended documentation. (Specification)

func (*ExternalDocs) Validate 

func (ed *ExternalDocs) Validate() error

Validate checks the external documentation for consistency.

type ExternalDocsByName 

type ExternalDocsByName map[string]*ExternalDocsRef

ExternalDocsByName is a map of External Documentation Objects. (Specification)

func (ExternalDocsByName) ByIndex 

func (ds ExternalDocsByName) ByIndex() iter.Seq2[string, *ExternalDocsRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*ExternalDocsByName) MarshalJSONTo 

func (ds *ExternalDocsByName) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*ExternalDocsByName) Set 

func (ds *ExternalDocsByName) Set(key string, d *ExternalDocsRef)

Set sets a value in the map, adding it at the end of the order.

func (ExternalDocsByName) Sort 

func (ds ExternalDocsByName) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*ExternalDocsByName) UnmarshalJSONFrom 

func (ds *ExternalDocsByName) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (ExternalDocsByName) Validate 

func (ds ExternalDocsByName) Validate() error

Validate validates each external documentation object.

type ExternalDocsRef 

type ExternalDocsRef = refOrValue[ExternalDocs, *ExternalDocs]

ExternalDocsRef is a reference to an ExternalDocs or an actual ExternalDocs.

type Format 

type Format string

Format defines additional formats to provide fine detail for primitive data types.

The format property is an open string-valued property, and can have any value to support documentation needs, so an unknown format is not an error. (Specification) 

const (
	// FormatInt32 represents a signed 32 bits integer.
	FormatInt32 Format = "int32"
	// FormatInt64 represents a signed 64 bits integer.
	FormatInt64 Format = "int64"
	// FormatFloat represents a float number.
	FormatFloat Format = "float"
	// FormatDouble represents a double number.
	FormatDouble Format = "double"
	// FormatByte represents base64 encoded characters.
	FormatByte Format = "byte"
	// FormatBinary represents any sequence of octets.
	FormatBinary Format = "binary"
	// FormatDate represents a date as defined by full-date in RFC3339.
	FormatDate Format = "date"
	// FormatDateTime represents a date-time as defined by date-time in RFC3339.
	FormatDateTime Format = "date-time"
	// FormatPassword is a hint to UIs that the input needs to be obscured.
	FormatPassword Format = "password"
)

func (Format) IsKnown 

func (f Format) IsKnown() bool

IsKnown reports whether the format is one of the formats defined by the AsyncAPI Specification.

Formats such as "email" or "uuid" can be used even though they are not defined by the specification, so a format that is not known is not necessarily invalid.

type Info 

type Info struct {
	// REQUIRED. The title of the application.
	Title string `json:"title" yaml:"title"`
	// REQUIRED. Provides the version of the application API (not to be confused with the specification version).
	Version string `json:"version" yaml:"version"`
	// A short description of the application. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A URL to the Terms of Service for the API. This MUST be in the form of an absolute URL.
	TermsOfService *url.URL `json:"termsOfService,omitempty" yaml:"termsOfService,omitempty"`
	// The contact information for the exposed API.
	Contact *Contact `json:"contact,omitempty" yaml:"contact,omitempty"`
	// The license information for the exposed API.
	License *License `json:"license,omitempty" yaml:"license,omitempty"`
	// A list of tags for application API documentation control. Tags can be used for logical grouping of applications.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation of the exposed API.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

The Info object provides metadata about the API. The metadata can be used by the clients if needed. (Specification)

func (*Info) Validate 

func (i *Info) Validate() error

Validate checks the info object for correctness.

type License 

type License struct {
	// REQUIRED. The license name used for the API.
	Name string `json:"name" yaml:"name"`
	// A URL to the license used for the API. This MUST be in the form of an absolute URL.
	URL *url.URL `json:"url,omitempty" yaml:"url,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

License information for the exposed API. (Specification)

func (*License) Validate 

func (l *License) Validate() error

Validate checks the license for correctness.

type MapOfStrings 

type MapOfStrings map[string]String

MapOfStrings is an ordered map of strings, e.g. the available scopes of an OAuth flow, which are "a map between the scope name and a short description for it". (Specification)

func (MapOfStrings) ByIndex 

func (ss MapOfStrings) ByIndex() iter.Seq2[string, String]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*MapOfStrings) MarshalJSONTo 

func (ss *MapOfStrings) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*MapOfStrings) Set 

func (ss *MapOfStrings) Set(key string, s String)

Set sets a value in the map, adding it at the end of the order.

func (MapOfStrings) Sort 

func (ss MapOfStrings) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*MapOfStrings) UnmarshalJSONFrom 

func (ss *MapOfStrings) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

type MediaType 

type MediaType string

MediaType is "the content type to use when encoding/decoding a message's payload. The value MUST be a specific media type (e.g. `application/json`)." (Specification) 

const (
	// MediaTypeJSON is the media type for JSON payloads.
	MediaTypeJSON MediaType = "application/json"
	// MediaTypeYAML is the media type for YAML payloads.
	MediaTypeYAML MediaType = "application/yaml"
	// MediaTypeAvro is the media type for Avro payloads.
	MediaTypeAvro MediaType = "avro/binary"
	// MediaTypeProtobuf is the media type for Protocol Buffers payloads.
	MediaTypeProtobuf MediaType = "application/protobuf"
	// MediaTypeText is the media type for plain text payloads.
	MediaTypeText MediaType = "text/plain"
)

func (MediaType) Validate 

func (mt MediaType) Validate() error

Validate checks that the media type is well-formed.

type Message 

type Message struct {
	// Schema definition of the application headers. Schema MUST be a map of key-value pairs.
	// It MUST NOT define the protocol headers.
	Headers *AnySchemaRef `json:"headers,omitempty" yaml:"headers,omitempty"`
	// Definition of the message payload.
	Payload *AnySchemaRef `json:"payload,omitempty" yaml:"payload,omitempty"`
	// Definition of the correlation ID used for message tracing or matching.
	CorrelationID *CorrelationIDRef `json:"correlationId,omitempty" yaml:"correlationId,omitempty"`
	// The content type to use when encoding/decoding a message's payload.
	// When omitted, the value MUST be the one specified on the defaultContentType field of the document.
	ContentType MediaType `json:"contentType,omitempty" yaml:"contentType,omitempty"`
	// A machine-friendly name for the message.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// A human-friendly title for the message.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short summary of what the message is about.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A verbose explanation of the message. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A list of tags for logical grouping and categorization of messages.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation for this message.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message.
	Bindings *BindingsRef `json:"bindings,omitempty" yaml:"bindings,omitempty"`
	// List of examples.
	Examples MessageExamples `json:"examples,omitempty" yaml:"examples,omitempty"`
	// A list of traits to apply to the message object.
	// Traits MUST be merged using the traits merge mechanism.
	// The resulting object MUST be a valid Message Object.
	Traits MessageTraitList `json:"traits,omitempty" yaml:"traits,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Message describes a message received on a given channel and operation. (Specification)

func (*Message) Validate 

func (m *Message) Validate() error

Validate checks the message for correctness.

type MessageExample 

type MessageExample struct {
	// The value of this field MUST validate against the headers of the message.
	Headers jsontext.Value `json:"headers,omitempty" yaml:"headers,omitempty"`
	// The value of this field MUST validate against the payload of the message.
	Payload jsontext.Value `json:"payload,omitempty" yaml:"payload,omitempty"`
	// A machine-friendly name.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// A short summary of what the example is about.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

MessageExample represents an example of a Message object and MUST contain either headers and/or payload fields. (Specification)

func (*MessageExample) Validate 

func (ex *MessageExample) Validate() error

Validate checks the message example for correctness.

type MessageExamples 

type MessageExamples []*MessageExample

MessageExamples is a list of examples of a message.

func (MessageExamples) Validate 

func (exs MessageExamples) Validate() error

Validate validates each example.

type MessageRef 

type MessageRef = refOrValue[Message, *Message]

MessageRef is a reference to a Message or an actual Message.

type MessageRefList 

type MessageRefList []*MessageRef

MessageRefList is a slice of MessageRef.

func (MessageRefList) Validate 

func (ms MessageRefList) Validate() error

Validate validates each message of the list and makes sure they are references.

type MessageTrait 

type MessageTrait struct {
	// Schema definition of the application headers. Schema MUST be a map of key-value pairs.
	// It MUST NOT define the protocol headers.
	Headers *AnySchemaRef `json:"headers,omitempty" yaml:"headers,omitempty"`
	// Definition of the correlation ID used for message tracing or matching.
	CorrelationID *CorrelationIDRef `json:"correlationId,omitempty" yaml:"correlationId,omitempty"`
	// The content type to use when encoding/decoding a message's payload.
	// When omitted, the value MUST be the one specified on the defaultContentType field of the document.
	ContentType MediaType `json:"contentType,omitempty" yaml:"contentType,omitempty"`
	// A machine-friendly name for the message.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// A human-friendly title for the message.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short summary of what the message is about.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A verbose explanation of the message. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A list of tags for logical grouping and categorization of messages.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation for this message.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the message.
	Bindings *BindingsRef `json:"bindings,omitempty" yaml:"bindings,omitempty"`
	// List of examples.
	Examples MessageExamples `json:"examples,omitempty" yaml:"examples,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

MessageTrait describes a trait that MAY be applied to a Message object. This object MAY contain any property from the Message object, except `payload` and `traits`.

If you're looking to apply traits to an operation, see the OperationTrait object. (Specification)

func (*MessageTrait) Validate 

func (t *MessageTrait) Validate() error

Validate checks the message trait for correctness.

type MessageTraitList 

type MessageTraitList []*MessageTraitRef

MessageTraitList is a slice of MessageTraitRef.

func (MessageTraitList) Validate 

func (ts MessageTraitList) Validate() error

Validate validates each message trait of the list.

type MessageTraitRef 

type MessageTraitRef = refOrValue[MessageTrait, *MessageTrait]

MessageTraitRef is a reference to a MessageTrait or an actual MessageTrait.

type MessageTraits 

type MessageTraits map[string]*MessageTraitRef

MessageTraits is a map of Message Trait Objects. (Specification)

func (MessageTraits) ByIndex 

func (ts MessageTraits) ByIndex() iter.Seq2[string, *MessageTraitRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*MessageTraits) MarshalJSONTo 

func (ts *MessageTraits) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*MessageTraits) Set 

func (ts *MessageTraits) Set(key string, t *MessageTraitRef)

Set sets a value in the map, adding it at the end of the order.

func (MessageTraits) Sort 

func (ts MessageTraits) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*MessageTraits) UnmarshalJSONFrom 

func (ts *MessageTraits) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (MessageTraits) Validate 

func (ts MessageTraits) Validate() error

Validate validates each message trait.

type Messages 

type Messages map[string]*MessageRef

Messages describes a map of messages included in a channel.

The key of each entry represents the message identifier. It is case-sensitive. Tools and libraries MAY use it to uniquely identify a message, therefore, it is RECOMMENDED to follow common programming naming conventions. (Specification)

func (Messages) ByIndex 

func (ms Messages) ByIndex() iter.Seq2[string, *MessageRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Messages) MarshalJSONTo 

func (ms *Messages) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Messages) Set 

func (ms *Messages) Set(key string, m *MessageRef)

Set sets a value in the map, adding it at the end of the order.

func (Messages) Sort 

func (ms Messages) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Messages) UnmarshalJSONFrom 

func (ms *Messages) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Messages) Validate 

func (ms Messages) Validate() error

Validate validates each message.

type MultiFormatSchema 

type MultiFormatSchema struct {
	// REQUIRED. A string containing the name of the schema format that is used to define the information.
	SchemaFormat SchemaFormat `json:"schemaFormat" yaml:"schemaFormat"`
	// REQUIRED. Definition of the message payload.
	// It can be of any type but defaults to a Schema Object.
	Schema jsontext.Value `json:"schema" yaml:"schema"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

MultiFormatSchema represents a schema definition in a specific schema format. It is the wire format of an AnySchema that has a schema format. (Specification)

type OAuthFlowAuthorizationCode 

type OAuthFlowAuthorizationCode struct {
	// REQUIRED. The authorization URL to be used for this flow. This MUST be in the form of an absolute URL.
	AuthorizationURL *url.URL `json:"authorizationUrl" yaml:"authorizationUrl"`
	// REQUIRED. The token URL to be used for this flow. This MUST be in the form of an absolute URL.
	TokenURL *url.URL `json:"tokenUrl" yaml:"tokenUrl"`
	// The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL.
	RefreshURL *url.URL `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
	// REQUIRED. The available scopes for the OAuth2 security scheme.
	// A map between the scope name and a short description for it.
	AvailableScopes MapOfStrings `json:"availableScopes" yaml:"availableScopes"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OAuthFlowAuthorizationCode holds the configuration details for the OAuth Authorization Code flow. (Specification)

func (*OAuthFlowAuthorizationCode) Validate 

func (f *OAuthFlowAuthorizationCode) Validate() error

Validate checks the OAuth flow for correctness.

type OAuthFlowClientCredentials 

type OAuthFlowClientCredentials = OAuthFlowPassword

OAuthFlowClientCredentials holds the configuration details for the OAuth Client Credentials flow.

type OAuthFlowImplicit 

type OAuthFlowImplicit struct {
	// REQUIRED. The authorization URL to be used for this flow. This MUST be in the form of an absolute URL.
	AuthorizationURL *url.URL `json:"authorizationUrl" yaml:"authorizationUrl"`
	// The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL.
	RefreshURL *url.URL `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
	// REQUIRED. The available scopes for the OAuth2 security scheme.
	// A map between the scope name and a short description for it.
	AvailableScopes MapOfStrings `json:"availableScopes" yaml:"availableScopes"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OAuthFlowImplicit holds the configuration details for the OAuth Implicit flow. (Specification)

func (*OAuthFlowImplicit) Validate 

func (f *OAuthFlowImplicit) Validate() error

Validate checks the OAuth flow for correctness.

type OAuthFlowPassword 

type OAuthFlowPassword struct {
	// REQUIRED. The token URL to be used for this flow. This MUST be in the form of an absolute URL.
	TokenURL *url.URL `json:"tokenUrl" yaml:"tokenUrl"`
	// The URL to be used for obtaining refresh tokens. This MUST be in the form of an absolute URL.
	RefreshURL *url.URL `json:"refreshUrl,omitempty" yaml:"refreshUrl,omitempty"`
	// REQUIRED. The available scopes for the OAuth2 security scheme.
	// A map between the scope name and a short description for it.
	AvailableScopes MapOfStrings `json:"availableScopes" yaml:"availableScopes"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OAuthFlowPassword holds the configuration details for the OAuth Resource Owner Protected Credentials flow. (Specification)

func (*OAuthFlowPassword) Validate 

func (f *OAuthFlowPassword) Validate() error

Validate checks the OAuth flow for correctness.

type OAuthFlows 

type OAuthFlows struct {
	// Configuration for the OAuth Implicit flow.
	Implicit *OAuthFlowImplicit `json:"implicit,omitempty" yaml:"implicit,omitempty"`
	// Configuration for the OAuth Resource Owner Protected Credentials flow.
	Password *OAuthFlowPassword `json:"password,omitempty" yaml:"password,omitempty"`
	// Configuration for the OAuth Client Credentials flow.
	ClientCredentials *OAuthFlowClientCredentials `json:"clientCredentials,omitempty" yaml:"clientCredentials,omitempty"`
	// Configuration for the OAuth Authorization Code flow.
	AuthorizationCode *OAuthFlowAuthorizationCode `json:"authorizationCode,omitempty" yaml:"authorizationCode,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OAuthFlows allows configuration of the supported OAuth Flows. (Specification)

func (*OAuthFlows) Validate 

func (f *OAuthFlows) Validate() error

Validate checks the OAuth flows for correctness.

type Operation 

type Operation struct {
	// REQUIRED. Use `send` when it's expected that the application will send a message to the given channel,
	// and `receive` when the application should expect receiving messages from the given channel.
	Action OperationAction `json:"action" yaml:"action"`
	// REQUIRED. A $ref pointer to the definition of the channel in which this operation is performed.
	// If the operation is located in the root Operations Object, it MUST point to a channel definition located in the root Channels Object.
	Channel *ChannelRef `json:"channel" yaml:"channel"`
	// A human-friendly title for the operation.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short summary of what the operation is about.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A verbose explanation of the operation. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A declaration of which security schemes are associated with this operation.
	// Only one of the security scheme objects MUST be satisfied to authorize an operation.
	// In cases where server security also applies, it MUST also be satisfied.
	Security SecuritySchemeRefList `json:"security,omitempty" yaml:"security,omitempty"`
	// A list of tags for logical grouping and categorization of operations.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation for this operation.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
	Bindings *BindingsRef `json:"bindings,omitempty" yaml:"bindings,omitempty"`
	// A list of traits to apply to the operation object.
	// Traits MUST be merged using the traits merge mechanism.
	// The resulting object MUST be a valid Operation Object.
	Traits OperationTraitList `json:"traits,omitempty" yaml:"traits,omitempty"`
	// A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation.
	// It MUST contain a subset of the messages defined in the channel referenced in this operation.
	//
	// Note: excluding this property from the operation implies that all messages from the channel will be included.
	// Explicitly set it to an empty, non-nil list if this operation should contain no messages.
	Messages MessageRefList `json:"messages,omitempty" yaml:"messages,omitempty"`
	// The definition of the reply in a request-reply operation.
	Reply *OperationReplyRef `json:"reply,omitempty" yaml:"reply,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Operation describes a specific operation. (Specification)

func (*Operation) Validate 

func (o *Operation) Validate() error

Validate checks the operation for correctness.

type OperationAction 

type OperationAction string

OperationAction describes whether the application sends messages to a channel or receives messages from it. (Specification) 

const (
	// OperationActionSend is used when it's expected that the application will send a message to the given channel.
	OperationActionSend OperationAction = "send"
	// OperationActionReceive is used when the application should expect receiving messages from the given channel.
	OperationActionReceive OperationAction = "receive"
)

func (OperationAction) Validate 

func (a OperationAction) Validate() error

Validate validates the operation action.

type OperationRef 

type OperationRef = refOrValue[Operation, *Operation]

OperationRef is a reference to an Operation or an actual Operation.

type OperationReply 

type OperationReply struct {
	// Definition of the address that implementations MUST use for the reply.
	Address *OperationReplyAddressRef `json:"address,omitempty" yaml:"address,omitempty"`
	// A $ref pointer to the definition of the channel in which this operation is performed.
	// When address is specified, the address property of the channel referenced by this property MUST be either null or not defined.
	Channel *ChannelRef `json:"channel,omitempty" yaml:"channel,omitempty"`
	// A list of $ref pointers pointing to the supported Message Objects that can be processed by this operation as reply.
	// It MUST contain a subset of the messages defined in the channel referenced in this operation reply.
	Messages MessageRefList `json:"messages,omitempty" yaml:"messages,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OperationReply describes the reply part that MAY be applied to an Operation object. If an operation implements the request/reply pattern, the reply object represents the response message. (Specification)

func (*OperationReply) Validate 

func (r *OperationReply) Validate() error

Validate checks the operation reply for correctness.

type OperationReplyAddress 

type OperationReplyAddress struct {
	// An optional description of the address. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// REQUIRED. A runtime expression that specifies the location of the reply address.
	Location RuntimeExpression `json:"location" yaml:"location"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OperationReplyAddress is an object that specifies where an operation has to send the reply.

For specifying and computing the location of a reply address, a RuntimeExpression is used. (Specification)

func (*OperationReplyAddress) Validate 

func (a *OperationReplyAddress) Validate() error

Validate checks the reply address for correctness.

type OperationReplyAddressRef 

type OperationReplyAddressRef = refOrValue[OperationReplyAddress, *OperationReplyAddress]

OperationReplyAddressRef is a reference to an OperationReplyAddress or an actual OperationReplyAddress.

type OperationReplyRef 

type OperationReplyRef = refOrValue[OperationReply, *OperationReply]

OperationReplyRef is a reference to an OperationReply or an actual OperationReply.

type OperationTrait 

type OperationTrait struct {
	// A human-friendly title for the operation.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short summary of what the operation is about.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A verbose explanation of the operation. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A declaration of which security schemes are associated with this operation.
	Security SecuritySchemeRefList `json:"security,omitempty" yaml:"security,omitempty"`
	// A list of tags for logical grouping and categorization of operations.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation for this operation.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the operation.
	Bindings *BindingsRef `json:"bindings,omitempty" yaml:"bindings,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

OperationTrait describes a trait that MAY be applied to an Operation object. This object MAY contain any property from the Operation object, except the `action`, `channel`, `messages` and `traits` ones.

If you're looking to apply traits to a message, see the MessageTrait object. (Specification)

func (*OperationTrait) Validate 

func (t *OperationTrait) Validate() error

Validate checks the operation trait for correctness.

type OperationTraitList 

type OperationTraitList []*OperationTraitRef

OperationTraitList is a slice of OperationTraitRef.

func (OperationTraitList) Validate 

func (ts OperationTraitList) Validate() error

Validate validates each operation trait of the list.

type OperationTraitRef 

type OperationTraitRef = refOrValue[OperationTrait, *OperationTrait]

OperationTraitRef is a reference to an OperationTrait or an actual OperationTrait.

type OperationTraits 

type OperationTraits map[string]*OperationTraitRef

OperationTraits is a map of Operation Trait Objects. (Specification)

func (OperationTraits) ByIndex 

func (ts OperationTraits) ByIndex() iter.Seq2[string, *OperationTraitRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*OperationTraits) MarshalJSONTo 

func (ts *OperationTraits) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*OperationTraits) Set 

func (ts *OperationTraits) Set(key string, t *OperationTraitRef)

Set sets a value in the map, adding it at the end of the order.

func (OperationTraits) Sort 

func (ts OperationTraits) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*OperationTraits) UnmarshalJSONFrom 

func (ts *OperationTraits) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (OperationTraits) Validate 

func (ts OperationTraits) Validate() error

Validate validates each operation trait.

type Operations 

type Operations map[string]*OperationRef

Operations holds a dictionary with all the operations this application MUST implement.

The key of each entry MUST be a string used to identify the operation in the document where it is defined, and its value is case-sensitive. Tools and libraries MAY use it to uniquely identify an operation, therefore, it is RECOMMENDED to follow common programming naming conventions. (Specification)

func (Operations) ByIndex 

func (ops Operations) ByIndex() iter.Seq2[string, *OperationRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Operations) MarshalJSONTo 

func (ops *Operations) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Operations) Set 

func (ops *Operations) Set(key string, o *OperationRef)

Set sets a value in the map, adding it at the end of the order.

func (Operations) Sort 

func (ops Operations) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Operations) UnmarshalJSONFrom 

func (ops *Operations) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Operations) Validate 

func (ops Operations) Validate() error

Validate validates each operation.

type Parameter 

type Parameter struct {
	// An enumeration of string values to be used if the substitution options are from a limited set.
	Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"`
	// The default value to use for substitution, and to send, if an alternate value is not supplied.
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// An optional description for the parameter. CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// An array of examples of the parameter value.
	Examples []string `json:"examples,omitempty" yaml:"examples,omitempty"`
	// A runtime expression that specifies the location of the parameter value.
	Location RuntimeExpression `json:"location,omitempty" yaml:"location,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Parameter describes a parameter included in a channel address. (Specification)

func (*Parameter) Validate 

func (p *Parameter) Validate() error

Validate checks the parameter for correctness.

type ParameterRef 

type ParameterRef = refOrValue[Parameter, *Parameter]

ParameterRef is a reference to a Parameter or an actual Parameter.

type Parameters 

type Parameters map[string]*ParameterRef

Parameters describes a map of parameters included in a channel address.

This map MUST contain all the parameters used in the parent channel address. (Specification)

func (Parameters) ByIndex 

func (ps Parameters) ByIndex() iter.Seq2[string, *ParameterRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Parameters) MarshalJSONTo 

func (ps *Parameters) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Parameters) Set 

func (ps *Parameters) Set(key string, p *ParameterRef)

Set sets a value in the map, adding it at the end of the order.

func (Parameters) Sort 

func (ps Parameters) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Parameters) UnmarshalJSONFrom 

func (ps *Parameters) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Parameters) Validate 

func (ps Parameters) Validate() error

Validate validates each parameter.

type Protocol 

type Protocol string

Protocol is the protocol a server supports for connection, respectively the name of the protocol a binding applies to. 

const (
	// ProtocolHTTP is the HTTP protocol.
	ProtocolHTTP Protocol = "http"
	// ProtocolWebSockets is the WebSockets protocol.
	ProtocolWebSockets Protocol = "ws"
	// ProtocolKafka is the Kafka protocol.
	ProtocolKafka Protocol = "kafka"
	// ProtocolAnypointMQ is the Anypoint MQ protocol.
	ProtocolAnypointMQ Protocol = "anypointmq"
	// ProtocolAMQP is the AMQP 0-9-1 protocol.
	ProtocolAMQP Protocol = "amqp"
	// ProtocolAMQP1 is the AMQP 1.0 protocol.
	ProtocolAMQP1 Protocol = "amqp1"
	// ProtocolMQTT is the MQTT protocol.
	ProtocolMQTT Protocol = "mqtt"
	// ProtocolMQTT5 is the MQTT 5 protocol.
	ProtocolMQTT5 Protocol = "mqtt5"
	// ProtocolNATS is the NATS protocol.
	ProtocolNATS Protocol = "nats"
	// ProtocolJMS is the JMS protocol.
	ProtocolJMS Protocol = "jms"
	// ProtocolSNS is the SNS protocol.
	ProtocolSNS Protocol = "sns"
	// ProtocolSolace is the Solace protocol.
	ProtocolSolace Protocol = "solace"
	// ProtocolSQS is the SQS protocol.
	ProtocolSQS Protocol = "sqs"
	// ProtocolSTOMP is the STOMP protocol.
	ProtocolSTOMP Protocol = "stomp"
	// ProtocolRedis is the Redis protocol.
	ProtocolRedis Protocol = "redis"
	// ProtocolMercure is the Mercure protocol.
	ProtocolMercure Protocol = "mercure"
	// ProtocolIBMMQ is the IBM MQ protocol.
	ProtocolIBMMQ Protocol = "ibmmq"
	// ProtocolGooglePubSub is the Google Cloud Pub/Sub protocol.
	ProtocolGooglePubSub Protocol = "googlepubsub"
	// ProtocolPulsar is the Pulsar protocol.
	ProtocolPulsar Protocol = "pulsar"
	// ProtocolROS2 is the ROS 2 protocol.
	ProtocolROS2 Protocol = "ros2"
)

type Reference 

type Reference struct {
	// REQUIRED. The reference string.
	Identifier string `json:"$ref" yaml:"$ref"`
}

Reference is "a simple object to allow referencing other components in the specification, internally and externally."

"The Reference Object is defined by JSON Reference and follows the same structure, behavior and rules. A JSON Reference SHALL only be used to refer to a schema that is formatted in either JSON or YAML. In the case of a YAML-formatted Schema, the JSON Reference SHALL be applied to the JSON representation of that schema."

"For this specification, reference resolution is done as defined by the JSON Reference specification and not by the JSON Schema specification."

"This object cannot be extended with additional properties and any properties added SHALL be ignored." Additional properties are therefore dropped when a document is read, they are not written back. (Specification)

func (*Reference) Validate 

func (r *Reference) Validate() error

Validate checks the reference for correctness.

type Replies 

type Replies map[string]*OperationReplyRef

Replies is a map of Operation Reply Objects. (Specification)

func (Replies) ByIndex 

func (rs Replies) ByIndex() iter.Seq2[string, *OperationReplyRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Replies) MarshalJSONTo 

func (rs *Replies) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Replies) Set 

func (rs *Replies) Set(key string, r *OperationReplyRef)

Set sets a value in the map, adding it at the end of the order.

func (Replies) Sort 

func (rs Replies) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Replies) UnmarshalJSONFrom 

func (rs *Replies) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Replies) Validate 

func (rs Replies) Validate() error

Validate validates each reply.

type ReplyAddresses 

type ReplyAddresses map[string]*OperationReplyAddressRef

ReplyAddresses is a map of Operation Reply Address Objects. (Specification)

func (ReplyAddresses) ByIndex 

func (as ReplyAddresses) ByIndex() iter.Seq2[string, *OperationReplyAddressRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*ReplyAddresses) MarshalJSONTo 

func (as *ReplyAddresses) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*ReplyAddresses) Set 

func (as *ReplyAddresses) Set(key string, a *OperationReplyAddressRef)

Set sets a value in the map, adding it at the end of the order.

func (ReplyAddresses) Sort 

func (as ReplyAddresses) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*ReplyAddresses) UnmarshalJSONFrom 

func (as *ReplyAddresses) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (ReplyAddresses) Validate 

func (as ReplyAddresses) Validate() error

Validate validates each reply address.

type RuntimeExpression 

type RuntimeExpression string

A runtime expression allows values to be defined based on information that will be available within the message. This mechanism is used by the CorrelationID object and the OperationReplyAddress object.

The runtime expression is defined by the following ABNF syntax: 

expression = ( "$message" "." source )
source = ( header-reference | payload-reference )
header-reference = "header" ["#" fragment]
payload-reference = "payload" ["#" fragment]
fragment = a JSON Pointer [RFC6901]

Examples: 

| Source Location         | Example expression               |
|-------------------------|----------------------------------|
| Message Header Property | `$message.header#/MQMD/CorrelId` |
| Message Payload Property | `$message.payload#/messageId`    |

Runtime expressions preserve the type of the referenced value. (Specification)

func (RuntimeExpression) Validate 

func (expr RuntimeExpression) Validate() error

Validate checks that the runtime expression is well-formed.

type Schema 

type Schema struct {
	// A boolean schema. `true` allows any instance to validate, `false` allows none.
	// When it is set, all other fields are ignored.
	Boolean *bool `json:"-" yaml:"-"`

	// The URI of the schema, used to identify it and to resolve relative references against.
	ID *url.URL `json:"$id,omitempty" yaml:"$id,omitempty"`
	// The dialect of the schema.
	Dialect *url.URL `json:"$schema,omitempty" yaml:"$schema,omitempty"`
	// A comment for the schema that is not meant to be displayed to end users.
	Comment string `json:"$comment,omitempty" yaml:"$comment,omitempty"`

	// The name of the schema.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short description of the schema. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Specifies the data type of the schema. It is either a single type or a list of types.
	Type DataTypes `json:"type,omitempty" yaml:"type,omitempty"`
	// Further refines the data type. See [Format] for the formats defined by the specification.
	Format Format `json:"format,omitempty" yaml:"format,omitempty"`

	// AllOf validates the value against ALL of the given schemas.
	AllOf AnySchemaRefList `json:"allOf,omitempty" yaml:"allOf,omitempty"`
	// OneOf validates the value against EXACTLY ONE of the given schemas.
	OneOf AnySchemaRefList `json:"oneOf,omitempty" yaml:"oneOf,omitempty"`
	// AnyOf validates the value against AT LEAST ONE of the given schemas.
	AnyOf AnySchemaRefList `json:"anyOf,omitempty" yaml:"anyOf,omitempty"`
	// Not validates the value against the negation of the given schema.
	Not *AnySchemaRef `json:"not,omitempty" yaml:"not,omitempty"`
	// If is the condition of a conditional schema.
	If *AnySchemaRef `json:"if,omitempty" yaml:"if,omitempty"`
	// Then is applied when the value validates against the schema given in the `if` keyword.
	Then *AnySchemaRef `json:"then,omitempty" yaml:"then,omitempty"`
	// Else is applied when the value does not validate against the schema given in the `if` keyword.
	Else *AnySchemaRef `json:"else,omitempty" yaml:"else,omitempty"`

	// The value must be a multiple of this number.
	MultipleOf *float64 `json:"multipleOf,omitempty" yaml:"multipleOf,omitempty"`
	// The minimum value of the number.
	Min *float64 `json:"minimum,omitempty" yaml:"minimum,omitempty"`
	// The exclusive minimum value of the number.
	ExclusiveMin *float64 `json:"exclusiveMinimum,omitempty" yaml:"exclusiveMinimum,omitempty"`
	// The maximum value of the number.
	Max *float64 `json:"maximum,omitempty" yaml:"maximum,omitempty"`
	// The exclusive maximum value of the number.
	ExclusiveMax *float64 `json:"exclusiveMaximum,omitempty" yaml:"exclusiveMaximum,omitempty"`

	// The minimum length of the string.
	MinLength uint `json:"minLength,omitzero" yaml:"minLength,omitempty"`
	// The maximum length of the string.
	MaxLength *uint `json:"maxLength,omitempty" yaml:"maxLength,omitempty"`
	// The pattern is used to validate the string.
	// This string SHOULD be a valid regular expression, according to the ECMA 262 regular expression dialect.
	// NOTE: We simply use text unmarshalling for this field. This guarantees that the regular expression is valid or we can't unmarshal.
	Pattern *regexp.Regexp `json:"pattern,omitempty" yaml:"pattern,omitempty"`

	// The minimum number of items in the array.
	MinItems uint `json:"minItems,omitzero" yaml:"minItems,omitempty"`
	// The maximum number of items in the array.
	MaxItems *uint `json:"maxItems,omitempty" yaml:"maxItems,omitempty"`
	// Whether the items of the array must be unique.
	UniqueItems bool `json:"uniqueItems,omitzero" yaml:"uniqueItems,omitempty"`
	// The schema the items of the array must validate against.
	Items *AnySchemaRef `json:"items,omitempty" yaml:"items,omitempty"`
	// The schema the additional items of the array must validate against.
	AdditionalItems *AnySchemaRef `json:"additionalItems,omitempty" yaml:"additionalItems,omitempty"`
	// The schema at least one item of the array must validate against.
	Contains *AnySchemaRef `json:"contains,omitempty" yaml:"contains,omitempty"`

	// The minimum number of properties of the object.
	MinProperties uint `json:"minProperties,omitzero" yaml:"minProperties,omitempty"`
	// The maximum number of properties of the object.
	MaxProperties *uint `json:"maxProperties,omitempty" yaml:"maxProperties,omitempty"`
	// Which properties are required.
	Required []string `json:"required,omitempty" yaml:"required,omitempty"`
	// The properties of the object.
	Properties Schemas `json:"properties,omitempty" yaml:"properties,omitempty"`
	// The properties of the object whose names match a regular expression.
	PatternProperties Schemas `json:"patternProperties,omitempty" yaml:"patternProperties,omitempty"`
	// The schema the additional properties of the object must validate against.
	AdditionalProperties *AnySchemaRef `json:"additionalProperties,omitempty" yaml:"additionalProperties,omitempty"`
	// The schema the property names of the object must validate against.
	PropertyNames *AnySchemaRef `json:"propertyNames,omitempty" yaml:"propertyNames,omitempty"`
	// Reusable schemas that are referenced from within this schema.
	Definitions Schemas `json:"definitions,omitempty" yaml:"definitions,omitempty"`

	// A list of possible values.
	Enum []jsontext.Value `json:"enum,omitempty" yaml:"enum,omitempty"`
	// The only possible value.
	Const jsontext.Value `json:"const,omitempty" yaml:"const,omitempty"`
	// The value that is used if no other value is present.
	// Unlike JSON Schema, the value MUST conform to the defined type for the schema defined at the same level.
	Default jsontext.Value `json:"default,omitempty" yaml:"default,omitempty"`
	// A list of examples of the value.
	Examples []jsontext.Value `json:"examples,omitempty" yaml:"examples,omitempty"`

	// special encoding for binary data
	ContentEncoding  string `json:"contentEncoding,omitempty"  yaml:"contentEncoding,omitempty"`
	ContentMediaType string `json:"contentMediaType,omitempty" yaml:"contentMediaType,omitempty"`

	// Whether the value is only sent by the server and must not be sent by the client.
	ReadOnly bool `json:"readOnly,omitzero" yaml:"readOnly,omitempty"`
	// Whether the value is only sent by the client and must not be sent by the server.
	WriteOnly bool `json:"writeOnly,omitzero" yaml:"writeOnly,omitempty"`

	// Adds support for polymorphism.
	// The discriminator is the schema property name that is used to differentiate between other schemas that inherit this schema.
	// The property name used MUST be defined at this schema and it MUST be in the required property list.
	Discriminator string `json:"discriminator,omitempty" yaml:"discriminator,omitempty"`
	// Additional external documentation for this schema.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// Specifies that a schema is deprecated and SHOULD be transitioned out of usage.
	Deprecated bool `json:"deprecated,omitzero" yaml:"deprecated,omitempty"`

	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Schema allows the definition of input and output data types. These types can be objects, but also primitives and arrays. This object is a superset of the JSON Schema Specification Draft 07.

The empty schema (which allows any instance to validate) MAY be represented by the boolean value `true` and a schema which allows no instance to validate MAY be represented by the boolean value `false`. Both are represented by the Schema.Boolean field.

For other formats (e.g. Avro, RAML, etc.) see the MultiFormatSchema object. (Specification)

func (*Schema) MarshalJSONTo 

func (s *Schema) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the schema, which may be a boolean schema.

func (*Schema) SortMaps 

func (s *Schema) SortMaps()

SortMaps sorts the properties of the schema and of all of its subschemas by key.

func (*Schema) UnmarshalJSONFrom 

func (s *Schema) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the schema, which may be a boolean schema.

func (*Schema) Validate 

func (s *Schema) Validate() error

Validate checks the schema for correctness.

type SchemaFormat 

type SchemaFormat string

SchemaFormat is the name of the schema format that is used to define the information of a MultiFormatSchema. (Specification) 

const (
	// SchemaFormatAsyncAPI is the AsyncAPI 3.1.0 Schema Object format.
	// It is the default when a schema format is not provided.
	SchemaFormatAsyncAPI SchemaFormat = "application/vnd.aai.asyncapi;version=3.1.0"
	// SchemaFormatAsyncAPIJSON is the AsyncAPI 3.1.0 Schema Object format, given as JSON.
	SchemaFormatAsyncAPIJSON SchemaFormat = "application/vnd.aai.asyncapi+json;version=3.1.0"
	// SchemaFormatAsyncAPIYAML is the AsyncAPI 3.1.0 Schema Object format, given as YAML.
	SchemaFormatAsyncAPIYAML SchemaFormat = "application/vnd.aai.asyncapi+yaml;version=3.1.0"
	// SchemaFormatJSONSchema is the JSON Schema Draft 07 format.
	SchemaFormatJSONSchema SchemaFormat = "application/schema+json;version=draft-07"
	// SchemaFormatJSONSchemaYAML is the JSON Schema Draft 07 format, given as YAML.
	SchemaFormatJSONSchemaYAML SchemaFormat = "application/schema+yaml;version=draft-07"
	// SchemaFormatAvro is the Avro 1.9.0 schema format.
	SchemaFormatAvro SchemaFormat = "application/vnd.apache.avro;version=1.9.0"
	// SchemaFormatAvroJSON is the Avro 1.9.0 schema format, given as JSON.
	SchemaFormatAvroJSON SchemaFormat = "application/vnd.apache.avro+json;version=1.9.0"
	// SchemaFormatAvroYAML is the Avro 1.9.0 schema format, given as YAML.
	SchemaFormatAvroYAML SchemaFormat = "application/vnd.apache.avro+yaml;version=1.9.0"
	// SchemaFormatOpenAPI is the OpenAPI 3.0.0 Schema Object format.
	SchemaFormatOpenAPI SchemaFormat = "application/vnd.oai.openapi;version=3.0.0"
	// SchemaFormatOpenAPIJSON is the OpenAPI 3.0.0 Schema Object format, given as JSON.
	SchemaFormatOpenAPIJSON SchemaFormat = "application/vnd.oai.openapi+json;version=3.0.0"
	// SchemaFormatOpenAPIYAML is the OpenAPI 3.0.0 Schema Object format, given as YAML.
	SchemaFormatOpenAPIYAML SchemaFormat = "application/vnd.oai.openapi+yaml;version=3.0.0"
	// SchemaFormatRAML is the RAML 1.0 data type format.
	SchemaFormatRAML SchemaFormat = "application/raml+yaml;version=1.0"
	// SchemaFormatProtobuf2 is the Protocol Buffers version 2 format.
	SchemaFormatProtobuf2 SchemaFormat = "application/vnd.google.protobuf;version=2"
	// SchemaFormatProtobuf3 is the Protocol Buffers version 3 format.
	SchemaFormatProtobuf3 SchemaFormat = "application/vnd.google.protobuf;version=3"
)

func (SchemaFormat) IsAsyncAPI 

func (f SchemaFormat) IsAsyncAPI() bool

IsAsyncAPI reports whether the schema format denotes an AsyncAPI Schema Object, i.e. whether the schema can be parsed into a Schema.

func (SchemaFormat) IsKnown 

func (f SchemaFormat) IsKnown() bool

IsKnown reports whether the schema format is one of the formats listed in the specification.

Custom values are allowed, so a format that is not known is not necessarily invalid.

type Schemas 

type Schemas map[string]*AnySchemaRef

Schemas is a map of schema definitions, each of which is either a schema object, a multi format schema object or a reference to one of them. (Specification)

func (Schemas) ByIndex 

func (ss Schemas) ByIndex() iter.Seq2[string, *AnySchemaRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Schemas) MarshalJSONTo 

func (ss *Schemas) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Schemas) Set 

func (ss *Schemas) Set(key string, s *AnySchemaRef)

Set sets a value in the map, adding it at the end of the order.

func (Schemas) Sort 

func (ss Schemas) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Schemas) UnmarshalJSONFrom 

func (ss *Schemas) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Schemas) Validate 

func (ss Schemas) Validate() error

Validate validates each schema.

type SecurityScheme 

type SecurityScheme struct {
	// REQUIRED. The type of the security scheme.
	Type SecuritySchemeType `json:"type" yaml:"type"`
	// A short description for security scheme. CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// REQUIRED for `httpApiKey`. The name of the header, query or cookie parameter to be used.
	Name string `json:"name,omitempty" yaml:"name,omitempty"`
	// REQUIRED for `apiKey` and `httpApiKey`. The location of the API key.
	// Valid values are `user` and `password` for `apiKey`
	// and `query`, `header` or `cookie` for `httpApiKey`.
	In SecuritySchemeIn `json:"in,omitempty" yaml:"in,omitempty"`
	// REQUIRED for `http`. The name of the HTTP Authorization scheme to be used in the Authorization header as defined in RFC7235.
	Scheme string `json:"scheme,omitempty" yaml:"scheme,omitempty"`
	// A hint to the client to identify how the bearer token is formatted, e.g. "jwt".
	// Bearer tokens are usually generated by an authorization server, so this information is primarily for documentation purposes.
	BearerFormat string `json:"bearerFormat,omitempty" yaml:"bearerFormat,omitempty"`
	// REQUIRED for `oauth2`. An object containing configuration information for the flow types supported.
	Flows *OAuthFlows `json:"flows,omitempty" yaml:"flows,omitempty"`
	// REQUIRED for `openIdConnect`. OpenId Connect URL to discover OAuth2 configuration values.
	// This MUST be in the form of an absolute URL.
	OpenIDConnectURL *url.URL `json:"openIdConnectUrl,omitempty" yaml:"openIdConnectUrl,omitempty"`
	// List of the needed scope names. An empty array means no scopes are needed.
	// Only valid for `oauth2` and `openIdConnect`.
	Scopes []string `json:"scopes,omitempty" yaml:"scopes,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

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

Supported schemes are:

  • User/Password.
  • API key (either as user or as password).
  • X.509 certificate.
  • End-to-end encryption (either symmetric or asymmetric).
  • HTTP authentication.
  • HTTP API key.
  • OAuth2's common flows (Implicit, Resource Owner Protected Credentials, Client Credentials and Authorization Code) as defined in RFC6749.
  • OpenID Connect Discovery.
  • SASL (Simple Authentication and Security Layer) as defined in RFC4422.

(Specification)

func (*SecurityScheme) Validate 

func (s *SecurityScheme) Validate() error

Validate checks the security scheme for correctness.

type SecuritySchemeIn 

type SecuritySchemeIn string

SecuritySchemeIn is "the location of the API key. Valid values are `user` and `password` for `apiKey` and `query`, `header` or `cookie` for `httpApiKey`." (Specification) 

const (
	// SecuritySchemeInUser is the location of an API key that is sent as the user of a connection.
	SecuritySchemeInUser SecuritySchemeIn = "user"
	// SecuritySchemeInPassword is the location of an API key that is sent as the password of a connection.
	SecuritySchemeInPassword SecuritySchemeIn = "password"
	// SecuritySchemeInQuery is the location of an API key that is sent as a query parameter.
	SecuritySchemeInQuery SecuritySchemeIn = "query"
	// SecuritySchemeInHeader is the location of an API key that is sent as a header.
	SecuritySchemeInHeader SecuritySchemeIn = "header"
	// SecuritySchemeInCookie is the location of an API key that is sent as a cookie.
	SecuritySchemeInCookie SecuritySchemeIn = "cookie"
)

type SecuritySchemeRef 

type SecuritySchemeRef = refOrValue[SecurityScheme, *SecurityScheme]

SecuritySchemeRef is a reference to a SecurityScheme or an actual SecurityScheme.

type SecuritySchemeRefList 

type SecuritySchemeRefList []*SecuritySchemeRef

SecuritySchemeRefList is a slice of SecuritySchemeRef.

func (SecuritySchemeRefList) Validate 

func (ss SecuritySchemeRefList) Validate() error

Validate validates each security scheme of the list.

type SecuritySchemeType 

type SecuritySchemeType string

SecuritySchemeType is the type of a security scheme. (Specification) 

const (
	// SecuritySchemeTypeUserPassword is the user/password authentication.
	SecuritySchemeTypeUserPassword SecuritySchemeType = "userPassword"
	// SecuritySchemeTypeAPIKey is an API key, either as user or as password.
	SecuritySchemeTypeAPIKey SecuritySchemeType = "apiKey"
	// SecuritySchemeTypeX509 is an X.509 certificate.
	SecuritySchemeTypeX509 SecuritySchemeType = "X509"
	// SecuritySchemeTypeSymmetricEncryption is a symmetric end-to-end encryption.
	SecuritySchemeTypeSymmetricEncryption SecuritySchemeType = "symmetricEncryption"
	// SecuritySchemeTypeAsymmetricEncryption is an asymmetric end-to-end encryption.
	SecuritySchemeTypeAsymmetricEncryption SecuritySchemeType = "asymmetricEncryption"
	// SecuritySchemeTypeHTTPAPIKey is an API key that is sent as an HTTP header, query or cookie parameter.
	SecuritySchemeTypeHTTPAPIKey SecuritySchemeType = "httpApiKey"
	// SecuritySchemeTypeHTTP is an HTTP authentication.
	SecuritySchemeTypeHTTP SecuritySchemeType = "http"
	// SecuritySchemeTypeOAuth2 is one of OAuth2's common flows.
	SecuritySchemeTypeOAuth2 SecuritySchemeType = "oauth2"
	// SecuritySchemeTypeOpenIDConnect is OpenID Connect Discovery.
	SecuritySchemeTypeOpenIDConnect SecuritySchemeType = "openIdConnect"
	// SecuritySchemeTypePlain is the SASL PLAIN mechanism.
	SecuritySchemeTypePlain SecuritySchemeType = "plain"
	// SecuritySchemeTypeScramSha256 is the SASL SCRAM-SHA-256 mechanism.
	SecuritySchemeTypeScramSha256 SecuritySchemeType = "scramSha256"
	// SecuritySchemeTypeScramSha512 is the SASL SCRAM-SHA-512 mechanism.
	SecuritySchemeTypeScramSha512 SecuritySchemeType = "scramSha512"
	// SecuritySchemeTypeGSSAPI is the SASL GSSAPI mechanism.
	SecuritySchemeTypeGSSAPI SecuritySchemeType = "gssapi"
)

func (SecuritySchemeType) Validate 

func (tp SecuritySchemeType) Validate() error

Validate validates the security scheme type.

type SecuritySchemes 

type SecuritySchemes map[string]*SecuritySchemeRef

SecuritySchemes is a map of Security Scheme Objects. (Specification)

func (SecuritySchemes) ByIndex 

func (ss SecuritySchemes) ByIndex() iter.Seq2[string, *SecuritySchemeRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*SecuritySchemes) MarshalJSONTo 

func (ss *SecuritySchemes) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*SecuritySchemes) Set 

func (ss *SecuritySchemes) Set(key string, s *SecuritySchemeRef)

Set sets a value in the map, adding it at the end of the order.

func (SecuritySchemes) Sort 

func (ss SecuritySchemes) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*SecuritySchemes) UnmarshalJSONFrom 

func (ss *SecuritySchemes) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (SecuritySchemes) Validate 

func (ss SecuritySchemes) Validate() error

Validate validates each security scheme.

type Server 

type Server struct {
	// REQUIRED. The server host name. It MAY include the port.
	// This field supports Server Variables. Variable substitutions will be made when a variable is named in {braces}.
	Host string `json:"host" yaml:"host"`
	// REQUIRED. The protocol this server supports for connection.
	Protocol Protocol `json:"protocol" yaml:"protocol"`
	// The version of the protocol used for connection. For instance: AMQP 0.9.1, HTTP 2.0, Kafka 1.0.0, etc.
	ProtocolVersion string `json:"protocolVersion,omitempty" yaml:"protocolVersion,omitempty"`
	// The path to a resource in the host.
	// This field supports Server Variables. Variable substitutions will be made when a variable is named in {braces}.
	Pathname string `json:"pathname,omitempty" yaml:"pathname,omitempty"`
	// An optional string describing the server. CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// A human-friendly title for the server.
	Title string `json:"title,omitempty" yaml:"title,omitempty"`
	// A short summary of the server.
	Summary string `json:"summary,omitempty" yaml:"summary,omitempty"`
	// A map between a variable name and its value. The value is used for substitution in the server's host and pathname template.
	Variables ServerVariables `json:"variables,omitempty" yaml:"variables,omitempty"`
	// A declaration of which security schemes can be used with this server.
	// The list of values includes alternative security scheme objects that can be used.
	// Only one of the security scheme objects need to be satisfied to authorize a connection or operation.
	Security SecuritySchemeRefList `json:"security,omitempty" yaml:"security,omitempty"`
	// A list of tags for logical grouping and categorization of servers.
	Tags Tags `json:"tags,omitempty" yaml:"tags,omitempty"`
	// Additional external documentation for this server.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// A map where the keys describe the name of the protocol and the values describe protocol-specific definitions for the server.
	Bindings *BindingsRef `json:"bindings,omitempty" yaml:"bindings,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Server is an object representing a message broker, a server or any other kind of computer program capable of sending and/or receiving data. This object is used to capture details such as URIs, protocols and security configuration. Variable substitution can be used so that some details, for example usernames and passwords, can be injected by code generation tools. (Specification)

func (*Server) Validate 

func (s *Server) Validate() error

Validate checks the server for correctness.

type ServerRef 

type ServerRef = refOrValue[Server, *Server]

ServerRef is a reference to a Server or an actual Server.

type ServerRefList 

type ServerRefList []*ServerRef

ServerRefList is a slice of ServerRef.

func (ServerRefList) Validate 

func (ss ServerRefList) Validate() error

Validate validates each server of the list and makes sure they are references.

type ServerVariable 

type ServerVariable struct {
	// An enumeration of string values to be used if the substitution options are from a limited set.
	Enum []string `json:"enum,omitempty" yaml:"enum,omitempty"`
	// The default value to use for substitution, and to send, if an alternate value is not supplied.
	Default string `json:"default,omitempty" yaml:"default,omitempty"`
	// An optional description for the server variable. CommonMark syntax MAY be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// An array of examples of the server variable.
	Examples []string `json:"examples,omitempty" yaml:"examples,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

ServerVariable is an object representing a Server Variable for server URL template substitution. (Specification)

func (*ServerVariable) Validate 

func (v *ServerVariable) Validate() error

Validate checks the server variable for correctness.

type ServerVariableRef 

type ServerVariableRef = refOrValue[ServerVariable, *ServerVariable]

ServerVariableRef is a reference to a ServerVariable or an actual ServerVariable.

type ServerVariables 

type ServerVariables map[string]*ServerVariableRef

ServerVariables is a map between a variable name and its value. The value is used for substitution in the server's host and pathname template. (Specification)

func (ServerVariables) ByIndex 

func (vars ServerVariables) ByIndex() iter.Seq2[string, *ServerVariableRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*ServerVariables) MarshalJSONTo 

func (vars *ServerVariables) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*ServerVariables) Set 

func (vars *ServerVariables) Set(key string, v *ServerVariableRef)

Set sets a value in the map, adding it at the end of the order.

func (ServerVariables) Sort 

func (vars ServerVariables) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*ServerVariables) UnmarshalJSONFrom 

func (vars *ServerVariables) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (ServerVariables) Validate 

func (vars ServerVariables) Validate() error

Validate validates each server variable.

type Servers 

type Servers map[string]*ServerRef

Servers is a map of Server Objects. (Specification)

func (Servers) ByIndex 

func (ss Servers) ByIndex() iter.Seq2[string, *ServerRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*Servers) MarshalJSONTo 

func (ss *Servers) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*Servers) Set 

func (ss *Servers) Set(key string, s *ServerRef)

Set sets a value in the map, adding it at the end of the order.

func (Servers) Sort 

func (ss Servers) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*Servers) UnmarshalJSONFrom 

func (ss *Servers) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (Servers) Validate 

func (ss Servers) Validate() error

Validate validates each server.

type String 

type String struct {
	Value string
	// contains filtered or unexported fields
}

String is a string value that remembers its position in an ordered map.

func (*String) MarshalJSONTo 

func (s *String) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the value of the String.

func (*String) UnmarshalJSONFrom 

func (s *String) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the value of the String.

type Tag 

type Tag struct {
	// REQUIRED. The name of the tag.
	Name string `json:"name" yaml:"name"`
	// A short description for the tag. CommonMark syntax can be used for rich text representation.
	Description string `json:"description,omitempty" yaml:"description,omitempty"`
	// Additional external documentation for this tag.
	ExternalDocs *ExternalDocsRef `json:"externalDocs,omitempty" yaml:"externalDocs,omitempty"`
	// This object MAY be extended with Specification Extensions.
	Extensions Extensions `json:",embed" yaml:",embed"`
}

Tag allows adding meta data to a single tag. (Specification)

func (*Tag) Validate 

func (t *Tag) Validate() error

Validate checks the tag for correctness.

type TagRef 

type TagRef = refOrValue[Tag, *Tag]

TagRef is a reference to a Tag or an actual Tag.

type Tags 

type Tags []*TagRef

Tags is a list of Tag Objects. A Tag Object in a list can be referenced by a Reference Object. (Specification)

func (Tags) Validate 

func (tags Tags) Validate() error

Validate validates each tag and makes sure that the tag names are unique.

type TagsByName 

type TagsByName map[string]*TagRef

TagsByName is a map of Tag Objects. (Specification)

func (TagsByName) ByIndex 

func (ts TagsByName) ByIndex() iter.Seq2[string, *TagRef]

ByIndex returns a sequence of key-value pairs ordered by index.

func (*TagsByName) MarshalJSONTo 

func (ts *TagsByName) MarshalJSONTo(enc *jsontext.Encoder) error

MarshalJSONTo marshals the key-value pairs in order.

func (*TagsByName) Set 

func (ts *TagsByName) Set(key string, t *TagRef)

Set sets a value in the map, adding it at the end of the order.

func (TagsByName) Sort 

func (ts TagsByName) Sort()

Sort sorts the map by key and sets the indices accordingly.

func (*TagsByName) UnmarshalJSONFrom 

func (ts *TagsByName) UnmarshalJSONFrom(dec *jsontext.Decoder) error

UnmarshalJSONFrom unmarshals the key-value pairs in order and sets the indices.

func (TagsByName) Validate 

func (ts TagsByName) Validate() error

Validate validates each tag.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.