schema

Documentation

Overview

Package schema defines the pure data model for describing value shapes.

A Schema value carries the JSON/YAML/OpenAPI/AsyncAPI description of a Go type: its JSON Schema type, properties, constraints (minimum, maximum, minLength, pattern, enum, …), description, title, example, and deprecation flag.

The schema package has zero dependencies inside the module — it is imported by codex (to annotate codecs), by render/openapi and render/asyncapi (to emit specs), and by validate (to annotate constraints). Nothing in schema knows about codecs, renderers, or adapters.

Typical usage:

// Schema values are produced by codecs — you rarely construct them directly.
var s schema.Schema = codex.String().
    Refine(validate.Email).
    WithDescription("Primary email address.").
    Schema
// s.Type == "string", s.Format == "email", s.Description == "Primary email address."

Renderers such as render/openapi and render/asyncapi/v3 accept map[string]Schema and emit the corresponding spec document.

Index

• type DiscriminatorSchema
• type Property
• type Schema
  • func (s Schema) IsZero() bool
  • func (s Schema) Prop(name string) (Schema, bool)

Types

type DiscriminatorSchema

type DiscriminatorSchema struct {
	// PropertyName is the name of the property that holds the type tag.
	PropertyName string `json:",omitempty"`
	// Mapping is an optional explicit tag-value → $ref map.
	Mapping map[string]string `json:",omitempty"`
}

DiscriminatorSchema describes the polymorphism discriminator field used in TaggedUnion schemas. It maps to the OpenAPI 3.x / AsyncAPI discriminator object.

type Property

type Property struct {
	Name   string
	Schema Schema
}

Property is a named schema entry inside an object's properties list. Using a slice of Property (rather than a map) preserves the registration order, giving deterministic YAML/JSON output across runs.

type Schema

type Schema struct {
	Type        string     `json:",omitempty"`
	Title       string     `json:",omitempty"`
	Description string     `json:",omitempty"`
	Format      string     `json:",omitempty"`
	Example     any        `json:",omitempty"`
	Properties  []Property `json:",omitempty"`
	Required    []string   `json:",omitempty"`
	Enum        []any      `json:",omitempty"`
	OneOf       []Schema   `json:",omitempty"`
	Items       *Schema    `json:",omitempty"`

	// Nullable marks the value as accepting null in addition to its type.
	// Renders as "nullable: true" in OpenAPI 3.0 / AsyncAPI.
	Nullable bool `json:",omitempty"`

	// AdditionalProperties controls whether undeclared properties are allowed.
	// nil = unset (spec default), false = no additional properties, true = any allowed.
	AdditionalProperties *bool `json:",omitempty"`

	// AdditionalPropertiesSchema constrains the type of additional properties.
	// When set, takes precedence over AdditionalProperties and renders as a schema object.
	// Used by StringMap to express map[string]V where V has a specific schema.
	AdditionalPropertiesSchema *Schema `json:",omitempty"`

	// PropertyNames constrains the format of map keys.
	// Corresponds to the JSON Schema "propertyNames" keyword.
	// Used by Map[K, V] to express the key codec's schema (e.g. pattern, format).
	PropertyNames *Schema `json:",omitempty"`

	// Discriminator describes the polymorphism tag for TaggedUnion schemas.
	Discriminator *DiscriminatorSchema `json:",omitempty"`

	// Numeric constraints.
	Minimum          *float64 `json:",omitempty"`
	Maximum          *float64 `json:",omitempty"`
	ExclusiveMinimum bool     `json:",omitempty"`
	ExclusiveMaximum bool     `json:",omitempty"`

	// String constraints.
	MinLength *int   `json:",omitempty"`
	MaxLength *int   `json:",omitempty"`
	Pattern   string `json:",omitempty"`

	// Deprecated marks this schema as deprecated in generated documentation.
	Deprecated bool `json:",omitempty"`

	// Default is the default value for this schema, used when the field is absent.
	Default any `json:",omitempty"`
}

Schema describes the shape of a value for documentation and validation purposes.

func (Schema) IsZero

func (s Schema) IsZero() bool

IsZero reports whether s is the zero value — i.e. no schema data has been set. Use this instead of comparing Schema.Type to "" to guard against future field additions.

func (Schema) Prop

func (s Schema) Prop(name string) (Schema, bool)

Prop returns the schema for the named property, and true if it was found.