schema

Documentation

Index

• func New[T any](store *store.Store) *base.SchemaProxy
• func ToYAMLNode(v any) *yaml.Node
• func TypeOf(i any, store *store.Store) *base.SchemaProxy
• type Option
  • func AdditionalProperties[T any]() Option
  • func AllOf(types ...TypeGetter) Option
  • func AnyOf(types ...TypeGetter) Option
  • func AnyOfUnion[T any]() Option
  • func Const(v any) Option
  • func Contains[T any]() Option
  • func ContentEncoding(s string) Option
  • func ContentMediaType(s string) Option
  • func DateTime() Option
  • func Default(v any) Option
  • func DependentRequired(property string, required ...string) Option
  • func DependentSchemas[T any](property string) Option
  • func Deprecated() Option
  • func Description(s string) Option
  • func Else[T any]() Option
  • func Email() Option
  • func Enum(values ...any) Option
  • func Example(v any) Option
  • func Examples(values ...any) Option
  • func ExclusiveMaximum(v float64) Option
  • func ExclusiveMinimum(v float64) Option
  • func ExternalDocs(url, description string) Option
  • func Field(name string, opts ...Option) Option
  • func Format(s string) Option
  • func If[T any]() Option
  • func MaxContains(n int64) Option
  • func MaxItems(n int64) Option
  • func MaxLength(n int64) Option
  • func MaxProperties(n int64) Option
  • func Maximum(v float64) Option
  • func MinContains(n int64) Option
  • func MinItems(n int64) Option
  • func MinLength(n int64) Option
  • func MinProperties(n int64) Option
  • func Minimum(v float64) Option
  • func MultipleOf(v float64) Option
  • func Not[T any]() Option
  • func Nullable() Option
  • func OneOf(types ...TypeGetter) Option
  • func OneOfUnion[T any]() Option
  • func Options(opts ...Option) Option
  • func Pattern(p string) Option
  • func PatternProperties(pattern string, opts ...Option) Option
  • func PrefixItems(types ...TypeGetter) Option
  • func PropertyNames[T any]() Option
  • func ReadOnly() Option
  • func Reference(name string) Option
  • func Required(fields ...string) Option
  • func Then[T any]() Option
  • func Title(s string) Option
  • func UUID() Option
  • func UnevaluatedItems[T any]() Option
  • func UnevaluatedProperties[T any]() Option
  • func UniqueItems() Option
  • func WriteOnly() Option
  • func XMLAttribute() Option
  • func XMLName(name string) Option
  • func XMLNamespace(namespace string) Option
  • func XMLPrefix(prefix string) Option
  • func XMLWrapped() Option
• type Schema
• type State
• type Store
• type TypeGetter
  • func Type[T any]() TypeGetter

Functions

func New

func New[T any](store *store.Store) *base.SchemaProxy

New reflects T into an OpenAPI schema proxy. When T declares schema options with Reference, the returned proxy is a $ref.

func ToYAMLNode

func ToYAMLNode(v any) *yaml.Node

ToYAMLNode converts v into a YAML node suitable for libopenapi example-like fields.

func TypeOf

func TypeOf(i any, store *store.Store) *base.SchemaProxy

TypeOf reflects the dynamic type of i into an OpenAPI schema proxy.

Types

type Option

type Option func(*base.Schema, *Store)

Option configures an OpenAPI schema. May be returned from a type implementing the Schema interface:

func (T) Schema() Option

func AdditionalProperties

func AdditionalProperties[T any]() Option

AdditionalProperties overrides the default closed-object behavior for structs. Use AdditionalProperties[any]() to allow any extra fields, or a concrete type to constrain their schema.

func AllOf

func AllOf(types ...TypeGetter) Option

AllOf requires the value to be valid against all of the given schemas.

AllOf(Type[A](), Type[B]()))

func AnyOf

func AnyOf(types ...TypeGetter) Option

AnyOf requires the value to be valid against at least one of the given schemas.

