schema

Documentation

Overview

Package schema implements the small JSON Schema subset used to describe tool inputs to Claude, OpenAI, and Gemini. Most callers never construct a Schema by hand — agent.NewTool derives one automatically from a Go struct via FromStruct (see reflect.go). The type is exported so it can also be built or edited directly, e.g. to bridge in a tool whose schema is discovered at runtime (an MCP server) rather than known at compile time.

Index

• type Schema
  • func FromStruct[T any]() *Schema
  • func (s *Schema) MarshalJSON() ([]byte, error)
• type Type

Types

type Schema

type Schema struct {
	Type        Type
	Description string

	// Object
	Properties    map[string]*Schema
	PropertyOrder []string // declaration order; used to keep marshaling stable
	Required      []string

	// Array
	Items *Schema

	// String
	Enum []string
}

Schema is a JSON Schema document restricted to the subset every first-class provider's tool/function-declaration format understands: object/string/number/integer/boolean/array, nested properties, required lists, array items, and string enums.

func FromStruct

func FromStruct[T any]() *Schema

FromStruct derives a Schema for T via reflection. T is expected to be a struct type (or a pointer to one); every other kind is reflected as a best-effort leaf schema so FromStruct never panics.

Two struct tags drive generation:

• `json:"name,omitempty"` — the standard encoding/json tag. The field name becomes the schema property name; a `-` name excludes the field entirely; `omitempty` marks the field optional (see the required rule below).
• `jsonschema:"required,description=...,enum=a;b;c"` — recognized keys: "required" forces the field into the schema's required list; "description=" must be the last key present and consumes the rest of the tag verbatim (including any embedded commas), so a description can itself contain commas; "enum=" takes a semicolon-separated list (semicolon, not comma, so it survives the outer comma-split).

A field is required in the generated schema if it is explicitly tagged `required`, or if it is neither a pointer nor tagged `omitempty` — i.e. the same "zero value is meaningful vs. this is optional" convention Go developers already use for JSON marshaling.

func (*Schema) MarshalJSON

func (s *Schema) MarshalJSON() ([]byte, error)

MarshalJSON renders the schema as standard JSON Schema. Object properties are emitted in PropertyOrder so output is stable and diff-friendly rather than reordered on every call (Go map iteration order is randomized).

type Type

type Type string

Type is a JSON Schema primitive type.

const (
	TypeObject  Type = "object"
	TypeString  Type = "string"
	TypeNumber  Type = "number"
	TypeInteger Type = "integer"
	TypeBoolean Type = "boolean"
	TypeArray   Type = "array"
)