schema

package
v0.2.0 Latest Latest
Warning

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

 Go to latest Published: Dec 16, 2025 License: MIT Imports: 4 Imported by: 0

Documentation

Overview

Package schema provides a fluent API for building JSON Schema objects for use with AI tool parameters and structured output.

Unlike reflection-based approaches, this package uses pure programmatic construction with compile-time type safety and build-time validation.

Basic Usage

Create schemas using the type constructors and chain constraint methods: 

params := schema.Object().
	Field("location", schema.String().Desc("City name").Required()).
	Field("unit", schema.String().Enum("celsius", "fahrenheit")).
	Field("days", schema.Int().Min(1).Max(14).Default(7)).
	MustBuild()

With Tool Definitions 

tool := gains.Tool{
	Name:        "get_forecast",
	Description: "Get weather forecast",
	Parameters: schema.Object().
		Field("location", schema.String().Required()).
		Field("days", schema.Int().Min(1).Max(14)).
		MustBuild(),
}

Response Schemas 

resp := gains.ResponseSchema{
	Name: "book_info",
	Schema: schema.Object().
		Field("title", schema.String().Required()).
		Field("year", schema.Int().Min(1000).Max(2100)).
		MustBuild(),
}

Nested Objects 

params := schema.Object().
	Field("user", schema.Object().
		Field("name", schema.String().Required()).
		Field("age", schema.Int().Min(0)).
		Required()).
	Field("tags", schema.Array(schema.String()).MaxItems(10)).
	MustBuild()

String Constraints 

schema.String().
	MinLength(1).
	MaxLength(100).
	Pattern(`^[a-z]+$`).
	Build()

Numeric Constraints 

schema.Int().Min(1).Max(100).Build()
schema.Number().ExclusiveMin(0).ExclusiveMax(1.0).Build()

Array Constraints 

schema.Array(schema.String()).
	MinItems(1).
	MaxItems(10).
	UniqueItems().
	Build()

Validation

Use Build() instead of MustBuild() to handle errors: 

params, err := schema.Object().
	Field("count", schema.Int().Min(10).Max(5)). // Error: min > max
	Build()
if err != nil {
	log.Fatal(err) // schema: minimum exceeds maximum
}

OpenAI Strict Mode

For OpenAI compatibility, use StrictMode() which sets additionalProperties to false: 

params := schema.Object().
	StrictMode().
	Field("name", schema.String().Required()).
	MustBuild()

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrInvalidRange is returned when min exceeds max.
	ErrInvalidRange = errors.New("schema: minimum exceeds maximum")

	// ErrInvalidPattern is returned when a regex pattern is invalid.
	ErrInvalidPattern = errors.New("schema: invalid regex pattern")

	// ErrNilItems is returned when an array has no items schema.
	ErrNilItems = errors.New("schema: array requires items schema")
)

Sentinel errors for schema validation.

Functions

This section is empty.

Types

type ArrayBuilder 

type ArrayBuilder struct {
	// contains filtered or unexported fields
}

ArrayBuilder constructs array type schemas.

func Array 

func Array(items Builder) *ArrayBuilder

Array creates a new array schema builder with the specified item type.

func (*ArrayBuilder) Build 

func (b *ArrayBuilder) Build() (json.RawMessage, error)

Build serializes the schema to json.RawMessage.

func (*ArrayBuilder) Desc 

func (b *ArrayBuilder) Desc(description string) *ArrayBuilder

Desc sets the description.

func (*ArrayBuilder) MaxItems 

func (b *ArrayBuilder) MaxItems(n int) *ArrayBuilder

MaxItems sets the maximum number of items.

func (*ArrayBuilder) MinItems 

func (b *ArrayBuilder) MinItems(n int) *ArrayBuilder

MinItems sets the minimum number of items.

func (*ArrayBuilder) MustBuild 

func (b *ArrayBuilder) MustBuild() json.RawMessage

MustBuild is like Build but panics on error.

func (*ArrayBuilder) Required 

func (b *ArrayBuilder) Required() *RequiredField

Required marks this field as required when used in an object.

func (*ArrayBuilder) UniqueItems 

func (b *ArrayBuilder) UniqueItems() *ArrayBuilder

