Documentation
¶
Overview ¶
Package schema provides utilities for creating and working with JSON schemas for structured output in AgentMesh.
Overview ¶
The schema package enables type-safe structured output from language models by:
- Generating JSON schemas from Go structs with jsonschema tags
- Creating schemas from maps for flexibility
- Validating values against schemas
- Extracting and parsing structured outputs from model responses
Basic Usage ¶
Define a struct with jsonschema tags:
type Person struct {
Name string `json:"name" jsonschema:"required,description=Person's full name"`
Age int `json:"age" jsonschema:"required,minimum=0,maximum=150"`
Email string `json:"email" jsonschema:"format=email"`
}
Create an OutputSchema:
outputSchema, err := schema.NewOutputSchema("person", Person{},
schema.WithStrict(true),
schema.WithDescription("Extracts person information"),
)
Use with model requests:
req := &model.Request{
Messages: messages,
OutputSchema: &outputSchema,
}
Extract structured output:
person, err := model.LastStructured[Person](mdl.Generate(ctx, req))
Supported Tags ¶
The package supports standard jsonschema struct tags:
- required: Mark field as required
- description: Field description
- minimum, maximum: Numeric constraints
- minLength, maxLength: String length constraints
- enum: Allowed values (comma-separated)
- format: Format validation (email, date-time, uri, etc.)
- default: Default value
Extracting Structured Output ¶
Use graph.LastStructured to extract and parse the last message from an agent or graph:
result, err := graph.LastStructured[AnalysisResult](compiled.Run(ctx, input))
For model-level responses, use model.LastStructured:
result, err := model.LastStructured[MovieReview](mdl.Generate(ctx, req))
Validation ¶
Validate JSON output against schemas using the Validator interface:
validator := schema.NewValidator()
result, err := validator.Validate(ctx, outputSchema.Schema, jsonString)
if !result.Valid {
for _, e := range result.Errors {
fmt.Printf("Validation error at %s: %s\n", e.Path, e.Message)
}
}
Package schema provides sentinel errors for the schema package.
Package schema provides utilities for creating and working with JSON schemas for structured output in AgentMesh agents and models.
Index ¶
- Variables
- func WithAllowAdditionalProperties(allow bool) func(*OutputSchemaOptions)
- func WithDescription(description string) func(*OutputSchemaOptions)
- func WithStrict(strict bool) func(*OutputSchemaOptions)
- func WithValidationPolicy(policy ValidationPolicy) func(*OutputSchemaOptions)
- type DefaultValidator
- type FailureAction
- type OutputSchema
- type OutputSchemaOptions
- type ValidationError
- type ValidationPolicy
- type ValidationResult
- type Validator
Constants ¶
This section is empty.
Variables ¶
var ( // ErrMissingType is returned when output schema is missing 'type'. ErrMissingType = errors.New("schema: output schema missing 'type'") // ErrMissingProperties is returned when output schema is missing 'properties'. ErrMissingProperties = errors.New("schema: output schema missing 'properties'") // ErrMissingRequired is returned when output schema is missing 'required'. ErrMissingRequired = errors.New("schema: output schema missing 'required'") )
Functions ¶
func WithAllowAdditionalProperties ¶
func WithAllowAdditionalProperties(allow bool) func(*OutputSchemaOptions)
WithAllowAdditionalProperties sets whether to allow additional properties not defined in the schema. Default: false
func WithDescription ¶
func WithDescription(description string) func(*OutputSchemaOptions)
WithDescription sets a description for the schema.
func WithStrict ¶
func WithStrict(strict bool) func(*OutputSchemaOptions)
WithStrict sets whether to enable strict mode for the schema. Strict mode behavior is provider-specific (e.g., OpenAI's strict JSON schema mode). Default: true
func WithValidationPolicy ¶
func WithValidationPolicy(policy ValidationPolicy) func(*OutputSchemaOptions)
WithValidationPolicy sets the post-generation validation policy. When enabled, generated output is validated against the schema with optional retries.
Types ¶
type DefaultValidator ¶
type DefaultValidator struct{}
DefaultValidator validates output against a JSON schema. It implements the Validator interface using the internal jsonschema library.
func NewValidator ¶
func NewValidator() *DefaultValidator
NewValidator creates a new default validator. This is the default Validator implementation using internal/jsonschema.
func (*DefaultValidator) Validate ¶
func (v *DefaultValidator) Validate(_ context.Context, schema map[string]any, output string) (*ValidationResult, error)
Validate checks if output conforms to the schema using the jsonschema library.
type FailureAction ¶
type FailureAction string
FailureAction defines what happens when validation fails after all retries.
const ( // FailOnError returns an error (default). FailOnError FailureAction = "fail" // WarnOnError logs a warning but returns the invalid output. WarnOnError FailureAction = "warn" // IgnoreOnError silently returns the invalid output. IgnoreOnError FailureAction = "ignore" )
type OutputSchema ¶
type OutputSchema struct {
Name string // Schema name/identifier
Strict bool // Enable strict mode (provider-specific)
Description string // Schema description
Schema map[string]any // The actual JSON schema
Validation *ValidationPolicy // Post-generation validation settings
}
OutputSchema represents a structured output schema with metadata.
func NewOutputSchema ¶
func NewOutputSchema[T any](name string, schema T, optFns ...func(*OutputSchemaOptions)) (OutputSchema, error)
NewOutputSchema creates an OutputSchema from a struct type or map[string]any. The function uses generics to accept either:
- A struct type (generates schema via reflection and jsonschema tags)
- A map[string]any (uses the map directly as the schema)
Example with struct:
type Person struct {
Name string `json:"name" jsonschema:"required,description=Person's name"`
Age int `json:"age" jsonschema:"required,minimum=0,maximum=150"`
}
schema, err := schema.NewOutputSchema("person", Person{})
Example with map:
schemaMap := map[string]any{
"type": "object",
"properties": map[string]any{
"name": map[string]any{"type": "string"},
},
"required": []string{"name"},
}
schema, err := schema.NewOutputSchema("person", schemaMap)
The function validates that the schema contains required fields: type, properties, and required.
type OutputSchemaOptions ¶
type OutputSchemaOptions struct {
Strict bool
Description string
AllowAdditionalProperties bool
Validation *ValidationPolicy
}
OutputSchemaOptions configures OutputSchema creation.
type ValidationError ¶
type ValidationError struct {
// Path is the JSON path to the error.
Path string
// Message describes the error.
Message string
// Expected is what the schema expected.
Expected string
// Actual is what was found.
Actual string
}
ValidationError represents a schema validation error.
type ValidationPolicy ¶
type ValidationPolicy struct {
// Enabled activates post-generation validation.
Enabled bool
// MaxRetries is the number of retry attempts with error feedback (0 = no retries, strict mode).
MaxRetries int
// OnFailure determines behavior when validation fails after all retries.
OnFailure FailureAction
// Validator is the custom validator to use. If nil, the DefaultValidator is used.
Validator Validator
}
ValidationPolicy controls post-generation schema validation behavior.
func ValidationDisabled ¶
func ValidationDisabled() ValidationPolicy
ValidationDisabled returns a policy that disables validation.
func ValidationStrict ¶
func ValidationStrict() ValidationPolicy
ValidationStrict returns a policy that fails immediately on validation error.
func ValidationWarnOnly ¶
func ValidationWarnOnly() ValidationPolicy
ValidationWarnOnly returns a policy that logs warnings but doesn't fail.
func ValidationWithRetry ¶
func ValidationWithRetry(maxRetries int) ValidationPolicy
ValidationWithRetry returns a policy that retries with error feedback.
type ValidationResult ¶
type ValidationResult struct {
// Valid indicates if the output matches the schema.
Valid bool
// Errors contains validation errors.
Errors []ValidationError
// ParsedData is the parsed JSON data (if valid JSON).
ParsedData any
}
ValidationResult contains the result of schema validation.
type Validator ¶
type Validator interface {
// Validate checks if output conforms to the schema.
Validate(ctx context.Context, schema map[string]any, output string) (*ValidationResult, error)
}
Validator defines the interface for schema validation. Implementations can provide custom validation logic.
Source Files