AnyOf(Type[A](), Type[B]()))

func AnyOfUnion

func AnyOfUnion[T any]() Option

AnyOfUnion expands a union.Union or union.TaggedUnion type T into anyOf case schemas.

func Const

func Const(v any) Option

Const restricts the schema to a single constant value.

func Contains

func Contains[T any]() Option

Contains sets the schema that at least one item in the array must validate against (OpenAPI 3.1).

func ContentEncoding

func ContentEncoding(s string) Option

ContentEncoding sets the encoding for string content (e.g. "base64", "quoted-printable").

func ContentMediaType

func ContentMediaType(s string) Option

ContentMediaType sets the MIME type of string content (e.g. "image/png", "application/pdf").

func DateTime

func DateTime() Option

DateTime sets the format to "date-time".

func Default

func Default(v any) Option

Default sets the default value used when the field is absent.

func DependentRequired

func DependentRequired(property string, required ...string) Option

DependentRequired specifies properties that are required when the named property is present (OpenAPI 3.1).

func DependentSchemas

func DependentSchemas[T any](property string) Option

DependentSchemas sets the schema that must validate when the named property is present (OpenAPI 3.1).

func Deprecated

func Deprecated() Option

Deprecated marks the schema as deprecated. Default: false.

func Description

func Description(s string) Option

Description sets the schema description.

func Else

func Else[T any]() Option

Else sets the schema applied when If does not validate (OpenAPI 3.1).

func Email

func Email() Option

Email sets the format to "email".

func Enum

func Enum(values ...any) Option

Enum restricts the schema to a fixed set of allowed values.

func Example

func Example(v any) Option

Example sets an example value for the schema.

func Examples

func Examples(values ...any) Option

Examples sets the array of example values for the schema (OpenAPI 3.1).

func ExclusiveMaximum

func ExclusiveMaximum(v float64) Option

ExclusiveMaximum sets the exclusive upper bound for a numeric value (OpenAPI 3.1).

func ExclusiveMinimum

func ExclusiveMinimum(v float64) Option

ExclusiveMinimum sets the exclusive lower bound for a numeric value (OpenAPI 3.1).

func ExternalDocs

func ExternalDocs(url, description string) Option

ExternalDocs attaches an external documentation link to the schema.

func Field

func Field(name string, opts ...Option) Option

Field applies options to a named property of a struct schema. If the property does not exist the option is a no-op.

func Format

func Format(s string) Option

Format sets the format hint for the schema (e.g. "date-time", "email", "uuid"). Prefer the named helpers (Email, UUID, DateTime) for common formats.

func If

func If[T any]() Option

If sets the conditional schema — if this validates, Then is applied; otherwise Else is applied (OpenAPI 3.1).

func MaxContains

func MaxContains(n int64) Option

MaxContains sets the maximum number of items that may validate against the contains schema.

func MaxItems

func MaxItems(n int64) Option

MaxItems sets the maximum number of elements in an array.

func MaxLength

func MaxLength(n int64) Option

MaxLength sets the maximum number of characters for a string value.

func MaxProperties

func MaxProperties(n int64) Option

MaxProperties sets the maximum number of properties an object may have.

func Maximum

func Maximum(v float64) Option

Maximum sets the inclusive upper bound for a numeric value.

func MinContains

func MinContains(n int64) Option

MinContains sets the minimum number of items that must validate against the contains schema.

func MinItems

func MinItems(n int64) Option

MinItems sets the minimum number of elements in an array.

func MinLength

func MinLength(n int64) Option

MinLength sets the minimum number of characters for a string value.

func MinProperties

func MinProperties(n int64) Option

MinProperties sets the minimum number of properties an object must have.

func Minimum

func Minimum(v float64) Option

Minimum sets the inclusive lower bound for a numeric value.

func MultipleOf

func MultipleOf(v float64) Option

MultipleOf requires the numeric value to be a multiple of the given number.

