schema

Documentation

Overview

Package schema provides tag-driven defaults and validation for config structs.

Index

• Constants
• func Process(v any) []error
• type DocProvider
  • func ParseTypeDocs(srcs ...string) DocProvider
• type EnumDoc
• type EnumValueDoc
• type FieldDoc
• type OneOfGroup
• type SchemaDoc
  • func Describe(v any, version string, docs DocProvider) SchemaDoc
  • func FilterTypes(doc SchemaDoc, names map[string]bool) SchemaDoc
  • func (d SchemaDoc) KnownTypes() map[string]bool
• type StructDoc
• type TypeDoc

Constants

const ReservedContextKey = "agentsmithy"

ReservedContextKey is the template context key injected by the engine. It is the canonical definition shared across all config versions.

const ReservedInputKey = "input"

ReservedInputKey is the template scope key holding the agent's inbound user message. Sub-agent and step names must not collide.

Functions

func Process

func Process(v any) []error

Process applies tag-driven defaults and validates v in a single traversal.

Both operations share walkLeafFields: for each leaf field it first applies any default= value (via the set callback, which handles map write-back internally), then runs all field-level validators on the (now-defaulted) value. OneOf groups require struct-scope visibility so they run in a second pass via walkStructNodes.

All validation errors are returned (required fields, enum, min, ref, oneof, notreserved, template syntax, typed-as).

Types

type DocProvider

type DocProvider struct {
	Types  map[string]string            // type name → doc
	Fields map[string]map[string]string // type name → Go field name → doc
	Values map[string]map[string]string // type name → enum value → doc
}

DocProvider supplies documentation extracted from Go source comments. Populated by the AST walker in v1/docs.go and passed to Describe.

func ParseTypeDocs

func ParseTypeDocs(srcs ...string) DocProvider

ParseTypeDocs parses Go source files and extracts doc comments for types, struct fields, and typed string const values into a DocProvider. Accepts multiple source strings; results are merged with later sources overwriting earlier ones on collision.

type EnumDoc

type EnumDoc struct {
	Name   string
	Doc    string
	Values []EnumValueDoc
}

EnumDoc describes a named string type with const values.

type EnumValueDoc

type EnumValueDoc struct {
	Label string
	Doc   string
}

EnumValueDoc is a single enum value with its label and doc.

type FieldDoc

type FieldDoc struct {
	YAMLName    string
	Type        string // plain type string (e.g. "Tool", "string[]", "map[string]Convention")
	TypeRef     string // non-empty when the leaf type is a known schema type (e.g. "Convention")
	Required    string // "yes", "no", or "oneof"
	Default     string // "—" or the default value
	Description string
	Min         string // "" or the minimum value as a string
	NotReserved bool
	Refs        []string
	OneOfGroups []OneOfGroup // mutual-exclusivity groups this field belongs to
}

FieldDoc describes a single struct field.

type OneOfGroup

type OneOfGroup struct {
	Group    string   // group name (internal identifier from the tag)
	Optional bool     // true = at-most-one (oneof?=); false = exactly-one (oneof=)
	Peers    []string // yaml names of the other fields in this group
}

OneOfGroup describes a mutual-exclusivity group membership for a field.

type SchemaDoc

type SchemaDoc struct {
	Version string
	Structs []StructDoc
	Enums   []EnumDoc
	Types   []TypeDoc // named non-struct, non-enum types (e.g. TemplateString)
}

SchemaDoc holds the fully described schema for a config version.

func Describe

func Describe(v any, version string, docs DocProvider) SchemaDoc

Describe walks the type tree rooted at v (typically a zero-value config struct like v1.Config{}) and produces a SchemaDoc using reflection and struct tags. Documentation strings come from docs (populated from Go source comments via go/ast).

func FilterTypes

func FilterTypes(doc SchemaDoc, names map[string]bool) SchemaDoc

FilterTypes returns a new SchemaDoc containing only the structs and enums whose names appear in the names set. Used by setup to extract the types relevant to a specific config section.

func (SchemaDoc) KnownTypes

func (d SchemaDoc) KnownTypes() map[string]bool

KnownTypes builds the set of type names present in a SchemaDoc. Callers can use this for cross-linking when rendering.

type StructDoc

type StructDoc struct {
	Name   string
	Doc    string
	Fields []FieldDoc
}

StructDoc describes a config struct type.

type TypeDoc

type TypeDoc struct {
	Name string
	Doc  string
}

TypeDoc describes a named non-struct type (e.g. a named string).