ITS Specification

Core Concepts

• Instruction-Generative: Placeholders become AI instructions, not data substitutions
• Content-First: Natural language content with embedded placeholders
• Type System: Extensible instruction types with validation
• Compilation: Templates compile to structured AI prompts

Base Schema URL

https://alexanderparker.github.io/instruction-template-specification/schema/v1.0/its-base-schema-v1.json

Required Properties

Optional Properties

Variable Definition

Variables are defined in the top-level variables object and can store strings, numbers, booleans, objects, or arrays.

{
  "variables": {
    "tone": "professional",
    "productType": "gaming headset",
    "featureCount": 5,
    "includeSpecs": true,
    "brandInfo": {
      "name": "TechCorp",
      "tagline": "Innovation First"
    }
  }
}

Variable Reference Syntax

Use ${variableName} syntax to reference variables throughout your template:

{
  "type": "text",
  "text": "Welcome to ${brandInfo.name} - ${brandInfo.tagline}"
}

{
  "type": "placeholder",
  "instructionType": "list",
  "config": {
    "description": "List ${featureCount} key features of a ${productType}",
    "format": "bullet_points",
    "itemCount": "${featureCount}"
  }
}

{
  "type": "text",
  "text": "The forecast covers ${forecast.length} days, ending on ${forecast[-1].day}."
}

Collection Functions

References to array variables accept a chain of collection functions after the path, applied left to right during substitution. A property argument extracts that property from each object item; without one the items themselves are used. Aggregations require numeric values, and whole-number results render without a decimal part. Functions are part of the reference syntax for substitution only; conditional expressions do not accept function calls.

${forecast.concat(day)}         // "Monday, Tuesday, Wednesday" - joins with ", "
${forecast.sum(high)}           // 82
${forecast.avg(high)}           // averages; min(prop) and max(prop) likewise
${scores.sum()}                 // aggregate arrays of numbers directly
${forecast.top(3)}              // first three items; chains with other functions
${forecast.top(2).concat(day)}  // "Monday, Tuesday"

Supported functions: concat(property?), sum(property?), avg(property?), min(property?), max(property?) and top(n), alongside the existing .length pseudo-property. Applying a function to a non-array, referencing a property missing from any item, or aggregating non-numeric values is a compilation error.

Variable Types

Conditional Expressions

Conditional elements use JavaScript-like expression syntax to control content inclusion:

Supported Operators

• Equality: ==, !=
• Comparison: >, <, >=, <=, including chained comparisons such as 1 < number <= 10
• Logical: && (AND), || (OR), ! (NOT), with the word forms and, or and not accepted as equivalents
• Membership: in and not in (for arrays and strings), with array literals such as status in ['active', 'trial']

Expression Examples

// Simple equality
"condition": "tone == 'professional'"

// Numeric comparison
"condition": "featureCount > 3"

// Boolean check
"condition": "includeSpecs == true"

// Compound conditions
"condition": "tone == 'professional' && featureCount > 3"

// Membership test
"condition": "productType in ['headset', 'speakers', 'microphone']"

// Object property access
"condition": "sections.intro == true"

// Negation
"condition": "!includeSpecs"

Overview

Templates can import instruction type definitions from external schemas using the extends property. This enables sharing and reusing instruction types across templates.

{
  "$schema": "https://alexanderparker.github.io/.../its-base-schema-v1.json",
  "version": "1.0.0",
  "extends": [
    "https://alexanderparker.github.io/.../its-standard-types-v1.json",
    "./my-local-types.json",
    "https://example.com/custom-types.json"
  ],
  "content": [...]
}

Resolution Rules

1. Complete Override Principle

When multiple schemas define the same instruction type, the entire definition from the later schema replaces the earlier one. No partial merging occurs.

2. Precedence Order

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

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

{
  "extends": [
    "schema-a.json",  // Lowest precedence
    "schema-b.json",  // Overrides schema-a
    "schema-c.json"   // Overrides schema-b and schema-a
  ],
  "customInstructionTypes": {
    "mytype": {...}   // Highest precedence, overrides all
  }
}

3. Version Compatibility

Extended schemas must be compatible with the template's base specification version. The version is determined by the $schema reference in the template.

Extended Schema Format

Extended schemas must follow this structure and be validated against the Type Extension Schema:

{
  "$schema": "https://alexanderparker.github.io/.../its-type-extension-schema-v1.json",
  "title": "My Custom Types",
  "description": "Description of these types",
  "version": "1.0.0",
  "instructionTypes": {
    "typeName": {
      "template": "<>",
      "description": "What this instruction type does",
      "configSchema": {
        "type": "object",
        "properties": {
          // Configuration property definitions
        }
      }
    }
  }
}

Reference Implementations

Multiple compiler implementations are available that implement this specification:

Python Compiler (Reference)

The ITS Compiler Python provides the complete reference implementation of the compilation process.

JavaScript/TypeScript Compiler

The ITS Compiler JavaScript provides a TypeScript implementation with jsep-based expression evaluation.

See the Compiler Implementation Guide for detailed requirements when building your own compiler.

Escaping Format

User content wrapper: ([{<USER_CONTENT>}])

Why this pattern:

• Extremely rare for users to type this exact sequence
• Multiple nested bracket types prevent accidental termination
• Visually distinct from regular content
• AI models can easily identify content boundaries

Handles edge cases like:

"description": "Create code like {\"key\": \"value\"} with \"quotes\" and <<brackets>>"

Safely compiles to:

([{<Create code like {"key": "value"} with "quotes" and <<brackets>>>}])

Example Compilation

Input Template:

{
  "content": [
    {"type": "text", "text": "Here are some fruits:\n"},
    {
      "type": "placeholder",
      "instructionType": "list",
      "config": {
        "description": "list 5 citrus fruits",
        "format": "bullet_points"
      }
    }
  ]
}

Compiled Output:

INTRODUCTION

You are an AI assistant that fills in content templates. Follow the instructions exactly and replace each placeholder with appropriate content based on the user prompts provided. Respond only with the transformed content.

INSTRUCTIONS

1. Replace each placeholder marked with << >> with generated content
2. The user's content request is wrapped in ([{< >}]) to distinguish it from instructions
3. Follow the format requirements specified after each user prompt
4. Maintain the existing structure and formatting of the template
5. Only replace the placeholders - do not modify any other text
6. Generate content that matches the tone and style requested
7. Respond only with the transformed content - do not include any explanations or additional text

TEMPLATE

Here are some fruits:

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

This template uses no reference data, so the REFERENCE DATA section is omitted here. When any placeholder names a dataSource, or any variable reference resolves to an object, that section is inserted between INSTRUCTIONS and TEMPLATE, giving up to four sections in total.