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: https://recipaie.com/schemas/recipaie.schema.json

Required Fields

Field	Type	Description
`name`	string	Name of the service or application
`version`	string	Semantic version of the recipaie (e.g., "1.0.0")
`steps`	array	Ordered list of deployment steps
`step_count`	integer	Total number of steps (must match steps array length)

Optional Fields

Field	Type	Description
`description`	string	Brief description of what this recipe deploys
`prerequisites`	array	Tools or conditions required before starting

Step Structure

Each step in the steps array must contain:

Field	Required	Description
`order`	Yes	Step number (1-based)
`what`	Yes	What action to perform
`why`	Yes	Why this step is needed (builds context)
`when`	Yes	When or under what condition to perform this step
`skip_if`	No	Condition to skip this step
`how`	Yes	How to perform the action (command or instruction)
`verify`	Yes	How to verify the step succeeded
`comments`	No	Additional context or notes

Full Schema JSON

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://recipaie.com/schemas/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"
    },
    "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: https://recipaie.com/schemas/prodaie.schema.json

Structure

A prodaie contains:

name - Must match the original recipaie
locations - Array of installation locations, each with their own execution results

Location Structure

Each location contains:

Field	Description
`path`	File path or directory where this instance is installed
`description`	Purpose of this specific installation
`status`	Execution status: complete, partial, or failed
`steps`	Steps with results for this installation
`step_count`	Total number of steps

Step Results

In addition to the recipaie step fields, prodaie steps include these required fields:

Field	Type	Description
`success`	boolean	`true` if step succeeded or was intentionally skipped, `false` if failed
`details`	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.com/schemas/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"
    },
    "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