Compiler Implementation Guide

MUST Validate Template Structure

Compilers MUST validate templates against the base schema before processing:

• Verify required properties (version, content)
• Validate content element types
• Check property constraints and patterns

MUST Validate Extended Schemas

When loading schemas from the extends array:

• Validate against the type extension schema
• Verify version compatibility with the template
• Ensure instruction types have required template field

MUST Fail on Invalid Schemas

Compilation MUST fail if:

• Template doesn't validate against base schema
• Extended schemas don't validate against type extension schema
• Any schema fails to load (network error, file not found)

MUST Support URL and Relative Paths

The extends array can contain:

• Full URLs: https://example.com/schema.json
• Relative paths: ./local-schema.json

MUST Follow Precedence Rules

Instruction types are resolved in this order (highest to lowest):

1. customInstructionTypes in the template
2. Last schema in extends array
3. Previous schemas in reverse order
4. First schema in extends array

MUST Apply Complete Override

When a type is defined in multiple schemas, the entire definition is replaced. No property merging occurs.

MUST Support Variable Syntax

Replace ${variableName} references with variable values in:

• Text element content
• Placeholder descriptions
• Config property values

MUST Support Variable Types

Handle all JSON-compatible types:

• Strings: ${name}
• Numbers: ${count}
• Booleans: ${enabled}
• Object properties: ${user.name}
• Array elements: ${items[0]}, including negative indices that select from the end (${items[-1]})
• The .length pseudo-property on arrays and strings: ${items.length}

MUST Support Collection Functions

Array references accept a chain of collection functions after the path: concat(prop?), sum(prop?), avg(prop?), min(prop?), max(prop?) and top(n). They are chainable suffixes applied left to right (for example ${forecast.top(3).concat(day)}) and are valid in substitution only, never in conditional expressions. Aggregations require numeric values, and whole-number results render without a decimal part.

MUST Handle Undefined Variables

If a variable reference is undefined, compilers MUST fail with a clear error message. Both reference compilers fail in this case, and the shared invalid-template suite requires an error.

MUST Support Expression Operators

MUST Support Nested Conditionals

Conditionals can contain other conditionals in their content arrays.

MUST Process Placeholder Templates

For each placeholder:

1. Look up the instruction type definition
2. Apply config values to the template
3. Wrap user description in the content wrapper
4. Generate the complete instruction

MUST Handle Missing Config Properties

If a template references {property} but it's not in config:

• Use the default value from configSchema if available
• Otherwise, fail with an error

MUST Generate Four-Section Output

The compiled output must have these sections:

INTRODUCTION

[System prompt from compilerConfig]

INSTRUCTIONS

[Processing instructions from compilerConfig]

REFERENCE DATA

[Rendered data sources - only when the template uses reference data]

TEMPLATE

[Processed template content with instructions]

The REFERENCE DATA section is emitted only when any placeholder names a dataSource or any variable reference resolves to an object; templates using neither omit that section entirely.

MUST Support the Reserved Data Source Keys

Compilers MUST support the reserved placeholder config keys dataSource (a variable name or array of variable names) and dataLimit (a positive integer).

MUST Render Reference Data Correctly

• Render each referenced variable once above the template: arrays of objects as markdown tables, plain objects as field tables
• Deduplicate sources across placeholders so each renders a single section
• When placeholders share a source with different limits, apply the most generous dataLimit; a reference without a limit beats any limit
• State truncation in the rendered section, for example "Showing the first N of M items."
• Fail with an error when a dataSource names an unknown variable
• Skip sources referenced only inside excluded conditional branches
• Substitute the pointer text "the X reference data" for object-valued ${refs} and render the object as reference data automatically
• Add the processing instruction telling the model to use the section as context and never output it

MUST Enforce Configurable Limits

Compilers MUST enforce processing limits - template size, content element count, nesting depth, total variable count (nested values included), items per variable array, and text length - and MUST make them operator-configurable. A template can never raise the limits of the compiler processing it. The reference implementations expose these via configuration objects, CLI flags (JavaScript) and ITS_* environment variables (Python and .NET).