func Not

func Not[T any]() Option

Not requires the value to be invalid against the given schema.

func Nullable

func Nullable() Option

Nullable marks the schema as nullable (OpenAPI 3.0 compatibility). Default: false. In OpenAPI 3.1 prefer using a pointer type, which sets nullable automatically.

func OneOf

func OneOf(types ...TypeGetter) Option

OneOf requires the value to be valid against exactly one of the given schemas.

OneOf(Type[A](), Type[B]()))

func OneOfUnion

func OneOfUnion[T any]() Option

OneOfUnion expands a union.Union or union.TaggedUnion type T into oneOf case schemas.

func Options

func Options(opts ...Option) Option

Options combines multiple options into one.

func Pattern

func Pattern(p string) Option

Pattern restricts a string value to match the given regular expression.

func PatternProperties

func PatternProperties(pattern string, opts ...Option) Option

PatternProperties adds schema constraints for properties whose names match the given regex.

func PrefixItems

func PrefixItems(types ...TypeGetter) Option

PrefixItems sets the tuple validation schemas for each position in an array (OpenAPI 3.1). Pass zero values of each positional type (e.g. PrefixItems(int(0), "")).

func PropertyNames

func PropertyNames[T any]() Option

PropertyNames sets constraints on the names of object properties (OpenAPI 3.1).

func ReadOnly

func ReadOnly() Option

ReadOnly marks the schema as read-only — the value must not be sent in requests. Default: false.

func Reference

func Reference(name string) Option

Reference sets a $ref to a named schema component in components/schemas.

func Required

func Required(fields ...string) Option

Required overrides the required property list for an object schema. By default, non-pointer struct fields are required and pointer fields are optional.

func Then

func Then[T any]() Option

Then sets the schema applied when If validates (OpenAPI 3.1).

func Title

func Title(s string) Option

Title sets the schema title.

func UUID

func UUID() Option

UUID sets the format to "uuid".

func UnevaluatedItems

func UnevaluatedItems[T any]() Option

UnevaluatedItems sets the schema for array items not covered by items or prefixItems (OpenAPI 3.1).

func UnevaluatedProperties

func UnevaluatedProperties[T any]() Option

UnevaluatedProperties sets the schema for properties not covered by properties or patternProperties (OpenAPI 3.1). Use UnevaluatedProperties[any]() to allow any extra properties, or a concrete type to constrain them.

func UniqueItems

func UniqueItems() Option

UniqueItems requires all elements in an array to be distinct. Default: false.

func WriteOnly

func WriteOnly() Option

WriteOnly marks the schema as write-only — the value must not be included in responses. Default: false.

func XMLAttribute

func XMLAttribute() Option

XMLAttribute marks the property as an XML attribute rather than an element. Default: false.

func XMLName

func XMLName(name string) Option

XMLName sets the XML element or attribute name, overriding the property name.

func XMLNamespace

func XMLNamespace(namespace string) Option

XMLNamespace sets the URI of the XML namespace for the element.

func XMLPrefix

func XMLPrefix(prefix string) Option

XMLPrefix sets the prefix to use with the XML namespace.

func XMLWrapped

func XMLWrapped() Option

XMLWrapped wraps an array in an enclosing XML element. Default: false.

type Schema

type Schema interface {
	Schema() Option
}

Schema may be implemented to set default schema options on a type.

func (T) Schema() schema.Option

type State

type State struct {
	Reference string
}

State tracks transient schema build options that do not live directly on base.Schema.

type Store

type Store struct {
	*store.Store
	// contains filtered or unexported fields
}

Store wraps the shared component store with per-schema build state.

type TypeGetter

type TypeGetter func(store *store.Store) *base.SchemaProxy

TypeGetter lazily resolves a schema proxy using the provided component store.

func Type

func Type[T any]() TypeGetter

Type returns a TypeGetter for T for use with composition helpers such as OneOf and AllOf.