asyncapi

package
v1.28.0 Latest Latest
Warning

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

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

Documentation

Overview

Package asyncapi provides models for AsyncAPI schemas: the native AsyncAPI Schema Object (a superset of JSON Schema Draft 07), explicit JSON Schema Draft 07 schemas, and Multi Format Schema Objects that wrap schemas written in other languages such as Avro or Protocol Buffers.

This package is deliberately separate from jsonschema/oas3. AsyncAPI schemas follow Draft 07 rather than the OpenAPI dialects, use a string `discriminator`, and `$ref` follows AsyncAPI Reference Object behaviour.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func WithSchemaFormat

func WithSchemaFormat(schemaFormat string) validation.Option

WithSchemaFormat sets the schema format that schemas are validated as, for example the native AsyncAPI Schema Object format of the owning document (`application/vnd.aai.asyncapi+json;version=3.1.0`) or JSON Schema Draft 07 (`application/schema+json;version=draft-07`). Without it, schemas are validated as native AsyncAPI schemas.

Types

type Dependency

type Dependency struct {
	// Schema is the schema the instance must validate against.
	Schema *JSONSchema
	// Properties are the property names that become required.
	Properties []string
	// contains filtered or unexported fields
}

Dependency is a value of the `dependencies` keyword: either a list of property names that are required when the property is present, or a schema the instance must validate against when the property is present. Set Properties (including to an empty, non-nil slice) for the list form, otherwise Schema.

func NewDependencyFromProperties

func NewDependencyFromProperties(properties ...string) *Dependency

NewDependencyFromProperties creates a property dependency.

func NewDependencyFromSchema

func NewDependencyFromSchema(schema *JSONSchema) *Dependency

NewDependencyFromSchema creates a schema dependency.

func (*Dependency) GetCore

func (d *Dependency) GetCore() *core.Dependency

GetCore returns the low level representation of the dependency.

func (*Dependency) GetRootNode

func (d *Dependency) GetRootNode() *yaml.Node

GetRootNode returns the node the dependency was parsed from.

func (*Dependency) IsList

func (d *Dependency) IsList() bool

IsList returns true if the dependency is a list of property names.

func (*Dependency) Populate

func (d *Dependency) Populate(source any) error

type ExternalDocumentation

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

	// Ref is set when this is a Reference Object, in which case the other fields are ignored.
	Ref *references.Reference
	// Description is a description of the target documentation. May contain CommonMark syntax.
	Description *string
	// URL is the URL for the target documentation. Required unless this is a Reference Object.
	URL *string
	// Extensions provides a list of extensions to the External Documentation Object.
	Extensions *extensions.Extensions
}

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

func (*ExternalDocumentation) GetDescription

func (e *ExternalDocumentation) GetDescription() string

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

func (*ExternalDocumentation) GetExtensions

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

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

func (*ExternalDocumentation) GetURL

func (e *ExternalDocumentation) GetURL() string

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

func (*ExternalDocumentation) IsReference

func (e *ExternalDocumentation) IsReference() bool

IsReference returns true if the external documentation is a Reference Object.

func (*ExternalDocumentation) Validate

Validate validates the External Documentation Object.

type Items

type Items struct {
	// Schema is the single schema applied to every item.
	Schema *JSONSchema
	// Schemas are the schemas applied to the items at the corresponding positions.
	Schemas []*JSONSchema
	// contains filtered or unexported fields
}

Items is the value of the `items` keyword: either a list of schemas (tuple validation) or a single schema. Set Schemas (including to an empty, non-nil slice) for the list form, otherwise Schema.

func NewItemsFromSchema

func NewItemsFromSchema(schema *JSONSchema) *Items

NewItemsFromSchema creates an `items` value applying the schema to every item.

func NewItemsFromSchemas

func NewItemsFromSchemas(schemas ...*JSONSchema) *Items

NewItemsFromSchemas creates an `items` value applying the schemas positionally.

func (*Items) GetCore

func (i *Items) GetCore() *core.Items

GetCore returns the low level representation of the items value.

func (*Items) GetRootNode

func (i *Items) GetRootNode() *yaml.Node

GetRootNode returns the node the items value was parsed from.

func (*Items) IsList

func (i *Items) IsList() bool

IsList returns true if `items` is a list of schemas.

func (*Items) Populate

func (i *Items) Populate(source any) error

type JSONSchema

