Getting Started - Instruction Template Specification (ITS)

Step 1: Understand the Concept

ITS templates are JSON files that define content with placeholders. These placeholders become instructions for AI systems to generate specific types of content.

Traditional templating: Hello {{name}} + data → Hello John
ITS: Hello [name placeholder] → AI instruction → AI-generated content

Step 2: Basic Template Structure

Every ITS template has this structure:

{
  "$schema": "https://alexanderparker.github.io/.../its-base-schema-v1.json",
  "version": "1.0.0",
  "extends": [
    "https://alexanderparker.github.io/.../its-standard-types-v1.json"
  ],
  "content": [
    // Your content elements here
  ]
}

The $schema reference enables validation and autocompletion in editors that support JSON Schema.

Step 3: Content Elements

Content is an array of elements. There are three types:

Text Elements (Static Content)

{
  "type": "text",
  "text": "This text appears exactly as written."
}

Placeholder Elements (Dynamic Instructions)

{
  "type": "placeholder",
  "id": "my_list",
  "instructionType": "list",
  "config": {
    "description": "list 5 programming languages",
    "displayName": "Programming Languages",
    "format": "bullet_points"
  }
}

Conditional Elements (Variable Content)

{
  "type": "conditional",
  "condition": "audience == 'technical'",
  "content": [
    {"type": "text", "text": "Technical details: "}
  ],
  "else": [
    {"type": "text", "text": "General overview: "}
  ]
}

Step 4: Your First Template

Create a simple template for a product description:

{
  "$schema": "https://alexanderparker.github.io/.../its-base-schema-v1.json",
  "version": "1.0.0",
  "extends": [
    "https://alexanderparker.github.io/.../its-standard-types-v1.json"
  ],
  "metadata": {
    "name": "Product Description Template",
    "description": "Basic template for product descriptions",
    "author": "Your Name"
  },
  "content": [
    {
      "type": "text",
      "text": "# "
    },
    {
      "type": "placeholder",
      "id": "product_name",
      "instructionType": "title",
      "config": {
        "description": "Create a product name for a smart water bottle",
        "displayName": "Product Name",
        "style": "descriptive",
        "length": "short"
      }
    },
    {
      "type": "text",
      "text": "\n\n"
    },
    {
      "type": "placeholder",
      "id": "description",
      "instructionType": "paragraph",
      "config": {
        "description": "Write a description of a smart water bottle that tracks hydration",
        "displayName": "Product Description",
        "tone": "professional",
        "length": "medium"
      }
    },
    {
      "type": "text",
      "text": "\n\n## Key Features\n\n"
    },
    {
      "type": "placeholder",
      "id": "features",
      "instructionType": "list",
      "config": {
        "description": "List 4 features of a smart water bottle",
        "displayName": "Features List",
        "format": "bullet_points",
        "itemCount": 4
      }
    }
  ]
}

Step 5: How Templates Compile

Your template compiles into an AI prompt with three sections:

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

# <}]). Format requirements: Create a descriptive title that is short in length.>>

<}]). Format requirements: Use professional tone and medium length (2-4 sentences).>>

## Key Features

<}]). Format requirements: Use bullet_points formatting with each item on a new line. Create exactly 4 items.>>

Notice how user content descriptions are wrapped in ([{<...>}]) to prevent parsing conflicts with special characters.

Step 6: Using Variables

Variables make templates reusable. Define them at the template level and reference with ${variableName}:

{
  "variables": {
    "productType": "smart water bottle",
    "features": 4,
    "tone": "professional"
  },
  "content": [
    {
      "type": "text",
      "text": "Introducing our new ${productType}!\n\n"
    },
    {
      "type": "placeholder",
      "id": "feature_list",
      "instructionType": "list",
      "config": {
        "description": "List ${features} features of a ${productType}",
        "format": "bullet_points",
        "itemCount": "${features}"
      }
    }
  ]
}

Variable Types

Strings: "productType": "headphones"
Numbers: "price": 99.99
Booleans: "includeWarranty": true
Objects: "brand": {"name": "TechCo", "slogan": "Innovation First"}
Arrays: "categories": ["audio", "premium", "wireless"]

Access nested values with dot notation: ${brand.name} or array indices: ${categories[0]}

Step 7: Conditional Content

Use conditionals to include or exclude content based on variables:

{
  "variables": {
    "audienceLevel": "technical",
    "includeSpecs": true
  },
  "content": [
    {
      "type": "conditional",
      "condition": "audienceLevel == 'technical' && includeSpecs == true",
      "content": [
        {
          "type": "text",
          "text": "## Technical Specifications\n\n"
        },
        {
          "type": "placeholder",
          "instructionType": "table",
          "config": {
            "description": "Create a technical specs table",
            "format": "markdown",
            "columns": 2,
            "rows": 5
          }
        }
      ],
      "else": [
        {
          "type": "text",
          "text": "## Why You'll Love It\n\n"
        },
        {
          "type": "placeholder",
          "instructionType": "list",
          "config": {
            "description": "List user benefits in simple terms",
            "format": "bullet_points"
          }
        }
      ]
    }
  ]
}

Supported Operators

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

Step 8: Available Instruction Types

The standard library includes these instruction types:

title - Headlines with style control
list - Formatted lists (bullets, numbers, etc.)
paragraph - Text with tone and length control
table - Structured data tables
code_block - Code snippets with syntax highlighting
dialogue - Conversations between multiple people
quote - Relevant quotes with attribution
summary - Summaries of varying detail
image_description - Descriptive image text

See the specification for detailed documentation of each type and their configuration options.

Step 9: Validation

Validate your templates using JSON Schema tools:

Many code editors automatically validate JSON files when you include the $schema property.

Online validation:

JSON Schema Validator

Command line validation:

# Using ajv-cli
npm install -g ajv-cli
ajv validate -s schema-url -d your-template.json

Getting Started with ITS