# Task Master JSON Schemas

This directory contains JSON schemas for validating Task Master prompt templates. These schemas provide IDE support, validation, and better developer experience when working with prompt templates.

## Overview

The schema system provides:
- **Structural Validation**: Ensures all required fields and proper JSON structure
- **Type Safety**: Validates parameter types and value constraints
- **IDE Integration**: IntelliSense and auto-completion in VS Code
- **Development Safety**: Catches errors before runtime
- **Documentation**: Self-documenting templates through schema definitions

## Schema Files

### `prompt-template.schema.json` (Main Schema)
**Version**: 1.0.0  
**Purpose**: Main schema for Task Master prompt template files

**Validates**:
- Template metadata (id, version, description)
- Parameter definitions with comprehensive type validation
- Prompt variants with conditional logic
- Cross-references between parameters and template variables
- Semantic versioning compliance
- Handlebars template syntax

**Required Fields**:
- `id`: Unique template identifier (kebab-case)
- `version`: Semantic version (e.g., "1.0.0")
- `description`: Human-readable description
- `prompts.default`: Default prompt variant

**Optional Fields**:
- `metadata`: Additional template information
- `parameters`: Parameter definitions for template variables
- `prompts.*`: Additional prompt variants

### `parameter.schema.json` (Parameter Schema)
**Version**: 1.0.0  
**Purpose**: Reusable schema for individual prompt parameters

**Supports**:
- **Type Validation**: `string`, `number`, `boolean`, `array`, `object`
- **Constraints**: Required/optional parameters, default values
- **String Validation**: Pattern matching (regex), enum constraints
- **Numeric Validation**: Minimum/maximum values, integer constraints
- **Array Validation**: Item types, minimum/maximum length
- **Object Validation**: Property definitions and required fields

**Parameter Properties**:
```json
{
  "type": "string|number|boolean|array|object",
  "required": true|false,
  "default": "any value matching type",
  "description": "Parameter documentation",
  "enum": ["option1", "option2"],
  "pattern": "^regex$",
  "minimum": 0,
  "maximum": 100,
  "minLength": 1,
  "maxLength": 255,
  "items": { "type": "string" },
  "properties": { "key": { "type": "string" } }
}
```

### `variant.schema.json` (Variant Schema)
**Version**: 1.0.0  
**Purpose**: Schema for prompt template variants

**Validates**:
- System and user prompt templates
- Conditional expressions for variant selection
- Variable placeholders using Handlebars syntax
- Variant metadata and descriptions

**Variant Structure**:
```json
{
  "condition": "JavaScript expression",
  "system": "System prompt template",
  "user": "User prompt template",
  "metadata": {
    "description": "When to use this variant"
  }
}
```

## Schema Validation Rules

### Template ID Validation
- **Pattern**: `^[a-z][a-z0-9-]*[a-z0-9]$`
- **Format**: Kebab-case, alphanumeric with hyphens
- **Examples**: 
  - ✅ `add-task`, `parse-prd`, `analyze-complexity`
  - ❌ `AddTask`, `add_task`, `-invalid-`, `task-`

### Version Validation
- **Pattern**: Semantic versioning (semver)
- **Format**: `MAJOR.MINOR.PATCH`
- **Examples**:
  - ✅ `1.0.0`, `2.1.3`, `10.0.0`
  - ❌ `1.0`, `v1.0.0`, `1.0.0-beta`

### Parameter Type Validation
- **String**: Text values with optional pattern/enum constraints
- **Number**: Numeric values with optional min/max constraints
- **Boolean**: True/false values
- **Array**: Lists with optional item type validation
- **Object**: Complex structures with property definitions

### Template Variable Validation
- **Handlebars Syntax**: `{{variable}}`, `{{#if condition}}`, `{{#each array}}`
- **Parameter References**: All template variables must have corresponding parameters
- **Nested Access**: Support for `{{object.property}}` notation
- **Special Variables**: `{{@index}}`, `{{@first}}`, `{{@last}}` in loops

## IDE Integration

### VS Code Setup
The VS Code profile automatically configures schema validation:

