schema

Documentation

Overview

Package schema loads JSON Schema files and validates JSON instances (design doc §9.1–§9.2, §13.3). Use ResolveSchemaPath with the project root, then Validate(absPath, jsonBytes). LoadDocument compiles the same files onto the project graph for static wiring checks (issue #193).

Index

• func Compatible(producer, consumer TypeSet) bool
• func ResolveSchemaPath(projectRoot, schemaRef string) (string, error)
• func Validate(schemaPath string, instance []byte) error
• type CompileError
  • func (e *CompileError) Error() string
  • func (e *CompileError) Unwrap() error
• type Document
  • func LoadDocument(schemaPath string) (*Document, error)
  • func (d *Document) Lookup(path []string) LookupResult
• type FileError
  • func (e *FileError) Error() string
  • func (e *FileError) Unwrap() error
• type InstanceError
  • func (e *InstanceError) Error() string
  • func (e *InstanceError) Unwrap() error
• type JSONType
• type LookupResult
• type Registry
  • func NewRegistry() *Registry
  • func (r *Registry) Validate(schemaPath string, instance []byte) error
• type TypeSet
  • func (s TypeSet) Has(t JSONType) bool
  • func (s TypeSet) String() string
• type ValidationError
  • func (e *ValidationError) Error() string
  • func (e *ValidationError) Unwrap() error

Functions

func Compatible

func Compatible(producer, consumer TypeSet) bool

Compatible reports whether a producing type set can flow into a consuming type set. Untyped (empty) sides are compatible (gradual typing). integer may flow into number.

func ResolveSchemaPath

func ResolveSchemaPath(projectRoot, schemaRef string) (string, error)

ResolveSchemaPath joins schemaRef to projectRoot for Agent/Workflow schema fields (paths like ./schemas/input.json in design doc §7.2, §7.4).

Rule: all paths are resolved under projectRoot. Absolute schemaRef is allowed only if it still lies under projectRoot after filepath.Clean (same containment check as relative joins). This matches a single-root workspace layout.

func Validate

func Validate(schemaPath string, instance []byte) error

Validate loads the schema at schemaPath, parses instance as JSON, and validates. schemaPath is cleaned and passed through filepath.Abs. Results are easier to reason about if callers pass the path returned by ResolveSchemaPath.

Compiled schemas are cached in a package-level registry (idempotent for the same path).

Types

type CompileError

type CompileError struct {
	Path string
	Err  error
}

CompileError wraps schema compilation failures (invalid schema document).

func (*CompileError) Error

func (e *CompileError) Error() string

func (*CompileError) Unwrap

func (e *CompileError) Unwrap() error

type Document

type Document struct {
	Path string
	Raw  map[string]any
}

Document is a loaded JSON Schema held on the project graph after validate (issue #193). Path is the absolute file used to compile; Raw is the object form used for static type lookup.

func LoadDocument

func LoadDocument(schemaPath string) (*Document, error)

LoadDocument reads, compiles, and returns a JSON Schema document. schemaPath is cleaned and passed through filepath.Abs (same as Validate).

func (*Document) Lookup

func (d *Document) Lookup(path []string) LookupResult

Lookup returns the schema constraint at a dotted property path from the document root. An empty path is the root schema (typically the whole output/input object).

type FileError

type FileError struct {
	Path string
	Op   string
	Err  error
}

FileError is returned when the schema file cannot be read or does not exist.

func (*FileError) Error

func (e *FileError) Error() string

func (*FileError) Unwrap

func (e *FileError) Unwrap() error

type InstanceError

type InstanceError struct {
	Path string
	Err  error
}

InstanceError means instance bytes are not valid JSON.

func (*InstanceError) Error

func (e *InstanceError) Error() string

func (*InstanceError) Unwrap

func (e *InstanceError) Unwrap() error

type JSONType

type JSONType string

JSONType is a JSON Schema instance type (draft 2020-12).

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

type LookupResult

type LookupResult struct {
	Types TypeSet
	// Known is true when the schema names at least one instance type at this path.
	Known bool
	// Missing is true when the path is forbidden (undeclared property with
	// additionalProperties: false, or a descent through a non-object/array).
	Missing bool
}

LookupResult is the static type of a JSON Schema path.

type Registry

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

Registry caches compiled schemas by absolute path for repeated validation.

func NewRegistry

func NewRegistry() *Registry

NewRegistry constructs an empty registry with a dedicated compiler.

func (*Registry) Validate

func (r *Registry) Validate(schemaPath string, instance []byte) error

Validate compiles the schema at schemaPath (if needed), parses instance as JSON, and validates. schemaPath may be relative; it is resolved with filepath.Abs before open/compile.

type TypeSet

type TypeSet map[JSONType]struct{}

TypeSet is a set of JSON Schema types. Empty means the schema does not constrain type.

func (TypeSet) Has

func (s TypeSet) Has(t JSONType) bool

Has reports whether t is in the set.

func (TypeSet) String

func (s TypeSet) String() string

type ValidationError

type ValidationError struct {
	Path string
	Err  error
}

ValidationError means the instance does not satisfy the schema.

func (*ValidationError) Error

func (e *ValidationError) Error() string

func (*ValidationError) Unwrap

func (e *ValidationError) Unwrap() error