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 ¶
- func WithSchemaFormat(schemaFormat string) validation.Option
- type Dependency
- type ExternalDocumentation
- func (e *ExternalDocumentation) GetDescription() string
- func (e *ExternalDocumentation) GetExtensions() *extensions.Extensions
- func (e *ExternalDocumentation) GetURL() string
- func (e *ExternalDocumentation) IsReference() bool
- func (e *ExternalDocumentation) Validate(_ context.Context, _ ...validation.Option) []error
- type Items
- type JSONSchema
- func (j *JSONSchema) GetBool() *bool
- func (j *JSONSchema) GetRef() references.Reference
- func (j *JSONSchema) GetSchema() *Schema
- func (j *JSONSchema) IsBool() bool
- func (j *JSONSchema) IsReference() bool
- func (j *JSONSchema) IsSchema() bool
- func (j *JSONSchema) Validate(ctx context.Context, opts ...validation.Option) []error
- type MultiFormatSchema
- type Schema
- func (s *Schema) GetDeprecated() bool
- func (s *Schema) GetDiscriminator() string
- func (s *Schema) GetExtensions() *extensions.Extensions
- func (s *Schema) GetExternalDocs() *ExternalDocumentation
- func (s *Schema) GetProperties() *sequencedmap.Map[string, *JSONSchema]
- func (s *Schema) GetRef() references.Reference
- func (s *Schema) GetRequired() []string
- func (s *Schema) GetType() []string
- func (s *Schema) IsReference() bool
- func (s *Schema) Validate(ctx context.Context, opts ...validation.Option) []error
- type SchemaDefinition
- func (d *SchemaDefinition) GetCore() *core.SchemaDefinition
- func (d *SchemaDefinition) GetRaw() values.Value
- func (d *SchemaDefinition) GetReference() references.Reference
- func (d *SchemaDefinition) GetRootNode() *yaml.Node
- func (d *SchemaDefinition) GetSchema() *JSONSchema
- func (d *SchemaDefinition) IsReference() bool
- func (d *SchemaDefinition) Populate(source any) error
- func (d *SchemaDefinition) SetCore(c *core.SchemaDefinition)
- type SchemaUnion
- func (u *SchemaUnion) GetCore() *core.SchemaUnion
- func (u *SchemaUnion) GetMultiFormat() *MultiFormatSchema
- func (u *SchemaUnion) GetRef() references.Reference
- func (u *SchemaUnion) GetRootNode() *yaml.Node
- func (u *SchemaUnion) GetSchema() *JSONSchema
- func (u *SchemaUnion) GetSchemaFormat(asyncAPIVersion string) string
- func (u *SchemaUnion) IsMultiFormat() bool
- func (u *SchemaUnion) IsReference() bool
- func (u *SchemaUnion) IsSchema() bool
- func (u *SchemaUnion) Populate(source any) error
- func (u *SchemaUnion) SetCore(c *core.SchemaUnion)
- func (u *SchemaUnion) Validate(ctx context.Context, opts ...validation.Option) []error
- type Type
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 ¶
func (e *ExternalDocumentation) Validate(_ context.Context, _ ...validation.Option) []error
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) GetRootNode ¶
GetRootNode returns the node the items value was parsed from.
type JSONSchema ¶
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 ¶
GetDeprecated returns true if the schema is marked as deprecated.
func (*Schema) GetDiscriminator ¶
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 ¶
GetRequired returns the required property names, or nil if not set.
func (*Schema) GetType ¶
GetType returns the declared types of the schema, or nil if no type is declared.
func (*Schema) IsReference ¶
IsReference returns true if the schema is a Reference Object.
func (*Schema) Validate ¶
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 Type = values.EitherValue[[]string, []marshaller.Node[string], string, string]
Type is the value of the `type` keyword: either a list of types or a single type.
func NewTypeFromArray ¶
NewTypeFromArray creates a `type` value with a list of types.
func NewTypeFromString ¶
NewTypeFromString creates a `type` value with a single type.