```json
{
  "json.schemas": [
    {
      "fileMatch": [
        "src/prompts/**/*.json",
        ".taskmaster/prompts/**/*.json",
        "prompts/**/*.json"
      ],
      "url": "./src/prompts/schemas/prompt-template.schema.json"
    }
  ]
}
```

**Features Provided**:
- **Auto-completion**: IntelliSense for all schema properties
- **Real-time Validation**: Immediate error highlighting
- **Hover Documentation**: Parameter descriptions on hover
- **Error Messages**: Detailed validation error explanations

### Other IDEs
For other development environments:

**Schema URLs**:
- **Local Development**: `./src/prompts/schemas/prompt-template.schema.json`
- **GitHub Reference**: `https://github.com/eyaltoledano/claude-task-master/blob/main/src/prompts/schemas/prompt-template.schema.json`

**File Patterns**:
- `src/prompts/**/*.json`
- `.taskmaster/prompts/**/*.json`
- `prompts/**/*.json`

## Validation Examples

### Valid Template Example
```json
{
  "id": "example-prompt",
  "version": "1.0.0",
  "description": "Example prompt template with comprehensive validation",
  "metadata": {
    "author": "Task Master Team",
    "category": "task",
    "tags": ["example", "validation"]
  },
  "parameters": {
    "taskDescription": {
      "type": "string",
      "description": "Description of the task to perform",
      "required": true,
      "minLength": 5,
      "maxLength": 500
    },
    "priority": {
      "type": "string",
      "description": "Task priority level",
      "required": false,
      "enum": ["high", "medium", "low"],
      "default": "medium"
    },
    "maxTokens": {
      "type": "number",
      "description": "Maximum tokens for response",
      "required": false,
      "minimum": 100,
      "maximum": 4000,
      "default": 1000
    },
    "useResearch": {
      "type": "boolean",
      "description": "Whether to include research context",
      "required": false,
      "default": false
    },
    "tags": {
      "type": "array",
      "description": "Task tags for categorization",
      "required": false,
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]*$"
      }
    }
  },
  "prompts": {
    "default": {
      "system": "You are a helpful AI assistant that creates tasks with {{priority}} priority.",
      "user": "Create a task: {{taskDescription}}{{#if tags}}\nTags: {{#each tags}}{{this}}{{#unless @last}}, {{/unless}}{{/each}}{{/if}}"
    },
    "research": {
      "condition": "useResearch === true",
      "system": "You are a research-focused AI assistant with access to current information.",
      "user": "Research and create a task: {{taskDescription}}"
    }
  }
}
```

### Common Validation Errors

**Missing Required Fields**:
```json
// ❌ Error: Missing required 'id' field
{
  "version": "1.0.0",
  "description": "Missing ID"
}
```

**Invalid ID Format**:
```json
// ❌ Error: ID must be kebab-case
{
  "id": "InvalidID_Format",
  "version": "1.0.0"
}
```

**Parameter Type Mismatch**:
```json
// ❌ Error: Parameter type doesn't match usage
{
  "parameters": {
    "count": { "type": "string" }
  },
  "prompts": {
    "default": {
      "user": "Process {{count}} items" // Should be number for counting
    }
  }
}
```

**Invalid Condition Syntax**:
```json
// ❌ Error: Invalid JavaScript in condition
{
  "prompts": {
    "variant": {
      "condition": "useResearch = true", // Should be ===
      "user": "Research prompt"
    }
  }
}
```

## Development Workflow

### Creating New Templates
1. **Start with Schema**: Use VS Code with schema validation enabled
2. **Define Structure**: Begin with required fields (id, version, description)
3. **Add Parameters**: Define all template variables with proper types
4. **Create Prompts**: Write system and user prompts with template variables
5. **Test Validation**: Ensure template validates without errors
6. **Add Variants**: Create additional variants if needed
7. **Document Usage**: Update the main README with template details

