Template syntax
TypePrompt projects are made up of .tp files matching the include pattern in typeprompt.yaml (usually: prompts/**/*.tp). Every file has one of the following root elements:
| Element | Purpose |
|---|---|
<meta> | Declare the type of per-template metadata |
<template> | Define a prompt template |
<tool> | Define a callable tool |
<namespace> | Group templates and tools; define shared types |
<playground> | Define playground samples for a template |
For the type system (schemas, SDL), see schema language. For file naming and project layout, see project structure.
The <meta> element (top level)
<meta> lets you attach structured metadata to each template — for example, the model to use, the sampling temperature, or any other configuration your LLM client needs. You define the shape of that metadata once at the top level, then supply values per template.
<meta> can therefore appear in two places: once at the top level of a file to declare the metadata type, and once inside each <template> to supply the metadata values.
At the top level of a file, the text content of <meta> must define a Meta type using TypePrompt's SDL.
<!-- meta.tp -->
<meta>
interface Meta {
/** Sampling temperature (0–2). */
temperature: number;
model?: "gpt4o" | "gpt4oMini" | "o3";
}
</meta>The <template> element
A <template> defines a prompt that can be built and sent to an LLM.
Attributes:
| Attribute | Requirement | Format | Description |
|---|---|---|---|
name | Required | PascalCase | Unique name within the namespace |
namespace | Optional | PascalCase | Namespace this template belongs to; defaults to Main |
Child elements (in any order):
| Element | Requirement | Description |
|---|---|---|
<meta> | If top-level <meta> exists | Per-template metadata values |
<schema> | Required | Input and Output types |
<tools> | Optional | Tools the model may call |
<system> | Required | System instructions |
<user> | Required | User message |
<examples> | Optional | Few-shot examples |
<snippet> | Optional | Reusable text fragments |
<variant> | Optional | Prompt variants |
Template-level <meta> — supplying values
When a top-level <meta> is declared, every <template> must include a <meta> child whose text content is a YAML value of type Meta.
<!-- Summarize.tp -->
<template name="Summarize">
<meta>
temperature: 0.3
model: gpt4o
</meta>
...
</template>The <schema> element
Defines the Input and Output types for the template using TypePrompt's SDL. Both types are required.
The Output type must be either string for unstructured text responses, or an interface type for structured JSON responses.
<!-- ClassifyEmail.tp -->
<template name="ClassifyEmail">
<schema>
interface Input {
subject: string;
body: string;
recipients: Recipient[];
}
interface Recipient {
emailAddress: string;
alias: string;
}
interface Output {
category: "billing" | "support" | "feedback" | "other";
summary: string;
}
</schema>
...
</template>The <tools> element
Registers tools that the model may call during this prompt. Contains one or more <tool> child elements referencing defined tools.
<!-- ResearchAssistant.tp -->
<template name="ResearchAssistant">
<tools>
<tool name="webSearch" />
<tool name="readDocument" />
</tools>
...
</template>Each name attribute must match a <tool> element defined at the top level (in the same namespace).
The <system> and <user> elements
These elements contain the system and user messages. Each may contain a mix of plain text and the inline elements described below: <insert>, <enclosed>, and <c>.
It is very common for the <user> message to simply render the input value in JSON, YAML, or TOON format:
<user>
<insert val="input" format="yaml" />
</user>Indentation
TypePrompt automatically strips leading indentation so you can format your XML neatly without it affecting the resolved text.
If the element's content begins with a line containing only whitespace, TypePrompt treats the indent of the first non-empty line as the base indent and strips it from every subsequent line. Lines that are non-empty but don't start with the base indent are a compile error.
<system>
You are a helpful assistant.
Today is <insert val="input.dateToday" />.
Answer the user's question clearly and concisely.
</system>Resolved text:
You are a helpful assistant.
Today is 2025-03-14.
Answer the user's question clearly and concisely.<insert>
Inserts a formatted value, a snippet, or a schema into the message at this position.
To insert a value, set the val attribute to an expression rooted at input:
<insert val="input.userQuery" />
<insert val="input.documents" format="json" />The format attribute controls serialization:
| Value | Description |
|---|---|
text | (default) Renders the value as a plain string. The value must be of type string or integer. |
json | Pretty-printed JSON (2-space indent). |
yaml | YAML serialization. |
toon | TOON — a structured, human-readable format optimized for LLM consumption. |
csv | Comma-separated values. The value must be an array of objects whose fields are strings or numbers; the field names become the header row. |
tsv | Tab-separated values. Same requirements as csv. |
To insert a snippet, use the snippet attribute:
<insert snippet="systemContext" />To insert a schema, use the schema attribute with format="typescript":
<system>
...
Your response must be a valid JSON object that satisfies this schema:
<insert schema="Output" format="typescript" />
</system>This injects the TypeScript type definition for Output (including any dependent types and documentation comments) directly into the prompt. This is mainly useful when targeting models that do not support strict JSON schemas via API parameters.
Indentation propagation: if the <insert> tag appears on an indented line, that indentation is prepended to every line of the resolved value, snippet, or schema. This lets you embed multi-line content inside a block element cleanly:
<user>
<enclosed tag="Document">
<insert val="input.documentContent" />
</enclosed>
</user>If documentContent is a three-line string, the resolved text is:
<Document>
Line 1
Line 2
Line 3
</Document><enclosed>
Wraps its content in an XML-like tag in the resolved text. This is more readable than escaping < and > manually.
<user>
<enclosed tag="Context">
<insert val="input.background" />
</enclosed>
<enclosed tag="Question">
<insert val="input.question" />
</enclosed>
</user>Resolved text:
<Context>
...background...
</Context>
<Question>
...question...
</Question>The <description> element inside <tool> may also contain <enclosed> and <c>.
<c>
<c> (short for check) wraps an identifier or JSON value and verifies at compile time that it matches something in the template's schema. This keeps your instructions in sync with your types — if you rename a field or change a literal value, TypePrompt will report an error wherever <c> references the old name.
Wrapping an identifier:
<template>
<schema>
interface Input {
documentText: string;
targetLanguage: string;
}
interface Output {
translatedText: string;
detectedSourceLanguage: string;
}
</schema>
<system>
Translate the <c>documentText</c> into the <c>targetLanguage</c>.
Return the result as <c>translatedText</c> and set <c>detectedSourceLanguage</c>
to the language you detected in the input.
</system>
...
<template>The valid identifier names are: all field names and string literal values from the template's schema, the names of registered tools, and all field names and string literal values from each registered tool's schema.
For readability, you may quote the identifier inside <c>: <c>"documentText"</c> is equivalent to "<c>documentText</c>".
Wrapping a JSON value:
<c> also validates inline JSON examples — useful when your instructions include sample inputs or outputs:
<system>
Translate the given document.
Example input: <c>{"documentText": "Bonjour", "targetLanguage": "en"}</c>
Example output: <c>{"translatedText": "Hello", "detectedSourceLanguage": "fr"}</c>
</system>The compiler checks that the JSON is well-formed and conforms to at least one named type in the schema.
To keep inline examples concise, you may use an ellipsis (...) as a placeholder:
<c>{"documentText": ..., ...}</c><examples>
Defines few-shot examples that are included in every rendered prompt. The text content is a YAML list with the following structure:
- input: <Input value>
output: <Output value>
steps: # optional; include when the example involves tool calls
- toolCalls:
- callId: <string>
tool: <tool name>
input: <tool Input value>
output: <tool Output value>For a template that classifies emails:
<examples>
- input:
subject: "Invoice #4821 overdue"
body: "Please settle your outstanding balance."
output:
category: billing
urgency: high
summary: Overdue invoice reminder.
- input:
subject: "Love the new dashboard!"
body: "The new analytics view is exactly what I needed."
output:
category: feedback
urgency: low
summary: Positive feedback about the dashboard.
</examples>For a template that uses tools:
<examples>
- input:
question: "What is the capital of France?"
steps:
- toolCalls:
- callId: c1
tool: webSearch
input:
query: "capital of France"
output:
results: ["Paris is the capital of France."]
output:
answer: Paris
</examples>There may be at most one <examples> element per template or variant.
<snippet>
A named, reusable fragment of text that can be inserted into <system>, <user>, or another <snippet> using <insert snippet="..." />.
<template name="QuestionAnswerer">
<system>
<insert snippet="todayDate" />
Answer the following question.
</system>
<snippet name="todayDate">
Today's date is <insert val="input.dateToday" />.
</snippet>
...
</template>Snippet names must be camelCase. The same indentation-stripping rules that apply to <system> and <user> apply here.
Conditional snippet (if)
A snippet can conditionally render one of two bodies depending on an expression:
<snippet name="locationContext" if="input.userLocation" is="notNull">
<then>
The user is located in <insert val="it" />.
</then>
<else></else>
</snippet>Inside the <then> and <else> bodies, it is an alias for the expression passed to if — in this case input.userLocation. This avoids repeating the expression and makes snippets easier to read.
Attributes:
| Attribute | Description |
|---|---|
if | Expression to evaluate (e.g. input.userLocation) |
is | Condition type: notNull (value is not null/undefined), notEmpty (string or array is non-empty), true (value is truthy). Defaults to true. |
When the condition holds, the <then> body is rendered; otherwise the <else> body is rendered.
Switch snippet (switch)
A snippet can branch on a string-union expression:
<snippet name="formalityInstruction" switch="input.tone">
<on case="formal">Use formal, professional language.</on>
<on case="casual">Keep the tone friendly and conversational.</on>
<on case="technical">Use precise technical terminology.</on>
</snippet>The switch attribute must resolve to a string-union type, and there must be exactly one <on case="..."> for each member of that union.
<variant>
Variants let you define multiple versions of a prompt that share the same Input/Output types but differ in instructions or examples — for example, to A/B test different system prompts or to handle a style field in the input.
Requirements:
- The
Inputtype must include avariantfield of type"a" | "b" | .... - There must be exactly one
<variant case="...">for each member of that union. - Each
<variant>may contain<meta>,<system>,<user>, and<examples>. - Elements defined directly under
<template>act as defaults and are inherited by variants that omit them. An element defined under<template>cannot be redefined under<variant>.
<!-- WriteEmail.tp -->
<template name="WriteEmail">
<schema>
interface Input {
recipient: string;
topic: string;
variant: "formal" | "casual";
}
interface Output {
subject: string;
body: string;
}
</schema>
<!-- Shared across both variants -->
<user>
Recipient: <insert val="input.recipient" />
Topic: <insert val="input.topic" />
</user>
<variant case="formal">
<system>
Write a professional business email. Use a formal salutation and sign off with
"Best regards".
</system>
<examples>
- input:
recipient: Dr. Lee
topic: project update
# Do not specify 'variant': inferred from the enclosing variant
output:
subject: Project Status Update
body: "Dear Dr. Lee, ..."
</examples>
</variant>
<variant case="casual">
<system>
Write a friendly, informal email. Keep it short and conversational.
</system>
</variant>
</template>The <tool> element
Defines a tool that the model can call during prompt execution. Tools have a description (shown to the model), and typed input/output schemas.
Attributes:
| Attribute | Requirement | Format | Description |
|---|---|---|---|
name | Required | camelCase | Unique name within the namespace |
namespace | Optional | PascalCase | Namespace this tool belongs to; defaults to Main |
Child elements:
| Element | Requirement | Description |
|---|---|---|
<description> | Required | Human/model-readable description of what the tool does |
<schema> | Required | Input and Output types; Input must be an interface |
<!-- getWeather.tp -->
<tool name="getWeather">
<description>
Returns the current weather at a given location. Use this when the user's
request depends on real-time weather conditions.
</description>
<schema>
interface Input {
city: string;
countryCode: string;
}
interface Output {
temperatureCelsius: number;
condition: "sunny" | "cloudy" | "rainy" | "snowy";
humidity: number;
}
</schema>
</tool>The <description> element may contain <c> and <enclosed> in addition to plain text.
The <namespace> element
Namespaces serve two purposes: organizing large projects and defining types that are shared across multiple templates and tools within the namespace.
<!-- Geo/shared.tp -->
<namespace name="Geo">
interface Address {
street: string;
city: string;
country: string;
}
</namespace><!-- Geo/FormatAddress.tp -->
<template name="FormatAddress" namespace="Geo">
<schema>
interface Input {
address: shared.Address;
locale: string;
}
type Output = string;
</schema>
...
</template><!-- Geo/geocode.tp -->
<tool name="geocode" namespace="Geo">
...
</tool>Types declared inside <namespace> can be referenced from template and tool schemas using the shared.TypeName prefix (see Shared Types).
Attributes:
| Attribute | Requirement | Format | Description |
|---|---|---|---|
name | Required | PascalCase | Unique identifier for this namespace |
If you don't declare any namespaces, all templates and tools belong to the implicit Main namespace. You can still define shared types for that default namespace by declaring <namespace name="Main"> — any types defined there will be available via shared.TypeName in all Main templates and tools.
The <playground> element
<playground> defines playground samples for a prompt template. Playgrounds live in their own .tp file alongside the template they target. See Playground inference for how to run them.
Inside <playground>, model configuration is defined in a <model> element, and test samples are defined as a YAML array nested inside a <samples> element. Each sample provides an input, optional history of previous completed turns, and optional intermediate steps (tool calls) taken during the current turn.
Attributes:
| Attribute | Requirement | Format | Description |
|---|---|---|---|
for | Required | PascalCase | Name of the template this playground targets |
namespace | Optional | PascalCase | Namespace of the target template; defaults to Main |
Model configuration
The <model> element contains YAML configuration representing model options:
| Field | Requirement | Type | Description |
|---|---|---|---|
model | Required | string | Model identifier (e.g. openai/gpt-4o, anthropic/claude-sonnet-4.5) |
temperature | Optional | number | Between 0 and 2; higher values produce more varied output |
maxTokens / maxOutputTokens | Optional | integer | Maximum number of tokens to generate; at least 1 |
topP | Optional | number | Nucleus sampling: only consider tokens within this cumulative probability (0 to 1) |
topK | Optional | integer | Only sample from the K most likely tokens |
presencePenalty | Optional | number | Between -2 and 2; positive values discourage reusing tokens that already appeared |
frequencyPenalty | Optional | number | Between -2 and 2; positive values discourage tokens in proportion to how often they appeared |
stopSequences | Optional | string[] | Generation stops when the model outputs any of these strings |
seed | Optional | integer | For best-effort deterministic sampling, on providers that support it |
reasoning | Optional | string | Reasoning effort (provider-default, none, minimal, low, medium, high, xhigh) |
providerOptions | Optional | object | Provider-specific options for openai, anthropic, google, xai, mistral |
Sample structure
Each sample in the <samples> YAML array has the following structure:
| Field | Requirement | Type | Description |
|---|---|---|---|
name | Optional | string | Label or description for the sample |
note | Optional | string | Note or commentary about the sample |
history | Optional | HistoryEntry[] | Previous completed turns in multi-turn conversations |
input | Required | Input | Current turn inputs matching the target template's Input schema |
steps | Optional | Step[] | Tool calls made during the current turn |
When history is specified, each entry represents a completed prior turn:
| Field | Requirement | Type | Description |
|---|---|---|---|
input | Required | Input | Inputs for that historical turn |
steps | Optional | Step[] | Tool calls made during that turn |
output | Required | Output | Model response for that turn matching the target template's Output schema |
Each step in steps contains a toolCalls list with the following structure:
steps:
- toolCalls:
- tool: <tool name>
callId: <string>
input: <tool Input> # validated against tool's Input schema
output: <tool Output> # optional; validated against tool's Output schemaExamples
Given a template defined in prompts/Translate.tp:
<!-- Translate.tp -->
<template name="Translate">
...
</template>You can define its playground samples in prompts/Translate.play.tp:
<!-- Translate.play.tp -->
<playground for="Translate">
<model>
model: openai/gpt-4o
temperature: 0.7
</model>
<samples>
- name: "Spanish greeting"
note: "Informal greeting"
input:
text: "Hello, how are you?"
targetLanguage: "Spanish"
- name: "French formal"
input:
text: "Please take a seat."
targetLanguage: "French"
- input:
text: "What time is it?"
targetLanguage: "German"
</samples>
</playground>For multi-turn conversations or templates that use tools:
<!-- MathAssistant.play.tp -->
<playground for="MathAssistant">
<model>
model: anthropic/claude-sonnet-4.5
</model>
<samples>
- name: "Multi-turn math session"
history:
- input:
question: "What is 2+2?"
steps:
- toolCalls:
- tool: calc
callId: "call-1"
input:
expr: "2+2"
output:
result: 4
output:
answer: "4"
input:
question: "Now multiply by 10"
steps:
- toolCalls:
- tool: calc
callId: "call-2"
input:
expr: "4*10"
</samples>
</playground>