UniqueItems requires all items to be unique.

type BoolBuilder 

type BoolBuilder struct {
	// contains filtered or unexported fields
}

BoolBuilder constructs boolean type schemas.

func Bool 

func Bool() *BoolBuilder

Bool creates a new boolean schema builder.

func Boolean 

func Boolean() *BoolBuilder

Boolean is an alias for Bool.

func (*BoolBuilder) Build 

func (b *BoolBuilder) Build() (json.RawMessage, error)

Build serializes the schema to json.RawMessage.

func (*BoolBuilder) Default 

func (b *BoolBuilder) Default(value bool) *BoolBuilder

Default sets the default value.

func (*BoolBuilder) Desc 

func (b *BoolBuilder) Desc(description string) *BoolBuilder

Desc sets the description.

func (*BoolBuilder) MustBuild 

func (b *BoolBuilder) MustBuild() json.RawMessage

MustBuild is like Build but panics on error.

func (*BoolBuilder) Required 

func (b *BoolBuilder) Required() *RequiredField

Required marks this field as required when used in an object.

type Builder 

type Builder interface {
	// Build serializes the schema to json.RawMessage.
	// Returns an error if the schema is invalid.
	Build() (json.RawMessage, error)

	// MustBuild is like Build but panics on error.
	MustBuild() json.RawMessage
	// contains filtered or unexported methods
}

Builder is the interface implemented by all schema builders. It provides a fluent API for constructing JSON Schema objects.

type IntBuilder 

type IntBuilder struct {
	// contains filtered or unexported fields
}

IntBuilder constructs integer type schemas.

func Int 

func Int() *IntBuilder

Int creates a new integer schema builder.

func Integer 

func Integer() *IntBuilder

Integer is an alias for Int.

func (*IntBuilder) Build 

func (b *IntBuilder) Build() (json.RawMessage, error)

Build serializes the schema to json.RawMessage.

func (*IntBuilder) Default 

func (b *IntBuilder) Default(value int) *IntBuilder

Default sets the default value.

func (*IntBuilder) Desc 

func (b *IntBuilder) Desc(description string) *IntBuilder

Desc sets the description.

func (*IntBuilder) Enum 

func (b *IntBuilder) Enum(values ...int) *IntBuilder

Enum restricts the value to specific integers.

func (*IntBuilder) ExclusiveMax 

func (b *IntBuilder) ExclusiveMax(n int) *IntBuilder

ExclusiveMax sets the exclusive maximum value.

func (*IntBuilder) ExclusiveMin 

func (b *IntBuilder) ExclusiveMin(n int) *IntBuilder

ExclusiveMin sets the exclusive minimum value.

func (*IntBuilder) Max 

func (b *IntBuilder) Max(n int) *IntBuilder

Max sets the maximum value (inclusive).

func (*IntBuilder) Min 

func (b *IntBuilder) Min(n int) *IntBuilder

Min sets the minimum value (inclusive).

func (*IntBuilder) MustBuild 

func (b *IntBuilder) MustBuild() json.RawMessage

MustBuild is like Build but panics on error.

func (*IntBuilder) Required 

func (b *IntBuilder) Required() *RequiredField

Required marks this field as required when used in an object.

type NumberBuilder 

type NumberBuilder struct {
	// contains filtered or unexported fields
}

NumberBuilder constructs number (float) type schemas.

func Number 

func Number() *NumberBuilder

Number creates a new number (float) schema builder.

func (*NumberBuilder) Build 

func (b *NumberBuilder) Build() (json.RawMessage, error)

Build serializes the schema to json.RawMessage.

func (*NumberBuilder) Default 

func (b *NumberBuilder) Default(value float64) *NumberBuilder

Default sets the default value.

func (*NumberBuilder) Desc 

func (b *NumberBuilder) Desc(description string) *NumberBuilder

Desc sets the description.

func (*NumberBuilder) Enum 

func (b *NumberBuilder) Enum(values ...float64) *NumberBuilder

Enum restricts the value to specific numbers.

func (*NumberBuilder) ExclusiveMax 

func (b *NumberBuilder) ExclusiveMax(n float64) *NumberBuilder

ExclusiveMax sets the exclusive maximum value.

