Specification
Recipaie uses JSON Schema for validation. The schemas below define the complete structure for deployment recipes and execution results.
Recipaie Schema
The recipaie schema defines the structure for deployment recipes - templates that describe how to install and configure software.
Schema URL:
Required Fields
| Field | Type | Description |
|---|---|---|
| string | Name of the service or application |
| string | Semantic version of the recipaie (e.g., "1.0.0") |
| array | Ordered list of deployment steps |
| integer | Total number of steps (must match steps array length) |
Optional Fields
| Field | Type | Description |
|---|---|---|
| string | Brief description of what this recipe deploys |
| array | Tools or conditions required before starting |
Step Structure
Each step in the steps array must contain:
| Field | Required | Description |
|---|---|---|
| Yes | Step number (1-based) |
| Yes | What action to perform |
| Yes | Why this step is needed (builds context) |
| Yes | When or under what condition to perform this step |
| No | Condition to skip this step |
| Yes | How to perform the action (command or instruction) |
| Yes | How to verify the step succeeded |
| No | Additional context or notes |
Full Schema JSON
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://recipaie.publifye.pro/recipaie.schema.json",
"title": "Recipaie",
"description": "Recipe for AI - a simple deployment guide schema for AI assistants",
"type": "object",
"required": ["name", "version", "steps", "step_count"],
"properties": {
"$schema": {
"type": "string",
"description": "Reference to the recipaie schema"
},
"name": {
"type": "string",
"description": "Name of the service or application"
},
"flavor": {
"type": "string",
"description": "Variant identifier (e.g., 'dev', 'deploy'). Empty or omitted for the main recipaie. Must match filename suffix: recipaie-{flavor}.json"
},
"version": {
"type": "string",
"description": "Semantic version of the recipaie (e.g., '1.0.0')"
},
"description": {
"type": "string",
"description": "Brief description of what this recipe deploys"
},
"prerequisites": {
"type": "array",
"items": { "type": "string" },
"description": "Tools or conditions that must exist before starting (e.g., docker, pubmcp)"
},
"steps": {
"type": "array",
"description": "Ordered list of deployment steps",
"items": {
"type": "object",
"required": ["order", "what", "why", "when", "how", "verify"],
"properties": {
"order": {
"type": "integer",
"minimum": 1,
"description": "Step number (1-based)"
},
"what": {
"type": "string",
"description": "What action to perform"
},
"why": {
"type": "string",
"description": "Why this step is needed (builds context)"
},
"when": {
"type": "string",
"description": "When or under what condition to perform this step"
},
"skip_if": {
"type": "string",
"description": "Condition to skip this step (optional)"
},
"how": {
"type": "string",
"description": "How to perform the action (command or instruction)"
},
"verify": {
"type": "string",
"description": "How to verify the step succeeded"
},
"comments": {
"type": "array",
"items": { "type": "string" },
"description": "Additional context or notes (optional)"
}
},
"additionalProperties": false
}
},
"step_count": {
"type": "integer",
"minimum": 1,
"description": "Total number of steps (must match steps array length)"
}
},
"additionalProperties": false
}
Prodaie Schema
The prodaie schema extends recipaie to track execution results per installation location. It's the "product" of running a recipaie.
Schema URL:
Structure
A prodaie contains:
name
locations- Array of installation locations, each with their own execution results
Location Structure
Each location contains:
| Field | Description |
|---|---|
| File path or directory where this instance is installed |
| Purpose of this specific installation |
| Execution status: complete, partial, or failed |
| Steps with results for this installation |
| Total number of steps |
Step Results
In addition to the recipaie step fields, prodaie steps include these required fields:
| Field | Type | Description |
|---|---|---|
| boolean |
|
| string | Explanation of what happened during execution |
The boolean success field makes it easy to programmatically check step outcomes, while details provides the human-readable explanation.
Full Schema JSON
{
"$schema": "http://json-schema.org/draft-07/schema#",
"$id": "https://recipaie.publifye.pro/prodaie.schema.json",
"title": "Prodaie",
"description": "Product of AI - a recipaie with execution results per installation location",
"type": "object",
"required": ["name", "locations"],
"properties": {
"$schema": {
"type": "string",
"description": "Reference to the prodaie schema"
},
"name": {
"type": "string",
"description": "Name of the service or application"
},
"flavor": {
"type": "string",
"description": "Variant identifier matching the recipaie that was executed. Must match filename suffix: prodaie-{flavor}.json"
},
"description": {
"type": "string",
"description": "Brief description of what this recipe deploys"
},
"prerequisites": {
"type": "array",
"items": { "type": "string" },
"description": "Tools or conditions that must exist before starting"
},
"locations": {
"type": "array",
"description": "Installation locations with their individual execution results",
"minItems": 1,
"items": {
"type": "object",
"required": ["path", "status", "steps", "step_count"],
"properties": {
"path": {
"type": "string",
"description": "File path or directory where this instance is installed"
},
"description": {
"type": "string",
"description": "Purpose of this specific installation"
},
"status": {
"type": "string",
"enum": ["complete", "partial", "failed"],
"description": "Execution status for this installation"
},
"steps": {
"type": "array",
"description": "Ordered list of deployment steps with results for this installation",
"items": {
"type": "object",
"required": ["order", "what", "why", "when", "how", "verify", "success", "details"],
"properties": {
"order": {
"type": "integer",
"minimum": 1,
"description": "Step number (1-based)"
},
"what": {
"type": "string",
"description": "What action to perform"
},
"why": {
"type": "string",
"description": "Why this step is needed (builds context)"
},
"when": {
"type": "string",
"description": "When or under what condition to perform this step"
},
"skip_if": {
"type": "string",
"description": "Condition to skip this step (optional)"
},
"how": {
"type": "string",
"description": "How to perform the action (command or instruction)"
},
"verify": {
"type": "string",
"description": "How to verify the step succeeded"
},
"success": {
"type": "boolean",
"description": "Whether the step succeeded (true) or failed (false). Steps that were intentionally skipped are also true."
},
"details": {
"type": "string",
"description": "Explanation of what happened during execution"
},
"comments": {
"type": "array",
"items": { "type": "string" },
"description": "Additional context or notes (optional)"
}
},
"additionalProperties": false
}
},
"step_count": {
"type": "integer",
"minimum": 1,
"description": "Total number of steps (must match steps array length)"
}
},
"additionalProperties": false
}
}
},
"additionalProperties": false
}
Validation
Use our web validator for quick checks, or validate programmatically:
API
curl -X POST https://recipaie.com/api/validate \
-H "Content-Type: application/json" \
-d '{"schema_type":"recipaie","content":{...your JSON...}}'CLI Tools (Unlimited)
# Using ajv-cli (Node.js)
npx ajv validate -s https://recipaie.com/schemas/recipaie.schema.json -d my-recipe.json
# Using jsonschema (Python)
pip install jsonschema
jsonschema -i my-recipe.json https://recipaie.com/schemas/recipaie.schema.json