type JSONSchema struct {
	values.EitherValue[Schema, core.Schema, bool, bool]
}

JSONSchema is either a Schema Object (which may be a Reference Object) or a boolean schema.

func NewJSONSchemaFromBool

func NewJSONSchemaFromBool(value bool) *JSONSchema

NewJSONSchemaFromBool creates a boolean JSONSchema, where true allows any instance and false allows none.

func NewJSONSchemaFromReference

func NewJSONSchemaFromReference(ref references.Reference) *JSONSchema

NewJSONSchemaFromReference creates a JSONSchema that is a Reference Object.

func NewJSONSchemaFromSchema

func NewJSONSchemaFromSchema(schema *Schema) *JSONSchema

NewJSONSchemaFromSchema creates a JSONSchema from a Schema Object.

func (*JSONSchema) GetBool

func (j *JSONSchema) GetBool() *bool

GetBool returns the boolean schema value, or nil if the JSONSchema is a Schema Object.

func (*JSONSchema) GetRef

func (j *JSONSchema) GetRef() references.Reference

GetRef returns the reference if the JSONSchema is a Reference Object, otherwise an empty reference.

func (*JSONSchema) GetSchema

func (j *JSONSchema) GetSchema() *Schema

GetSchema returns the Schema Object, or nil if the JSONSchema is a boolean schema.

func (*JSONSchema) IsBool

func (j *JSONSchema) IsBool() bool

IsBool returns true if the JSONSchema is a boolean schema.

func (*JSONSchema) IsReference

func (j *JSONSchema) IsReference() bool

IsReference returns true if the JSONSchema is a Reference Object.

func (*JSONSchema) IsSchema

func (j *JSONSchema) IsSchema() bool

IsSchema returns true if the JSONSchema is a Schema Object (including a Reference Object).

func (*JSONSchema) Validate

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

Validate validates the schema, which may be a boolean schema.

type MultiFormatSchema

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

	// SchemaFormat is the media type identifying the schema language, e.g. `application/vnd.apache.avro;version=1.9.0`.
	SchemaFormat string
	// Schema is the schema definition, interpreted according to SchemaFormat.
	Schema *SchemaDefinition
	// Extensions provides a list of extensions to the Multi Format Schema Object.
	Extensions *extensions.Extensions
}

MultiFormatSchema is an AsyncAPI Multi Format Schema Object, a schema written in the language identified by SchemaFormat.

func NewMultiFormatSchema

func NewMultiFormatSchema(schemaFormat string, definition *SchemaDefinition) *MultiFormatSchema

NewMultiFormatSchema creates a Multi Format Schema Object for the provided format and definition.

func (*MultiFormatSchema) GetExtensions

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

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

func (*MultiFormatSchema) GetSchema

func (m *MultiFormatSchema) GetSchema() *SchemaDefinition

GetSchema returns the schema definition, or nil if not set.

func (*MultiFormatSchema) GetSchemaFormat

func (m *MultiFormatSchema) GetSchemaFormat() string

GetSchemaFormat returns the authored schema format.

func (*MultiFormatSchema) Validate

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

Validate validates the Multi Format Schema Object. The schema is validated when its format is the native AsyncAPI Schema Object of a supported version or JSON Schema Draft 07. Other formats are preserved but not validated, and a warning with the RuleValidationUnsupportedFormat rule is reported so callers can tell the content was not checked.

type Schema

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

	Ref                  *references.Reference
	ID                   *string
	Schema               *string
	Comment              *string
	Title                *string
	Description          *string
	Default              values.Value
	ReadOnly             *bool
	WriteOnly            *bool
	Examples             []values.Value
	MultipleOf           *float64
	Maximum              *float64
	ExclusiveMaximum     *float64
	Minimum              *float64
	ExclusiveMinimum     *float64
	MaxLength            *int64
	MinLength            *int64
	Pattern              *string
	AdditionalItems      *JSONSchema
	Items                *Items
	MaxItems             *int64
	MinItems             *int64
	UniqueItems          *bool
	Contains             *JSONSchema
	MaxProperties        *int64
	MinProperties        *int64
	Required             []string
	AdditionalProperties *JSONSchema
	Definitions          *sequencedmap.Map[string, *JSONSchema]
	Properties           *sequencedmap.Map[string, *JSONSchema]
	PatternProperties    *sequencedmap.Map[string, *JSONSchema]
	Dependencies         *sequencedmap.Map[string, *Dependency]
	PropertyNames        *JSONSchema
	Const                values.Value
	Enum                 []values.Value
	Type                 *Type
	Format               *string
	ContentMediaType     *string
	ContentEncoding      *string
	If                   *JSONSchema
	Then                 *JSONSchema
	Else                 *JSONSchema
	AllOf                []*JSONSchema
	AnyOf                []*JSONSchema
	OneOf                []*JSONSchema
	Not                  *JSONSchema
	// Discriminator is the name of the property used to differentiate between schemas that inherit this schema (AsyncAPI only).
	Discriminator *string
	// ExternalDocs is additional external documentation for this schema (AsyncAPI only).
	ExternalDocs *ExternalDocumentation
	// Deprecated specifies that the schema is deprecated (AsyncAPI only).
	Deprecated *bool
	Extensions *extensions.Extensions
}

