Compiler Implementation Guide

This guide defines the requirements for implementing a compliant ITS compiler. Requirements are categorized using RFC 2119 keywords:

Compilation Process

1. Schema Validation

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)

2. Schema Loading

MUST Support URL and Relative Paths

The extends array can contain:

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

SHOULD Report Loading Progress

For better user experience, report which schemas are being loaded.

MAY Implement Caching

Compilers may cache remote schemas to improve performance.

MAY Implement Security Controls

Optional security features include:

Domain allowlists/blocklists
HTTPS-only requirements
Schema size limits
Request timeouts

3. Type Resolution

MUST Follow Precedence Rules

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

customInstructionTypes in the template
Last schema in extends array
Previous schemas in reverse order
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.

SHOULD Report Overrides

Compilers should inform users when types are overridden:

INFO: Instruction type overrides detected:
- 'summary' overridden by marketing-types.json (from company-types.json)
- 'list' overridden by customInstructionTypes (from its-standard-types-v1.json)

4. Variable Processing

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]}

MUST Handle Undefined Variables

If a variable reference is undefined, compilers MUST either:

Fail with a clear error message
Leave the reference unchanged (e.g., ${undefined})

5. Conditional Evaluation

MUST Support Expression Operators

Operator Type	Operators	Example
Equality	`==`, `!=`	`tone == 'professional'`
Comparison	`>`, `<`, `>=`, `<=`	`count > 5`
Logical	`&&`, `\|\|`, `!`	`includeA && !includeB`
Membership	`in`	`type in ['A', 'B', 'C']`

MUST Support Nested Conditionals

Conditionals can contain other conditionals in their content arrays.

SHOULD Provide Clear Expression Errors

Invalid expressions should produce helpful error messages.

6. Instruction Generation

MUST Process Placeholder Templates

For each placeholder:

Look up the instruction type definition
Apply config values to the template
Wrap user description in the content wrapper
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

Example Instruction Generation

Type Definition:

{
  "instructionTypes": {
    "list": {
      "template": "<<Replace this placeholder with a list using this user prompt: ([{<{description}>}]). Format requirements: Use {format} formatting with each item on a new line.>>",
      "configSchema": {
        "type": "object",
        "properties": {
          "format": {
            "type": "string",
            "enum": ["bullet_points", "numbered"],
            "default": "bullet_points"
          }
        }
      }
    }
  }
}

Placeholder in Template:

{
  "type": "placeholder",
  "instructionType": "list",
  "config": {
    "description": "List 5 fruits",
    "format": "bullet_points"
  }
}

Processing Steps:

Replace {description} with "List 5 fruits"
Replace {format} with "bullet_points"
Wrap the description in content wrapper: ([{<List 5 fruits>}])

Generated Instruction:

<<Replace this placeholder with a list using this user prompt: ([{<List 5 fruits>}]). Format requirements: Use bullet_points formatting with each item on a new line.>>

7. Output Format

MUST Generate Three-Section Output

The compiled output must have these sections:

INTRODUCTION

[System prompt from compilerConfig]

INSTRUCTIONS

[Processing instructions from compilerConfig]

TEMPLATE

[Processed template content with instructions]

SHOULD Preserve Template Formatting

Maintain line breaks, spacing, and structure from the original template.

8. Error Handling

Error Type	Required Behavior	Example Message
Schema Validation	MUST fail compilation	"Template validation failed: Missing required property 'content'"
Schema Loading	MUST fail compilation	"Failed to load schema: https://example.com/types.json (404 Not Found)"
Version Mismatch	MUST fail compilation	"Schema version 2.0 incompatible with template version 1.0"
Undefined Variable	MUST fail or preserve	"Undefined variable: ${productName}"
Invalid Expression	MUST fail compilation	"Invalid conditional expression: 'count >> 5'"
Missing Type	MUST fail compilation	"Unknown instruction type: 'custom_type'"

9. Optional Features

MAY Support Watch Mode

Recompile templates when source files change.

MAY Generate Multiple Output Formats

Besides the standard prompt format, compilers may generate:

API-ready JSON payloads
Model-specific formats
Debug outputs with metadata

MAY Provide IDE Integration

Language server protocol support for real-time validation.

Reference Implementation

ITS Compiler Python

The ITS Compiler Python provides a complete reference implementation of this specification. Use it to:

Test compliance - Verify your templates work correctly
Study implementation - See how the specification is implemented in practice
Compare behavior - Ensure your compiler produces consistent results

Installation:

pip install its-compiler-python

Usage:

# Compile a template
its-compile template.json --output prompt.txt

# Validate without compiling
its-compile template.json --validate-only

# Watch mode for development
its-compile template.json --watch

Pseudo-code Compilation Flow

function compileTemplate(templatePath) {
  // 1. Load and validate template
  const template = loadJSON(templatePath)
  validateSchema(template, BASE_SCHEMA)
  
  // 2. Load extended schemas
  const types = {}
  for (const schemaUrl of template.extends || []) {
    const schema = loadSchema(schemaUrl)
    validateSchema(schema, TYPE_EXTENSION_SCHEMA)
    
    // Apply overrides
    Object.assign(types, schema.instructionTypes)
  }
  
  // 3. Apply custom types (highest precedence)
  Object.assign(types, template.customInstructionTypes || {})
  
  // 4. Process variables
  const processedContent = processVariables(template.content, template.variables)
  
  // 5. Evaluate conditionals
  const finalContent = evaluateConditionals(processedContent, template.variables)
  
  // 6. Generate instructions
  const compiledTemplate = generateInstructions(finalContent, types)
  
  // 7. Assemble final output
  return assembleOutput(template.compilerConfig, compiledTemplate)
}

Overview