Skip to content

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:

ElementPurpose
<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.

xml
<!-- 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:

AttributeRequirementFormatDescription
nameRequiredPascalCaseUnique name within the namespace
namespaceOptionalPascalCaseNamespace this template belongs to; defaults to Main

Child elements (in any order):

ElementRequirementDescription
<meta>If top-level <meta> existsPer-template metadata values
<schema>RequiredInput and Output types
<tools>OptionalTools the model may call
<system>RequiredSystem instructions
<user>RequiredUser message
<examples>OptionalFew-shot examples
<snippet>OptionalReusable text fragments
<variant>OptionalPrompt 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.

xml
<!-- 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.

xml
<!-- 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.

xml
<!-- 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:

xml
<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.

xml
<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:

xml
<insert val="input.userQuery" />
<insert val="input.documents" format="json" />

The format attribute controls serialization:

ValueDescription
text(default) Renders the value as a plain string. The value must be of type string or integer.
jsonPretty-printed JSON (2-space indent).
yamlYAML serialization.
toonTOON — a structured, human-readable format optimized for LLM consumption.
csvComma-separated values. The value must be an array of objects whose fields are strings or numbers; the field names become the header row.
tsvTab-separated values. Same requirements as csv.

To insert a snippet, use the snippet attribute:

xml
<insert snippet="systemContext" />

To insert a schema, use the schema attribute with format="typescript":

xml
<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:

xml
<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.

xml
<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:

xml
<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:

xml
<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:

xml
<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:

yaml
- 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:

xml
<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:

xml
<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="..." />.

xml
<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:

xml
<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:

AttributeDescription
ifExpression to evaluate (e.g. input.userLocation)
isCondition 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:

xml
<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 Input type must include a variant field 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>.
xml
<!-- 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:

AttributeRequirementFormatDescription
nameRequiredcamelCaseUnique name within the namespace
namespaceOptionalPascalCaseNamespace this tool belongs to; defaults to Main

Child elements:

ElementRequirementDescription
<description>RequiredHuman/model-readable description of what the tool does
<schema>RequiredInput and Output types; Input must be an interface
xml
<!-- 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.

xml
<!-- Geo/shared.tp -->
<namespace name="Geo">
  interface Address {
    street: string;
    city: string;
    country: string;
  }
</namespace>
xml
<!-- Geo/FormatAddress.tp -->
<template name="FormatAddress" namespace="Geo">
  <schema>
    interface Input {
      address: shared.Address;
      locale: string;
    }

    type Output = string;
  </schema>
  ...
</template>
xml
<!-- 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:

AttributeRequirementFormatDescription
nameRequiredPascalCaseUnique 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:

AttributeRequirementFormatDescription
forRequiredPascalCaseName of the template this playground targets
namespaceOptionalPascalCaseNamespace of the target template; defaults to Main

Model configuration ​

The <model> element contains YAML configuration representing model options:

FieldRequirementTypeDescription
modelRequiredstringModel identifier (e.g. openai/gpt-4o, anthropic/claude-sonnet-4.5)
temperatureOptionalnumberBetween 0 and 2; higher values produce more varied output
maxTokens / maxOutputTokensOptionalintegerMaximum number of tokens to generate; at least 1
topPOptionalnumberNucleus sampling: only consider tokens within this cumulative probability (0 to 1)
topKOptionalintegerOnly sample from the K most likely tokens
presencePenaltyOptionalnumberBetween -2 and 2; positive values discourage reusing tokens that already appeared
frequencyPenaltyOptionalnumberBetween -2 and 2; positive values discourage tokens in proportion to how often they appeared
stopSequencesOptionalstring[]Generation stops when the model outputs any of these strings
seedOptionalintegerFor best-effort deterministic sampling, on providers that support it
reasoningOptionalstringReasoning effort (provider-default, none, minimal, low, medium, high, xhigh)
providerOptionsOptionalobjectProvider-specific options for openai, anthropic, google, xai, mistral

Sample structure ​

Each sample in the <samples> YAML array has the following structure:

FieldRequirementTypeDescription
nameOptionalstringLabel or description for the sample
noteOptionalstringNote or commentary about the sample
historyOptionalHistoryEntry[]Previous completed turns in multi-turn conversations
inputRequiredInputCurrent turn inputs matching the target template's Input schema
stepsOptionalStep[]Tool calls made during the current turn

When history is specified, each entry represents a completed prior turn:

FieldRequirementTypeDescription
inputRequiredInputInputs for that historical turn
stepsOptionalStep[]Tool calls made during that turn
outputRequiredOutputModel response for that turn matching the target template's Output schema

Each step in steps contains a toolCalls list with the following structure:

yaml
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 schema

Examples ​

Given a template defined in prompts/Translate.tp:

xml
<!-- Translate.tp -->
<template name="Translate">
  ...
</template>

You can define its playground samples in prompts/Translate.play.tp:

xml
<!-- 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:

xml
<!-- 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>

Made with 🩷 in New York and outer space