Schema is an AsyncAPI Schema Object, a superset of JSON Schema Draft 07. It is also used to represent schemas explicitly declared as JSON Schema Draft 07, in which case the AsyncAPI specific fields (Discriminator, ExternalDocs and Deprecated) have no special meaning.

When Ref is set the schema is a Reference Object, and any sibling fields are ignored.

func (*Schema) GetDeprecated

func (s *Schema) GetDeprecated() bool

GetDeprecated returns true if the schema is marked as deprecated.

func (*Schema) GetDiscriminator

func (s *Schema) GetDiscriminator() string

GetDiscriminator returns the discriminator property name, or an empty string if not set.

func (*Schema) GetExtensions

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

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

func (*Schema) GetExternalDocs

func (s *Schema) GetExternalDocs() *ExternalDocumentation

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

func (*Schema) GetProperties

func (s *Schema) GetProperties() *sequencedmap.Map[string, *JSONSchema]

GetProperties returns the properties of the schema, or nil if not set.

func (*Schema) GetRef

func (s *Schema) GetRef() references.Reference

GetRef returns the reference of the schema, or an empty reference if it is not a Reference Object.

func (*Schema) GetRequired

func (s *Schema) GetRequired() []string

GetRequired returns the required property names, or nil if not set.

func (*Schema) GetType

func (s *Schema) GetType() []string

GetType returns the declared types of the schema, or nil if no type is declared.

func (*Schema) IsReference

func (s *Schema) IsReference() bool

IsReference returns true if the schema is a Reference Object.

func (*Schema) Validate

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

Validate validates the Schema Object and all its subschemas. The structure is checked against the JSON Schema Draft 07 metaschema. For native AsyncAPI schemas the AsyncAPI specific rules are also checked: `discriminator` must name a required property defined in the same schema, `default` must conform to the declared `type`, and `externalDocs` must be valid.

A Reference Object is only checked for a valid reference. As in both AsyncAPI and Draft 07, its siblings are ignored.

type SchemaDefinition

type SchemaDefinition struct {
	// Schema is the typed schema for JSON Schema based formats.
	Schema *JSONSchema
	// Raw is the authored value for all other formats.
	Raw values.Value
	// contains filtered or unexported fields
}

SchemaDefinition is the `schema` value of a Multi Format Schema Object.

For JSON Schema based formats (the native AsyncAPI Schema Object and JSON Schema Draft 07) Schema holds the typed schema. For any other format Raw holds the authored value unchanged: for example a structured Avro schema, a Protocol Buffers string or a Reference Object to an external resource in that format.

func NewSchemaDefinitionFromRaw

func NewSchemaDefinitionFromRaw(raw *yaml.Node) *SchemaDefinition

NewSchemaDefinitionFromRaw creates a schema definition holding a raw value for any other format.

func NewSchemaDefinitionFromSchema

func NewSchemaDefinitionFromSchema(schema *JSONSchema) *SchemaDefinition

NewSchemaDefinitionFromSchema creates a schema definition for a JSON Schema based format.

func (*SchemaDefinition) GetCore

func (d *SchemaDefinition) GetCore() *core.SchemaDefinition

GetCore returns the low level representation of the schema definition.

func (*SchemaDefinition) GetRaw

func (d *SchemaDefinition) GetRaw() values.Value

GetRaw returns the raw value, or nil if the format is JSON Schema based.

func (*SchemaDefinition) GetReference

func (d *SchemaDefinition) GetReference() references.Reference

