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

Variable Types

Conditional Expressions

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

Supported Operators

• Equality: ==, !=
• Comparison: >, <, >=, <=
• Logical: && (AND), || (OR), ! (NOT)
• Membership: in (for arrays and strings)

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 Implementation

The ITS Compiler Python provides a complete reference implementation of the compilation process. 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 designed to convert content templates into actual content. 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.>>