Schema design patterns shown here use the new
/documents/sections and /documents/templates API. See Create a Section for the full endpoint mechanics.Why schema is the headline feature
outputSchema on a section does two things at once:
- Declares the shape of what the LLM is allowed to emit — a string, a number, a structured object with named fields, an array of objects, and so on. The model is steered to fit this shape.
- Drives the rendering of that output via format strings (
fieldFormat,itemFormat) so the rendered Markdown/text matches your downstream consumer — an EHR field, a structured pipeline, a free-text note block.
Node types at a glance
outputSchema is one of five node types, discriminated by type. The table lists each type and the fields you can set; bold fields are required, the rest are optional.
type | Use when | Required | Optional |
|---|---|---|---|
string | Free prose, single labels, fixed phrases | type | description, default, enum, pattern |
number | Measurements, counts, scores | type | description, default, enum, minimum, maximum |
boolean | Yes/no facts (e.g. “fasting?”) | type | description, default |
array | Lists of any node type | type, items | description, itemFormat, minItems, maxItems |
object | Structured blocks with named fields | type | description, fields[], fieldFormat |
items can itself be any node — including another array or object. That’s the lever for everything below.
Field reference — what each option does
Most fields are technically optional, butdescription is strongly recommended on every node — it doubles as a prompt to steer the LLM, not just metadata.
Common to all node types
| Field | Purpose |
|---|---|
type | The discriminator. One of string, number, boolean, array, object. Always required. |
description | Prompt text the model sees when generating this part of the output. Optional but strongly recommended — this is your main lever to clarify what this specific node should contain, in addition to the section’s instructions.contentPrompt. |
String-specific
| Field | Purpose |
|---|---|
default | Fallback string if the model has nothing to emit for this node. |
enum | A closed set of allowed values. The model must pick one of these strings. |
pattern | A regular expression the output should match. The model is steered toward emitting a string that conforms (e.g. ^\d{2,3}/\d{2,3}$ for a blood-pressure value). Not a hard validator — pair with enum/description for stricter control. |
Number-specific
| Field | Purpose |
|---|---|
default | Fallback numeric value when nothing applies. |
enum | Closed set of allowed numeric values. |
minimum / maximum | Plausible range bounds. Acts as a prompt anchor as well as validation. |
Boolean-specific
| Field | Purpose |
|---|---|
default | Fallback true/false when the source material is silent. |
Array-specific
| Field | Purpose |
|---|---|
items (required) | The schema for each element. Can be any node type — string, number, object, even another array. |
itemFormat | Per-item rendering. A custom format string that must contain the {item} placeholder — applied per element. For bullets use "- {item}\n"; for prefixed entries use e.g. "Rp. {item}\n". Note: there is no built-in auto-incrementing index token, so a “numbered” rendering (1., 2., 3., …) cannot be produced from itemFormat alone — model the section as a string and ask the model to emit the numbering in its content, or accept bullets via "- {item}\n". |
minItems / maxItems | Bounds on the number of items the model may emit. |
Object-specific
| Field | Purpose |
|---|---|
fields[] | The fixed set of fields the object contains. Each entry requires key, description, and value (any node type). |
fieldFormat | Single unified format string controlling how the object is rendered. Two modes — pick one per object: (a) Per-field iteration with generic {key} and {value} placeholders (e.g. "{key}: {value}\n" for inline subheadings, "{key}\n{value}\n" for block subheadings, "**{key}**: {value}\n" for bold Markdown). The template is applied to every field. (b) Custom layout with specific field-key placeholders that match defined fields[] (e.g. "{test}: {result} ({status})"). The format string is rendered once with all fields substituted. |
Composing schemas — quick reference
| Pattern | Shape | Use for |
|---|---|---|
string | One line of prose | HPI, Chief Complaint, single-paragraph Assessment |
string + enum | One value from a closed set | Triage acuity, urgency, disposition |
string + enum + keyword rules in description (+ default) | Keyword-driven classification — one value out, nothing else | Encounter disposition (admit / discharge / transfer / …), tobacco status, pregnancy status, severity class — any EHR picker or analytics dimension where the receiver needs a stable categorical value |
number + minimum/maximum | Constrained measure | Vital values, scores, counts |
array of string + itemFormat | Repeating short items | Diagnoses, Medications, Plan items |
array of object containing a nested array with indented itemFormat | Multi-level lists (e.g. numbered parent + indented bullet children) | Plan items with sub-bullets, treatment steps with instructions, action lists with contingencies |
array of object (free title) | Dynamic key/value rows | Objective findings, Diagnostic results, Physical Exam |
array of object (enum’d title) | Constrained-key rows | Review of Systems with standardized domains |
object + fieldFormat per-field iteration ({key} / {value}) | Fixed-subheading block, optionally with per-field style rules | Pre-op screening, OT Activity & Participation, pain assessment, fixed-form SOAP-style blocks |
object + fieldFormat custom layout (literal text + {fieldKey} placeholders) | Sentence-template scaffold | Referral letter, discharge letter, any note with fixed phrasing around variable content |
object + fieldFormat custom layout with escaped {{ }} | Layout with literal braces in output | EHR placeholder scaffolds, mixed-type test rows, structured discharge summaries |
Where schema interacts with the rest of the prompt
The model receives, in priority order:- Section
instructions—contentPrompt,writingStylePrompt,miscPrompt. - Template-level instructions —
instructions.prompton the parent template (when used in a template). - Schema-level guidance — every
description,enum,pattern,default,minimum,maximum,minItems,maxItemsyou supply on theoutputSchema.
instructions.contentPrompt for the overall section content/scope; use schema descriptions for field-specific behavior.
Applying a schema to a Corti Standard section
A common pattern is: keep a Corti Standard section’s full prompt machinery (heading, contentPrompt, writingStylePrompt, miscPrompt) but swap its outputSchema for one of the patterns above — e.g. take the curated corti-hpi prompts and emit a structured object for an EHR pipeline.
Two ways to do this:
- Fork the Standard (persistent).
POST /documents/sectionswithinheritFromId: <standard-section-uuid>and onlygeneration.outputSchemain the body. Everything else is inherited. See Corti Standards — overrideoutputSchema. - Override per call (ephemeral). Submit the new
outputSchemainsidetemplateRef.overrides.sections[].generation.outputSchemaonPOST /documents. See Guided Synthesis — Path 2 and Customization Cookbook — Recipe 2.
outputSchema overrides are wholesale — whatever you submit fully replaces the parent’s schema; partial schemas are not merged. When the change is structural (e.g. string → object/array), consider overriding writingStylePrompt in the same request so the parent’s wording rules don’t conflict with the new shape.
Related
Create a Section
Wrap any of these schemas in a full section create request — name, language, instructions, lifecycle.
Corti Standards
Browse the curated library — many of the patterns above are how Corti standard sections are built.
Worked clinical examples
The patterns below are pulled from real Corti standard sections — adapted so you can copy/paste them into your ownPOST /documents/sections request, lift specific fields, or reference them as a parent via inheritFromId.
Each example shows the full outputSchema (you’d wrap it in the standard name/language/generation.instructions/generation.outputSchema envelope from Create a Section).
Example 1 — Fixed subheadings with explicit 'not discussed' vs 'nil' defaults
Example 1 — Fixed subheadings with explicit 'not discussed' vs 'nil' defaults
Goal: A pre-op screening block that always renders the same fixed subheadings in the same order. When the conversation didn’t touch a topic, render What you get (with
Not discussed. When the patient explicitly denied something, render Nil. Don’t let the model invent in-between phrases like “patient denies anything noteworthy.”Pattern: object with fieldFormat: "{key}\\n{value}\\n" (per-field iteration), fixed fields[], per-field default, and explicit guidance in each field’s description for the negation rule.outputSchema — fixed subheadings + explicit defaults
fieldFormat: "{key}\n{value}\n" — per-field iteration):Example 2a — Dynamic organ-system labels (free)
Example 2a — Dynamic organ-system labels (free)
Goal: Examination findings where the LLM picks the organ-system label dynamically — only the systems actually examined appear in the output, with a clinically appropriate label for each. No predefined enum.Pattern: array of objects with a What you get:
title string field (no enum) and a content string field, joined via fieldFormat: "{title}: {content}". The model creates as many entries as needed.outputSchema — dynamic-key array-of-objects
Example 2b — Constrained organ-system labels (enum)
Example 2b — Constrained organ-system labels (enum)
Goal: Same shape, but every label must come from a fixed clinical abbreviation set you’ve standardized on for an EHR field.Pattern: identical to 2a, but the What you get:
title field’s string node carries an enum of allowed values.outputSchema — enum-constrained dynamic keys
When to use which. Use free titles (2a) when the legal label set is open-ended and clinicians need to choose precise body regions. Use enum (2b) when the downstream consumer (EHR field, analytics pipeline) requires a finite, stable set of labels.
Example 3 — Structured test results with measures and free-text findings
Example 3 — Structured test results with measures and free-text findings
Goal: Lab and imaging results where each entry mixes typed measures (numeric values with ranges and units), a status field drawn from a fixed clinical vocabulary, and a free-text finding narrative.Pattern: array of objects with a What you get:Every row renders cleanly:
result string that the model formats consistently (number + unit, or status placeholder for non-numeric studies), plus a typed status enum and a free-text findings field. Numeric typing is preserved per-test through the description instructions; the rendered line stays clean regardless of test type.outputSchema — mixed-type test results
result is always non-empty, so there’s no double-space gap, and the rendered line works for quantitative labs and imaging studies alike.Example 4 — Prefixes and standard phrasings via `itemFormat`
Example 4 — Prefixes and standard phrasings via `itemFormat`
Goal: A prescription section where every line is prefixed with What you get:The same
Rp., and a separate dictation block where every utterance begins with a standard “Pt reports:” header.Pattern: custom itemFormat on the array. The {item} placeholder is the rendered item; everything else around it is literal text.outputSchema — prescriptions with Rp. prefix
outputSchema — dictation with fixed prefix per item
{key}/{value} levers exist on objects via fieldFormat (e.g. "**{key}**: {value}") for Markdown-bold headings, or "## {key}\n{value}" for full Markdown headings.Example 5 — EHR placeholders that survive verbatim
Example 5 — EHR placeholders that survive verbatim
Goal: A plan section that emits literal placeholder strings — like What you get:The clinician-generated plan text fills
{treatment_shared_motherhood_ivf} — for an EHR system to substitute downstream. The LLM must not generate or paraphrase these; they’re scaffolding for the EHR, not content.Pattern: bake the placeholders directly into fieldFormat as literal text, escaping the curly braces. fieldFormat parses {fieldKey} as a variable substitution; doubled {{ and }} are escapes that render as a single literal { and } in the output. Any clinician-authored content goes into a normal field that is substituted.Format-string brace escaping. In
fieldFormat:- A single
{fieldKey}substitutes the value of that field. - A doubled
{{renders as a literal{in the output;}}renders as a literal}.
{treatment_var} in the output (single braces around a placeholder name), write {{treatment_var}} in the format string — that’s {{ (literal {) + treatment_var (literal text, no substitution because there’s no matching field) + }} (literal }).To emit literal {<value-of-field_1>} (literal braces around a substituted value), write {{{field_1}}} — that’s {{ + {field_1} + }}.To emit double-brace placeholders like {{treatment_var}} literally (Mustache/Handlebars style), each output brace needs its own escape: write {{{{treatment_var}}}} in the format string.outputSchema — EHR placeholders via escaped literal braces
{plan_notes}; the EHR placeholders pass through as literal text because their braces are escaped. No extra fields and no enum tricks needed.Example 6 — Different writing styles per subheader via field `description`
Example 6 — Different writing styles per subheader via field `description`
Goal: Inside one section, each subheader (field) follows a different writing style — telegraphic for one, flowing prose for another, comma-separated short phrases for a third — without splitting into multiple sections.Pattern: the section’s What you get:
instructions.writingStylePrompt sets the global default; each field’s description carries the local style rule for that subheader. The model reads both and applies the field-level rule where the two disagree.outputSchema — per-field writing styles
When per-field
description is enough vs. when to split into multiple sections. Use this pattern when the styles are contrasts within a coherent section that always renders as one block (e.g. a pain assessment). When the subheaders are large enough to be reused independently across templates — or have meaningfully different contentPrompt rules — it’s cleaner to promote each into its own section in the template instead.Example 7 — OT Activity & Participation (ICF-style fixed subcategories)
Example 7 — OT Activity & Participation (ICF-style fixed subcategories)
Goal: An occupational therapy block with fixed ICF-aligned subcategories — Self-care, Mobility, Communication, Domestic life, Interpersonal interactions — each producing free text. Subcategories always render in the same order; subcategories not covered in the source still appear with an explicit “Not assessed” placeholder so downstream consumers can rely on the structure.Pattern: What you get:The “Domestic life” subheader still renders even though the source material didn’t cover it — because the field’s
object + fieldFormat: "{key}\\n{value}\\n" (per-field iteration) + fixed fields[] with a per-field default of "Not assessed". This is the OT-clinic equivalent of the pre-op screening pattern in Example 1.outputSchema — OT Activity & Participation block
default is "Not assessed". Downstream consumers see a stable structure across encounters.Example 8 — Standard phrases combined with LLM-generated content
Example 8 — Standard phrases combined with LLM-generated content
Goal: Output a clinical letter (or any structured note) where standard sentence templates wrap model-generated content. The connective tissue — salutations, framing sentences, closing — is verbatim; only the clinical content varies between encounters.Pattern: What you get:
object + fieldFormat with full sentences containing {field} placeholders. The fixed phrases are just literal text in the format string; each {field} is substituted with model-generated content from fields[].outputSchema — standard phrasing scaffold
Example 9 — Bullet points nested inside a numbered list
Example 9 — Bullet points nested inside a numbered list
Goal: A Plan section where each plan item carries a top-level marker (bullet by default — see the numbering caveat below) and 0 or more indented sub-bullets with dosing, follow-up timing, contingencies or anything else worth itemising under that step.Pattern: outer What you get:How it works:
array with a custom itemFormat containing the {item} placeholder. Each item is an object with a summary string field plus a nested details array whose own itemFormat includes a leading indent + bullet marker (e.g. " - {item}\n"). Compose summary + details via fieldFormat. The outer array applies its itemFormat once per top-level entry; the inner array’s itemFormat controls the indented bullet rendering.outputSchema — plan with nested bullet details
- The outer
array.itemFormat: "* {item}\n"puts an asterisk (or any literal marker you choose —-,•,1.) in front of each top-level item. - The inner
array.itemFormat: " - {item}\n"is the key lever: the two leading spaces indent each bullet under its parent, and-is the bullet marker. Adjust spacing for deeper nesting (e.g." * {item}\n"for a four-space-indented sub-sub-list). - The object’s
fieldFormat: "{summary}\n{details}"concatenates the summary line with the sub-bullets directly underneath, preserving the visual nesting. - If a plan item has no sub-bullets, the
detailsarray renders as empty and the entry collapses to just the summary line (item 3 above).
Example 10 — Diagnoses with indented detail bullets
Example 10 — Diagnoses with indented detail bullets
Goal: A Diagnoses (problem list) section where each diagnosis is rendered with a top-level marker and an optional ICD/SNOMED code, and each diagnosis carries indented sub-bullets describing the clinical findings, reasoning, status, and management pertaining to it. Same structural pattern as Example 9; the field descriptions and the kind of content the LLM is steered toward are diagnosis-focused.Pattern: outer What you get:How it differs from Example 9:
array with a custom itemFormat (e.g. "* {item}\n"), inner items are objects with a diagnosis summary string and a nested details array. The details.itemFormat uses the leading-indent + bullet marker trick to render each sub-point indented under its diagnosis.outputSchema — diagnoses with indented details
- Structurally identical schema shape (outer array + object item with
summary+ nesteddetailsarray). The pattern is reusable. - The field descriptions are diagnosis-specific:
diagnosisprompts for label + optional code;detailsprompts for findings, reasoning, status, management. - Same graceful-collapse behavior — if a diagnosis only has a name (and the source material doesn’t support sub-bullets), the entry renders as just the diagnosis line (item 4 above).
Need auto-numbered diagnoses (1., 2., 3., …)? Same caveat as Example 9:
itemFormat has no built-in counter, so use string + a contentPrompt that instructs the model to emit numbered lines with two-space-indented sub-bullets. Trade-off: you lose the typed array-of-objects shape and any structuredDocument benefits.Example 11 — Keyword-driven classification (single enum value out)
Example 11 — Keyword-driven classification (single enum value out)
Goal: The section emits exactly one value from a closed list based on cues in the source material. No free text, no explanation — just the categorical value. Useful for EHR picker fields, analytics dashboards, routing logic, or any downstream consumer that needs a stable enum value rather than narrative content.Pattern: What you get (for a transcript where the clinician says “…let’s send her home with the antibiotic course and a follow-up in two weeks”):Just the bare enum value, nothing else. Downstream consumers can map it to a UI dropdown selection, an EHR field, a routing decision, or a metric label without any parsing.How it works:
string + enum (closed value set) + a rich description that teaches the model the keyword-to-value mapping. Add default for the “no signal in the source” case so the field always renders something deterministic.outputSchema — encounter disposition classifier
enumis the hard constraint. The model can only emit one of the listed values —"admit","discharge","transfer","consult-pending","left-ama", or"undetermined". Free text never leaks through.descriptionis where the classification logic lives. Spell out which input keywords or phrases map to each enum value. The model reads this alongside the section’sinstructions.contentPromptwhen picking the output.defaultcovers the empty-state case — if the source material has nothing to support a disposition decision, the field renders"undetermined"deterministically. (Without a default, the model might still pick a value or return an empty string. With it, your downstream consumer always sees a known value.)
Other clinical use cases that fit this pattern: triage acuity (ESI levels 1–5), pain severity (mild / moderate / severe), tobacco status (never / former / current), pregnancy status, fall-risk class, cancer stage, AMS level, NYHA functional class, audit/consent yes-no-unknown checks. Each one is a
string + enum + descriptive keyword rules. For numeric scoring (Apgar, GCS, pain 0–10), use number + minimum/maximum instead — see Example 3 patterns.