func (*NumberBuilder) ExclusiveMin 

func (b *NumberBuilder) ExclusiveMin(n float64) *NumberBuilder

ExclusiveMin sets the exclusive minimum value.

func (*NumberBuilder) Max 

func (b *NumberBuilder) Max(n float64) *NumberBuilder

Max sets the maximum value (inclusive).

func (*NumberBuilder) Min 

func (b *NumberBuilder) Min(n float64) *NumberBuilder

Min sets the minimum value (inclusive).

func (*NumberBuilder) MustBuild 

func (b *NumberBuilder) MustBuild() json.RawMessage

MustBuild is like Build but panics on error.

func (*NumberBuilder) Required 

func (b *NumberBuilder) Required() *RequiredField

Required marks this field as required when used in an object.

type ObjectBuilder 

type ObjectBuilder struct {
	// contains filtered or unexported fields
}

ObjectBuilder constructs object type schemas.

func Object 

func Object() *ObjectBuilder

Object creates a new object schema builder.

func (*ObjectBuilder) AdditionalProperties 

func (b *ObjectBuilder) AdditionalProperties(allowed bool) *ObjectBuilder

AdditionalProperties controls whether extra properties are allowed. OpenAI strict mode requires this to be false.

func (*ObjectBuilder) Build 

func (b *ObjectBuilder) Build() (json.RawMessage, error)

Build serializes the schema to json.RawMessage.

func (*ObjectBuilder) Desc 

func (b *ObjectBuilder) Desc(description string) *ObjectBuilder

Desc sets the description for the object itself.

func (*ObjectBuilder) Field 

func (b *ObjectBuilder) Field(name string, field any) *ObjectBuilder

Field adds a field with its schema. The field argument can be a Builder or a *RequiredField.

func (*ObjectBuilder) MustBuild 

func (b *ObjectBuilder) MustBuild() json.RawMessage

MustBuild is like Build but panics on error.

func (*ObjectBuilder) Required 

func (b *ObjectBuilder) Required() *RequiredField

Required marks this object as required when nested in another object.

func (*ObjectBuilder) StrictMode 

func (b *ObjectBuilder) StrictMode() *ObjectBuilder

StrictMode sets additionalProperties to false for OpenAI compatibility.

type RequiredField 

type RequiredField struct {
	// contains filtered or unexported fields
}

RequiredField wraps a Builder to mark it as required in an object.

type StringBuilder 

type StringBuilder struct {
	// contains filtered or unexported fields
}

StringBuilder constructs string type schemas.

func String 

func String() *StringBuilder

String creates a new string schema builder.

func (*StringBuilder) Build 

func (b *StringBuilder) Build() (json.RawMessage, error)

Build serializes the schema to json.RawMessage.

func (*StringBuilder) Default 

func (b *StringBuilder) Default(value string) *StringBuilder

Default sets the default value.

func (*StringBuilder) Desc 

func (b *StringBuilder) Desc(description string) *StringBuilder

Desc sets the description for this field.

func (*StringBuilder) Enum 

func (b *StringBuilder) Enum(values ...string) *StringBuilder

Enum restricts the value to one of the provided options.

func (*StringBuilder) MaxLength 

func (b *StringBuilder) MaxLength(n int) *StringBuilder

MaxLength sets the maximum string length.

func (*StringBuilder) MinLength 

func (b *StringBuilder) MinLength(n int) *StringBuilder

MinLength sets the minimum string length.

func (*StringBuilder) MustBuild 

func (b *StringBuilder) MustBuild() json.RawMessage

MustBuild is like Build but panics on error.

func (*StringBuilder) Pattern 

func (b *StringBuilder) Pattern(regex string) *StringBuilder

Pattern sets a regex pattern the string must match.

func (*StringBuilder) Required 

func (b *StringBuilder) Required() *RequiredField

Required marks this field as required when used in an object. Returns a RequiredField wrapper for use with ObjectBuilder.Field().

type ValidationError 

type ValidationError struct {
	Field   string // The field name (for objects)
	Message string // Human-readable error message
	Err     error  // Underlying error
}

ValidationError represents a schema validation failure.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap 

func (e *ValidationError) Unwrap() error

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.