yaml-flow 3.1.1 → 4.0.0

package/schema/live-cards.schema.json

@@ -7,9 +7,9 @@
   "definitions": {
 
     "bind_ref": {
-      "description": "A state path reference, e.g. 'state.raw_quotes' or 'state.compute_vars.total'",
+      "description": "A state path reference, e.g. 'state.raw_quotes' or 'requires.upstream'",
       "type": "string",
-      "pattern": "^state\\."
+      "pattern": "^(state|requires|computed_values)\\."
     },
 
     "bind_or_literal": {
@@ -72,39 +72,46 @@
       }
     },
 
-    "data": {
+    "requires": {
+      "type": "array",
+      "items": { "type": "string" },
+      "description": "IDs of upstream nodes this node depends on"
+    },
+
+    "provides": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["bindTo", "src"],
+        "properties": {
+          "bindTo": { "type": "string", "description": "Token name published downstream" },
+          "src":    { "type": "string", "description": "Path to read value from (state.*, requires.*, computed_values.*)" }
+        }
+      },
+      "description": "Explicit bindings exposing computed/state values downstream as named tokens"
+    },
+
+    "compute_step": {
+      "description": "A single ordered compute step: reads state.*/requires.*/computed_values.*, writes to computed_values[bindTo]",
       "type": "object",
+      "required": ["bindTo", "expr"],
       "properties": {
-        "requires": {
-          "type": "array",
-          "items": { "type": "string" },
-          "description": "IDs of upstream nodes this node depends on"
-        },
-        "provides": {
-          "type": "object",
-          "description": "Subset of state exposed downstream. Keys are published names, values are bind refs.",
-          "additionalProperties": { "$ref": "#/definitions/bind_or_literal" }
-        }
+        "bindTo": { "type": "string", "description": "Key in computed_values to write result" },
+        "expr":   { "type": "string", "description": "JSONata expression evaluated against { state, requires, sources, computed_values }" }
       }
     },
 
     "source_def": {
+      "description": "One source entry. The engine only cares about 'bindTo' (compute namespace key) and 'outputFile' (delivery signal). Every other property is yours — add whatever your task-executor needs: kind, url, headers, mailbox, channel, model, query, etc. The full object is passed verbatim as the --in JSON to the executor.",
       "type": "object",
-      "required": ["kind", "bindTo"],
+      "required": ["bindTo"],
+      "additionalProperties": true,
       "properties": {
-        "kind":           { "enum": ["api", "websocket", "static", "llm"] },
-        "bindTo":         { "$ref": "#/definitions/bind_ref", "description": "state path to write fetched data into" },
-        "method":         { "enum": ["GET", "POST", "PUT", "DELETE"], "default": "GET" },
-        "url_template":   { "type": "string", "description": "URL with {{var}} placeholders" },
-        "headers":        { "type": "object", "additionalProperties": { "$ref": "#/definitions/bind_or_literal" } },
-        "body_template":  { "type": "object", "description": "Request body with {{var}} placeholders or bind refs" },
-        "template_vars":  {
-          "type": "object",
-          "additionalProperties": { "$ref": "#/definitions/bind_or_literal" },
-          "description": "Variables for url/body templates — static values or bind refs"
-        },
-        "poll_interval":  { "type": "integer", "minimum": 0, "description": "Auto-refresh in seconds (0 = manual)" },
-        "transform":      { "type": "string", "description": "Dot-path to extract from response, e.g. 'data.items'" }
+        "bindTo":     { "type": "string",  "description": "Key under sources.* available in compute expressions" },
+        "outputFile": { "type": "string",  "description": "Board-relative path the executor writes its JSON result to. Presence of this file signals delivery." },
+        "optionalForCompletionGating":   { "type": "boolean", "default": false, "description": "When true this source does not gate card completion. Default false when absent, so sources are completion-gating by default." },
+        "timeout":    { "type": "integer", "minimum": 0, "default": 120000, "description": "Executor/script timeout in ms. Default: 120 000 (2 min)." },
+        "script":     { "type": "string",  "description": "Legacy direct-run: shell command executed when no .task-executor is registered. stdout is captured as the result." }
       }
     },
 
@@ -209,58 +216,33 @@
     }
   },
 
-  "oneOf": [
-    {
-      "title": "Card",
-      "description": "A renderable card node with view elements",
-      "type": "object",
-      "required": ["id", "type", "view", "state"],
-      "additionalProperties": false,
+  "title": "LiveCard",
+  "description": "A unified card node. Behavior depends on which sections are present (sources, compute, view, etc.)",
+  "type": "object",
+  "required": ["id"],
+  "additionalProperties": false,
+  "properties": {
+    "id":       { "type": "string" },
+    "requires": { "$ref": "#/definitions/requires" },
+    "provides": { "$ref": "#/definitions/provides" },
+    "meta":     { "$ref": "#/definitions/meta" },
+    "view":     { "$ref": "#/definitions/view" },
+    "state":    { "type": "object", "additionalProperties": true,
       "properties": {
-        "id":      { "type": "string" },
-        "type":    { "const": "card" },
-        "meta":    { "$ref": "#/definitions/meta" },
-        "data":    { "$ref": "#/definitions/data" },
-        "view":    { "$ref": "#/definitions/view" },
-        "state":   { "type": "object", "additionalProperties": true,
-          "properties": {
-            "status":  { "enum": ["fresh", "stale", "loading", "error"] },
-            "lastRun": { "type": "string", "format": "date-time" },
-            "error":   { "type": "string" }
-          }
-        },
-        "compute": {
-          "type": "object",
-          "description": "Derived state: key = state path to write, value = compute_expr",
-          "additionalProperties": { "$ref": "#/definitions/compute_expr" }
-        }
+        "status":  { "enum": ["fresh", "stale", "loading", "error"] },
+        "lastRun": { "type": "string", "format": "date-time" },
+        "error":   { "type": "string" }
       }
     },
-    {
-      "title": "ExternalSource",
-      "description": "A data-only node that fetches from external systems (no view)",
-      "type": "object",
-      "required": ["id", "type", "source", "state"],
-      "additionalProperties": false,
-      "properties": {
-        "id":      { "type": "string" },
-        "type":    { "const": "source" },
-        "meta":    { "$ref": "#/definitions/meta" },
-        "data":    { "$ref": "#/definitions/data" },
-        "source":  { "$ref": "#/definitions/source_def" },
-        "state":   { "type": "object", "additionalProperties": true,
-          "properties": {
-            "status":  { "enum": ["fresh", "stale", "loading", "error"] },
-            "lastRun": { "type": "string", "format": "date-time" },
-            "error":   { "type": "string" }
-          }
-        },
-        "compute": {
-          "type": "object",
-          "description": "Derived state: key = state path to write, value = compute_expr",
-          "additionalProperties": { "$ref": "#/definitions/compute_expr" }
-        }
-      }
+    "sources": {
+      "type": "array",
+      "description": "Source entries. Each entry is passed verbatim to the board's .task-executor (registered via init --task-executor) as the --in JSON file. The executor fetches/generates the data and writes JSON to --out. If no executor is registered, the built-in executor runs the entry's 'cli' command directly. Sources gate completion by default. Set optionalForCompletionGating: true for enrichment-only sources that should not block task-completed.",
+      "items": { "$ref": "#/definitions/source_def" }
+    },
+    "compute": {
+      "type": "array",
+      "description": "Ordered array of compute steps. Each reads state.*/requires.*/sources.*/computed_values.* and writes to ephemeral computed_values[bindTo].",
+      "items": { "$ref": "#/definitions/compute_step" }
     }
-  ]
+  }
 }