Documentation
¶
Overview ¶
Package jschema is a fail-closed JSON Schema compile/validate wrapper for structured subagent outputs (plan tools/02).
Policy:
- no remote $ref resolution (only the document under compile)
- marshaled schema size and nesting depth caps
- validation errors are redacted and size-bounded before model-facing use
Index ¶
- Constants
- Variables
- func EnvelopeAppendixBody(contract string) string
- func ExtractEnvelope(s string) string
- func ExtractOutputCandidate(reply string) string
- func FormatCorrective(validateErr error, redact func(string) string) string
- func FormatCorrectiveWithSchema(validateErr error, schema map[string]any, redact func(string) string) string
- func ModelSchemaContract(schema map[string]any) string
- func PromptAppendix(schema map[string]any) string
- func StripOneCodeFence(s string) string
- type Compiled
Constants ¶
const ( // MaxSchemaBytes is the maximum marshaled size of a schema document. MaxSchemaBytes = 16 << 10 // MaxSchemaDepth is the maximum nesting depth of objects/arrays in a schema. MaxSchemaDepth = 32 // MaxValidationErrors is how many validation error lines a corrective // message may carry. MaxValidationErrors = 5 // MaxCorrectiveBytes caps the corrective user message body. MaxCorrectiveBytes = 1024 )
Admission caps applied at compile time.
const OutputEnvelopeTag = "mivia_output"
OutputEnvelopeTag is the tag name a subagent reply is asked to wrap its JSON in when a schema is in force. Asking for a fixed text envelope, rather than relying on a provider-specific structured-output or forced-tool-call feature, keeps extraction identical across every model provider (Anthropic, OpenAI, DeepSeek, local models, ...), since none of those APIs guarantee a compatible mechanism for every provider this harness must support.
Variables ¶
var ErrAdmission = errors.New("schema admission rejected")
ErrAdmission is returned when a schema is refused before any run starts.
var ErrValidation = errors.New("schema validation failed")
ErrValidation is returned when an instance fails validation.
Functions ¶
func EnvelopeAppendixBody ¶
EnvelopeAppendixBody is the shared instruction text asking the model to wrap its schema-conformant JSON reply in <mivia_output> tags. Both prompt- appendix renderers - PromptAppendix in jschema.go (user turn) and schemaSystemAppendix in internal/cli (system prompt) - delegate to this single function so the tag name and wrapping instruction can never drift out of sync between the two surfaces, which independently hand-built near-identical strings before this function existed.
func ExtractEnvelope ¶
ExtractEnvelope locates the content between a line-bound opening <mivia_output> tag and the LAST line-bound closing </mivia_output> tag that follows it, and returns it trimmed.
"Line-bound" means the tag occupies its own line, allowing only horizontal whitespace before or after it on that line. This rejects a tag merely mentioned in prose (e.g. "I'll wrap this in <mivia_output> tags:") - a model narrating compliance before the real envelope is expected behavior, and the prompt instruction itself necessarily contains the tag text, so a naive first-occurrence match would extract the narration instead of the real payload.
The LAST line-bound closing tag is used, not the first, so a closing-tag-shaped line inside the JSON payload's own string content cannot truncate the real payload early.
When no unambiguous line-bound pair is found, s is returned unchanged - the same fail-open philosophy as StripOneCodeFence, so a reply that ignores the envelope instruction and emits bare JSON still validates.
func ExtractOutputCandidate ¶
ExtractOutputCandidate is the single entry point for turning a raw model reply into a JSON-parse candidate: it isolates the <mivia_output> envelope (if present, else the reply is left unchanged) and then strips one wrapping code fence, so a reply that fences its JSON inside the envelope - or skips the envelope but still fences the JSON - both resolve to bare JSON text.
func FormatCorrective ¶
FormatCorrective builds a bounded, plain-text corrective user message. callerRedact, when non-nil, is applied to the full message before return.
func FormatCorrectiveWithSchema ¶
func FormatCorrectiveWithSchema(validateErr error, schema map[string]any, redact func(string) string) string
FormatCorrectiveWithSchema builds the corrective user message with the required schema restated inline. The retry turn replaces the task prompt, which carried the schema appendix, so without a restated schema the model repairs its output shape blind and the retry budget is spent on the same invalid shape.
func ModelSchemaContract ¶
ModelSchemaContract renders the model-facing contract for a schema map. It strips the schema meta-keywords, adds the never-echo instruction, and appends a compact filled example for small object schemas. The compiled validator still uses the raw document (Compiled.Raw()); this is only the text the model sees. It returns "" when the schema cannot be rendered.
func PromptAppendix ¶
PromptAppendix is the deterministic host instruction appended when a schema is in force.
func StripOneCodeFence ¶
StripOneCodeFence removes at most one well-formed markdown code fence that wraps the entire body. Nested or partial fences are left untouched. The opening and closing fences must carry the same number of backticks (>= 3), so 4-backtick fences - the correct way to fence JSON containing backticks - are handled as well as the conventional triple-backtick fence.
Types ¶
type Compiled ¶
type Compiled struct {
// contains filtered or unexported fields
}
Compiled is a schema ready for Validate.
func Compile ¶
Compile admits and compiles a JSON Schema object. Remote $ref is disabled; size and depth caps fail closed.
Source Files