Expand description
Language-agnostic authoring: YAML/JSON question-spec documents → IR.
The document format is the jev-1 questions map with an optional shared state, in our own prose (clean-room, S6a §3):
state: "The refund arrived two weeks late and the box was crushed."
questions:
is_refund: # caller-chosen id — never sent to the model
type: noul
instructions: "The customer is asking for a refund."
criteria: # optional; keys are literally "true" / "false"
"true": "Explicitly requests money back"
"false": ~ # null = undescribed
tone:
type: choice
instructions: "Classify the tone of the review."
criteria: # option name -> rubric (null = undescribed option)
positive: "The review expresses approval."
negative: "The review expresses disapproval."
neutral: ~
severity:
type: score
criteria: # ordered levels, 0-indexed; null = undescribed level
- "Cosmetic issue only"
- "Usable but damaged"
- "Completely unusable"Validation produces structured, positioned SpecErrors — the first violation is
returned with a document path (and line/column for syntax errors). The enforced rules:
- top level: a mapping with optional
stateand requiredquestions; unknown keys rejected (D-parity with the upstream SDKs’extra=forbid). questions: ≥ 1 entry; ids non-empty and unique.- every question:
typerequired;instructionsoptional and nullable (D4); unknown fields rejected. noul:criteriaoptional; only keys"true"/"false"allowed.choice:criteriarequired; 2–255 options (D2); option names non-empty, unique.score:criteriarequired; ≥ 2 levels (D1); null levels allowed (D3).span/derivedare recognized and rejected as reserved v2 types.
There is intentionally no limit on questions per document (S6a A12 footnote: the
upstream profile publishes only token budgets). The serialized-size contract is the 2k
token budget documented on crate::serialize.
Constants§
- MAX_
CHOICE_ OPTIONS - The profile-pinned maximum number of options on a choice question (S6a A4: the 255 limit is prose-documented upstream; this profile pins it as a hard validation).
Functions§
- parse_
json - Parse a JSON question-spec document into the IR.
- parse_
yaml - Parse a YAML question-spec document into the IR.