GetReference returns the reference if the definition is a Reference Object, otherwise an empty reference. For formats other than JSON Schema based formats only a Reference Object that is the entire value is recognised, references nested within foreign schema languages are not interpreted.

func (*SchemaDefinition) GetRootNode

func (d *SchemaDefinition) GetRootNode() *yaml.Node

GetRootNode returns the node the schema definition was parsed from.

func (*SchemaDefinition) GetSchema

func (d *SchemaDefinition) GetSchema() *JSONSchema

GetSchema returns the typed schema, or nil if the format is not JSON Schema based.

func (*SchemaDefinition) IsReference

func (d *SchemaDefinition) IsReference() bool

IsReference returns true if the definition is a Reference Object to a schema resource.

func (*SchemaDefinition) Populate

func (d *SchemaDefinition) Populate(source any) error

func (*SchemaDefinition) SetCore

func (d *SchemaDefinition) SetCore(c *core.SchemaDefinition)

SetCore sets the low level representation of the schema definition.

type SchemaUnion

type SchemaUnion struct {
	// Schema is a native AsyncAPI Schema Object, boolean schema or Reference Object.
	Schema *JSONSchema
	// MultiFormat is a Multi Format Schema Object.
	MultiFormat *MultiFormatSchema
	// contains filtered or unexported fields
}

SchemaUnion is a value AsyncAPI accepts wherever a schema is expected (for example message payloads and headers, and component schemas): a Schema Object, a boolean schema, a Reference Object or a Multi Format Schema Object. Exactly one of Schema and MultiFormat is set.

func NewSchemaUnionFromMultiFormat

func NewSchemaUnionFromMultiFormat(multiFormat *MultiFormatSchema) *SchemaUnion

NewSchemaUnionFromMultiFormat creates a schema union holding a Multi Format Schema Object.

func NewSchemaUnionFromSchema

func NewSchemaUnionFromSchema(schema *JSONSchema) *SchemaUnion

NewSchemaUnionFromSchema creates a schema union holding a native schema, boolean schema or Reference Object.

func (*SchemaUnion) GetCore

func (u *SchemaUnion) GetCore() *core.SchemaUnion

GetCore returns the low level representation of the schema union.

func (*SchemaUnion) GetMultiFormat

func (u *SchemaUnion) GetMultiFormat() *MultiFormatSchema

GetMultiFormat returns the Multi Format Schema Object, or nil if the union holds a native schema.

func (*SchemaUnion) GetRef

func (u *SchemaUnion) GetRef() references.Reference

GetRef returns the reference if the union is a Reference Object, otherwise an empty reference.

func (*SchemaUnion) GetRootNode

func (u *SchemaUnion) GetRootNode() *yaml.Node

GetRootNode returns the node the schema union was parsed from.

func (*SchemaUnion) GetSchema

func (u *SchemaUnion) GetSchema() *JSONSchema

GetSchema returns the native schema, or nil if the union holds a Multi Format Schema Object.

func (*SchemaUnion) GetSchemaFormat

func (u *SchemaUnion) GetSchemaFormat(asyncAPIVersion string) string

GetSchemaFormat returns the effective schema format of the union. A native schema uses the AsyncAPI Schema Object format of the provided document version.

func (*SchemaUnion) IsMultiFormat

func (u *SchemaUnion) IsMultiFormat() bool

IsMultiFormat returns true if the union holds a Multi Format Schema Object.

func (*SchemaUnion) IsReference

func (u *SchemaUnion) IsReference() bool

IsReference returns true if the union is a Reference Object.

func (*SchemaUnion) IsSchema

func (u *SchemaUnion) IsSchema() bool

IsSchema returns true if the union holds a native schema, boolean schema or Reference Object.

func (*SchemaUnion) Populate

func (u *SchemaUnion) Populate(source any) error

func (*SchemaUnion) SetCore

func (u *SchemaUnion) SetCore(c *core.SchemaUnion)

SetCore sets the low level representation of the schema union.

func (*SchemaUnion) Validate

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

Validate validates whichever schema the union holds.

type Type

Type is the value of the `type` keyword: either a list of types or a single type.

func NewTypeFromArray

func NewTypeFromArray(types ...string) *Type

NewTypeFromArray creates a `type` value with a list of types.

func NewTypeFromString

func NewTypeFromString(typ string) *Type

NewTypeFromString creates a `type` value with a single type.

Directories

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

Jump to

Keyboard shortcuts

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