Spesifikasjon
Recipaie bruker JSON Schema for validering. Skjemaene under definerer hele strukturen for utrullingsoppskrifter og utførelsesresultater.
Recipaie-skjemaet
Recipaie-skjemaet definerer strukturen for utrullingsoppskrifter - maler som beskriver hvordan programvare installeres og konfigureres.
Skjema-URL:
Obligatoriske felt
| Felt | Type | Beskrivelse |
|---|---|---|
| string | Navnet på tjenesten eller applikasjonen |
| string | Semantisk versjon av recipaie-en (f.eks. «1.0.0») |
| array | Ordnet liste over utrullingssteg |
| integer | Totalt antall steg (må stemme med lengden på steps-arrayet) |
Valgfrie felt
| Felt | Type | Beskrivelse |
|---|---|---|
| string | Kort beskrivelse av hva denne oppskriften ruller ut |
| array | Verktøy eller betingelser som må være på plass før start |
Stegstruktur
Hvert steg i steps-arrayet må inneholde:
| Felt | Obligatorisk | Beskrivelse |
|---|---|---|
| Ja | Stegnummer (starter på 1) |
| Ja | Hvilken handling som skal utføres |
| Ja | Hvorfor dette steget trengs (bygger kontekst) |
| Ja | Når eller under hvilken betingelse dette steget skal utføres |
| Nei | Betingelse for å hoppe over dette steget |
| Ja | Hvordan handlingen utføres (kommando eller instruksjon) |
| Ja | Hvordan man verifiserer at steget lyktes |
| Nei | Ekstra kontekst eller merknader |
Hele skjemaet som 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-skjemaet
Prodaie-skjemaet utvider recipaie for å spore utførelsesresultater per installasjonssted. Det er «produktet» av å kjøre en recipaie.
Skjema-URL:
Struktur
En prodaie inneholder:
name
locations- array med installasjonssteder, hvert med sine egne utførelsesresultater
Struktur for sted
Hvert sted inneholder:
| Felt | Beskrivelse |
|---|---|
| Filsti eller katalog der denne instansen er installert |
| Formålet med denne bestemte installasjonen |
| Utførelsesstatus: complete, partial eller failed |
| Steg med resultater for denne installasjonen |
| Totalt antall steg |
Stegresultater
I tillegg til feltene fra recipaie-steget har prodaie-steg disse obligatoriske feltene:
| Felt | Type | Beskrivelse |
|---|---|---|
| boolean |
|
| string | Forklaring på hva som skjedde under utførelsen |
Det boolske success-feltet gjør det enkelt å sjekke utfallet av et steg programmatisk, mens details gir den menneskelesbare forklaringen.
Hele skjemaet som 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
}
Validering
Bruk validatoren vår på nett for raske sjekker, eller valider programmatisk:
API
curl -X POST https://recipaie.com/api/validate \
-H "Content-Type: application/json" \
-d '{"schema_type":"recipaie","content":{...your JSON...}}'CLI-verktøy (ubegrenset)
# 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