Especificación
Recipaie utiliza JSON Schema para la validación. Los esquemas siguientes definen la estructura completa de las recetas de despliegue y de los resultados de ejecución.
Esquema Recipaie
El esquema recipaie define la estructura de las recetas de despliegue: plantillas que describen cómo instalar y configurar software.
URL del esquema:
Campos obligatorios
| Campo | Tipo | Descripción |
|---|---|---|
| string | Nombre del servicio o de la aplicación |
| string | Versión semántica del recipaie (p. ej., "1.0.0") |
| array | Lista ordenada de los pasos de despliegue |
| integer | Número total de pasos (debe coincidir con la longitud del array steps) |
Campos opcionales
| Campo | Tipo | Descripción |
|---|---|---|
| string | Breve descripción de lo que despliega esta receta |
| array | Herramientas o condiciones necesarias antes de empezar |
Estructura del paso
Cada paso del array steps debe contener:
| Campo | Obligatorio | Descripción |
|---|---|---|
| Sí | Número de paso (empezando en 1) |
| Sí | Qué acción hay que realizar |
| Sí | Por qué es necesario este paso (aporta contexto) |
| Sí | Cuándo o bajo qué condición debe realizarse este paso |
| No | Condición para omitir este paso |
| Sí | Cómo realizar la acción (comando o instrucción) |
| Sí | Cómo verificar que el paso se completó con éxito |
| No | Contexto o notas adicionales |
JSON completo del esquema
{
"$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
}
Esquema Prodaie
El esquema prodaie amplía recipaie para registrar los resultados de ejecución por ubicación de instalación. Es el "producto" de ejecutar un recipaie.
URL del esquema:
Estructura
Un prodaie contiene:
name
locations- Array de ubicaciones de instalación, cada una con sus propios resultados de ejecución
Estructura de la ubicación
Cada ubicación contiene:
| Campo | Descripción |
|---|---|
| Ruta de archivo o directorio donde está instalada esta instancia |
| Finalidad de esta instalación concreta |
| Estado de la ejecución: complete, partial o failed |
| Pasos con resultados para esta instalación |
| Número total de pasos |
Resultados del paso
Además de los campos de paso del recipaie, los pasos de un prodaie incluyen estos campos obligatorios:
| Campo | Tipo | Descripción |
|---|---|---|
| boolean |
|
| string | Explicación de lo ocurrido durante la ejecución |
El campo booleano success facilita comprobar por programa el resultado de cada paso, mientras que details aporta la explicación legible por humanos.
JSON completo del esquema
{
"$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
}
Validación
Use nuestro validador web para comprobaciones rápidas, o valide mediante programación:
API
curl -X POST https://recipaie.com/api/validate \
-H "Content-Type: application/json" \
-d '{"schema_type":"recipaie","content":{...your JSON...}}'Herramientas CLI (sin límite)
# 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