Documentation
¶
Overview ¶
Package outschema implements the output contract of `suga run --output-schema` and sugasdk.Prompt.OutputSchema (design docs/design/2026-10-22-output-schema-design.md): compile a caller's JSON Schema in a sandbox, extract JSON from a model answer, check it, and render what a report, a trace event and a correction message need.
The package is pure: no store, no runner, no I/O beyond what a caller hands in. A schema is treated as data - it never loads external resources and nothing in it is executed.
Index ¶
Constants ¶
const ( // KindSize: the schema is bigger than MaxSchemaBytes. KindSize = "size" // KindTopLevel: the schema is neither a JSON object nor a boolean. KindTopLevel = "toplevel" // KindSyntax: the schema is not JSON at all. KindSyntax = "syntax" // KindExternalRef: the schema refers to a resource that is not inline. KindExternalRef = "external_ref" // KindUnknownDraft: $schema names a draft this compiler does not know. KindUnknownDraft = "unknown_draft" // KindInvalidSchema: the schema does not satisfy its meta schema. KindInvalidSchema = "invalid_schema" )
Compile error kinds; the entry layer reports them as usage errors (exit 2).
const ( // SourceWhole: the whole answer is the JSON value. SourceWhole = "whole" // SourceFenced: a fenced code block (“`json or unlabelled) holds it. SourceFenced = "fenced" // SourceSubstring: a balanced {...}/[...] inside the prose holds it. SourceSubstring = "substring" // SourceNone: the answer holds no JSON value (reported as no_json). SourceNone = "no_json" )
Sources of a checked JSON value; they are reported to the caller and in the trace event, so the caller never has to guess (design 3.3).
const ( // MaxErrors caps the errors a report, a trace event and a correction message // carry: a small schema can produce hundreds of them. MaxErrors = 8 // MaxErrorChars caps one error message: a meta-schema message can be long. MaxErrorChars = 200 )
const ( // MaxSchemaBytes caps one contract (design 6.2): the schema travels with // every request of the call, so a bigger one would cost more context than it // buys; splitting it into inline $defs is the caller's remedy. MaxSchemaBytes = 32 << 10 )
Variables ¶
This section is empty.
Functions ¶
func CorrectionText ¶
CorrectionText is the injected turn that hands a failing check back to the model: the errors only - the answer and the schema are already in its context - plus the one way to answer (design 4.2).
func PromptBlock ¶
PromptBlock is the ephemeral context block of one request: the contract, with its boundary spelled out. It is never stored in the session (design 4.2).
Types ¶
type CompileError ¶
type CompileError struct {
Kind string
Message string
// Params are the values of the placeholders of a translated line of Kind (url,
// draft, detail, limit, actual): the display layer renders Kind + Params in the
// UI language, while Message stays the same text for sugasdk and its callers.
Params map[string]any
}
CompileError is a schema the caller has to fix before a turn may start. Message is one line: the entry layer prints it as is when it has no translated line for Kind.
func (*CompileError) Error ¶
func (e *CompileError) Error() string
type Contract ¶
type Contract struct {
// contains filtered or unexported fields
}
Contract is one compiled caller schema.
func Compile ¶
Compile validates and compiles a caller schema. The returned error is always a *CompileError; every failure is a usage error of the caller, not a bug.
type Error ¶
type Error struct {
// Path is the JSON path of the offending value, e.g. $, $.items[0].id. A
// numeric object key renders as an index (known, harmless: the path only
// feeds text and the trace, never the decision).
Path string
// Message is the localized reason, one line, at most MaxErrorChars runes.
Message string
}
Error is one validation problem of a checked answer.
type Result ¶
type Result struct {
// Passed: a candidate satisfied the schema.
Passed bool
// Source says where the checked value came from (whole/fenced/substring);
// no_json means the answer held no JSON value at all.
Source string
// Value is the passing candidate's raw JSON, compacted.
Value json.RawMessage
// Errors are the problems of the last candidate tried (empty on success).
Errors []Error
}
Result is the outcome of checking one answer against a contract.