### Modifying Existing Templates
1. **Check Current Version**: Note the current version number
2. **Assess Changes**: Determine if changes are breaking or non-breaking
3. **Update Version**: Increment version following semantic versioning
4. **Maintain Compatibility**: Avoid breaking existing parameter contracts
5. **Test Thoroughly**: Verify all existing code still works
6. **Update Documentation**: Reflect changes in README files

### Schema Evolution
When updating schemas themselves:

1. **Backward Compatibility**: Ensure existing templates remain valid
2. **Version Increment**: Update schema version in `$id` and `version` fields
3. **Test Migration**: Validate all existing templates against new schema
4. **Document Changes**: Update this README with schema changes
5. **Coordinate Release**: Ensure schema and template changes are synchronized

## Advanced Validation Features

### Cross-Reference Validation
The schema validates that:
- All template variables have corresponding parameters
- Parameter types match their usage in templates
- Variant conditions reference valid parameters
- Nested property access is properly defined

### Conditional Validation
- **Dynamic Schemas**: Different validation rules based on parameter values
- **Variant Conditions**: JavaScript expression validation
- **Template Syntax**: Handlebars syntax validation
- **Parameter Dependencies**: Required parameters based on other parameters

### Custom Validation Rules
The schema includes custom validation for:
- **Semantic Versioning**: Proper version format validation
- **Template Variables**: Handlebars syntax and parameter references
- **Condition Expressions**: JavaScript expression syntax validation
- **File Patterns**: Consistent naming conventions

## Performance Considerations

### Schema Loading
- **Caching**: Schemas are loaded once and cached
- **Lazy Loading**: Validation only occurs when templates are accessed
- **Memory Efficiency**: Shared schema instances across templates

### Validation Performance
- **Fast Validation**: AJV provides optimized validation
- **Error Batching**: Multiple errors reported in single validation pass
- **Minimal Overhead**: Validation adds minimal runtime cost

### Development Impact
- **IDE Responsiveness**: Real-time validation without performance impact
- **Build Time**: Schema validation during development, not production
- **Testing Speed**: Fast validation during test execution

## Troubleshooting

### Common Schema Issues

**Schema Not Loading**:
- Check file paths in VS Code settings
- Verify schema files exist and are valid JSON
- Restart VS Code if changes aren't recognized

**Validation Not Working**:
- Ensure `ajv` and `ajv-formats` dependencies are installed
- Check for JSON syntax errors in templates
- Verify schema file paths are correct

**Performance Issues**:
- Check for circular references in schemas
- Verify schema caching is working
- Monitor validation frequency in development

### Debugging Validation Errors

**Understanding Error Messages**:
```javascript
// Example error output
{
  "instancePath": "/parameters/priority/type",
  "schemaPath": "#/properties/parameters/additionalProperties/properties/type/enum",
  "keyword": "enum",
  "params": { "allowedValues": ["string", "number", "boolean", "array", "object"] },
  "message": "must be equal to one of the allowed values"
}
```

**Common Error Patterns**:
- `instancePath`: Shows where in the template the error occurred
- `schemaPath`: Shows which schema rule was violated
- `keyword`: Indicates the type of validation that failed
- `params`: Provides additional context about the validation rule
- `message`: Human-readable description of the error

### Getting Help

**Internal Resources**:
- Main prompt README: `src/prompts/README.md`
- Schema files: `src/prompts/schemas/*.json`
- PromptManager code: `scripts/modules/prompt-manager.js`

**External Resources**:
- JSON Schema documentation: https://json-schema.org/
- AJV validation library: https://ajv.js.org/
- Handlebars template syntax: https://handlebarsjs.com/

## Schema URLs and References

### Current Schema Locations
- **Local Development**: `./src/prompts/schemas/prompt-template.schema.json`
- **GitHub Blob**: `https://github.com/eyaltoledano/claude-task-master/blob/main/src/prompts/schemas/prompt-template.schema.json`
- **Schema ID**: Used for internal references and validation

### URL Usage Guidelines
- **`$id` Field**: Use GitHub blob URLs for stable schema identification
- **Local References**: Use relative paths for development and testing
- **External Tools**: GitHub blob URLs provide stable, version-controlled access
- **Documentation**: Link to GitHub for public schema access