Documentation
¶
Overview ¶
Package schema provides helpers to generate JSON Schemas from Go types and shape those schemas for LLM prompting. It is used throughout the project to derive structured parameter definitions and response formats from Go structs.
Core ideas
- Reflect Go structs and produce a jsonschema (draft-07) model.
- Convert reflected schema to a compact “function parameter” schema where top-level properties are flattened and $ref entries are resolved.
- Build OpenAI-style JSON Schema response formats to steer model outputs.
Common usage ¶
Generate a schema from a struct and use it as function parameters:
type Search struct {
Query string `json:"query" jsonschema:"description=Query to search"`
Type string `json:"type" jsonschema:"description=Type of search,enum=web,enum=image,default=web"`
}
s, err := New(reflect.TypeOf(Search{}))
if err != nil { /* handle */ }
_ = s.Parameters // jsonschema.Schema describing parameters
Build a response format (OpenAI style) from a type:
rf, err := NewResponseFormat(reflect.TypeOf(Search{}), true)
if err != nil { /* handle */ }
// rf.Type == "json_schema" and rf.JSONSchema contains the strict schema
You can also construct a schema from an arbitrary map using FromAny/MustFromAny when you want explicit control over the resulting structure.
Index ¶
- func FromAny(t any) (*jsonschema.Schema, error)
- func JSONSchema(t reflect.Type) *jsonschema.Schema
- func MustFromAny(t any) *jsonschema.Schema
- func ToFunctionSchema(tType reflect.Type, tSchema *jsonschema.Schema) *jsonschema.Schema
- type Faker
- type ResponseFormat
- type ResponseFormatJSONSchema
- type ResponseFormatJSONSchemaProperty
- type Schema
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func FromAny ¶ added in v0.10.55
func FromAny(t any) (*jsonschema.Schema, error)
FromAny creates a jsonschema.Schema from an arbitrary value, returning an error if the input is invalid.
func JSONSchema ¶
func JSONSchema(t reflect.Type) *jsonschema.Schema
JSONSchema returns the jsonschema model for a type using invopop/jsonschema. The reflector is configured to produce expanded structs and stable names to avoid collisions across packages with identically-named structs.
func MustFromAny ¶ added in v0.10.55
func MustFromAny(t any) *jsonschema.Schema
MustFromAny creates a jsonschema.Schema from an arbitrary value. It panics if the input cannot be marshaled into a valid schema. Useful in tests or when construction failures should be considered programmer errors.
func ToFunctionSchema ¶
func ToFunctionSchema(tType reflect.Type, tSchema *jsonschema.Schema) *jsonschema.Schema
ToFunctionSchema converts a reflected Schema into a simplified, top-level object schema by resolving local $ref entries and exposing first-level properties directly. This structure is more suitable for function/tool parameter documentation.
Types ¶
type Faker ¶
type Faker interface {
Fake() any
}
Faker is an interface for generating structures with fake data. It can be implemented by custom types to provide exemplar values used in tests or documentation.
type ResponseFormat ¶ added in v0.10.55
type ResponseFormat struct {
Type string `json:"type"`
JSONSchema *ResponseFormatJSONSchema `json:"json_schema,omitempty"`
}
ResponseFormat defines the LLM response format. Currently supports a JSON Schema variant compatible with OpenAI’s response_format.
func NewResponseFormat ¶ added in v0.10.55
func NewResponseFormat(t reflect.Type, strict bool) (*ResponseFormat, error)
NewResponseFormat builds an OpenAI-style JSON Schema response format from the provided Go type. When strict is true, additionalProperties are disabled for objects and only defined fields are allowed.
type ResponseFormatJSONSchema ¶ added in v0.10.55
type ResponseFormatJSONSchema struct {
Name string `json:"name"`
Strict bool `json:"strict"`
Schema *ResponseFormatJSONSchemaProperty `json:"schema"`
}
ResponseFormatJSONSchema is the container for the top-level JSON Schema definition used in prompts, including the schema name and strictness.
type ResponseFormatJSONSchemaProperty ¶ added in v0.10.55
type ResponseFormatJSONSchemaProperty struct {
Type string `json:"type"`
Title string `json:"title,omitempty"`
Description string `json:"description,omitempty"`
Enum []any `json:"enum,omitempty"`
Default any `json:"default,omitempty"`
Examples []any `json:"examples,omitempty"`
Items *ResponseFormatJSONSchemaProperty `json:"items,omitempty"`
Properties map[string]*ResponseFormatJSONSchemaProperty `json:"properties,omitempty"`
AdditionalProperties *bool `json:"additionalProperties,omitempty"`
Required []string `json:"required,omitempty"`
Ref string `json:"$ref,omitempty"`
}
ResponseFormatJSONSchemaProperty represents a property within the flattened JSON Schema used for prompting. Only fields relevant for LLM guidance are retained and rendered.
type Schema ¶
type Schema struct {
RawSchema *jsonschema.Schema
// Parameters represents the Function parameters definition
Parameters *jsonschema.Schema
}
func New ¶
New creates a new Schema from the given Go type. The result contains both the raw reflected jsonschema and a flattened Parameters schema suitable for use as tool/function parameters.
Source Files