@signstack/cli 0.1.1

package/dist/libs/signstack/base/schemas/blueprint.schema.json

@@ -0,0 +1,485 @@
+{
+    "$schema": "https://json-schema.org/draft/2020-12/schema",
+    "$id": "https://signstack.ai/schemas/blueprint/v1beta2",
+    "title": "SignStack Blueprint",
+    "description": "A Blueprint defines a multi-document signing workflow with orchestration. It specifies: (1) inputs - data schemas provided at runtime, (2) participants - people who will sign, (3) envelopes - groups of documents sent together, (4) orchestration - the order and conditions for signing. Blueprints are reusable workflow templates that produce Workflows when executed with concrete data.",
+    "type": "object",
+    "required": ["apiVersion", "kind", "metadata", "spec"],
+    "additionalProperties": false,
+    "properties": {
+        "apiVersion": {
+            "type": "string",
+            "const": "signstack/v1beta2",
+            "description": "API version for the blueprint schema"
+        },
+        "kind": {
+            "type": "string",
+            "const": "Blueprint",
+            "description": "Resource type identifier"
+        },
+        "metadata": {
+            "type": "object",
+            "required": ["key", "version", "name"],
+            "additionalProperties": false,
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                    "description": "Unique identifier for the blueprint. Must be snake_case: starts with a letter, contains only lowercase letters, numbers, and single underscores. Cannot end with underscore or have consecutive underscores.",
+                    "examples": [
+                        "employee_onboarding",
+                        "simple_nda",
+                        "multi_party_contract"
+                    ]
+                },
+                "version": {
+                    "type": "string",
+                    "pattern": "^(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$",
+                    "description": "Semantic version (e.g., 1.0.0)",
+                    "examples": ["1.0.0", "2.1.0", "1.0.1"]
+                },
+                "name": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 200,
+                    "description": "Human-readable name for the blueprint"
+                },
+                "description": {
+                    "type": "string",
+                    "minLength": 1,
+                    "maxLength": 1000,
+                    "description": "Description of the blueprint"
+                },
+                "labels": {
+                    "type": "object",
+                    "propertyNames": {
+                        "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$"
+                    },
+                    "additionalProperties": { "type": "string" },
+                    "description": "Key-value labels for categorization and filtering. Keys must be in snake_case format."
+                }
+            }
+        },
+        "spec": {
+            "type": "object",
+            "required": ["envelopes"],
+            "additionalProperties": false,
+            "properties": {
+                "inputs": {
+                    "type": "array",
+                    "description": "Data inputs required when creating a workflow from this blueprint. Each input references a Schema (key@version) that defines its structure. Input keys are used in JSONata expressions throughout the blueprint via $.inputKey syntax. Blueprint inputs auto-map to template inputs by matching keys - if blueprint has 'employee' and template expects 'employee', no inputMap needed.",
+                    "items": {
+                        "type": "object",
+                        "required": ["key", "schema"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "key": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                "description": "Unique identifier for the input"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Human-readable name"
+                            },
+                            "schema": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$",
+                                "description": "Reference to schema (key@version)"
+                            },
+                            "required": {
+                                "oneOf": [
+                                    { "type": "boolean" },
+                                    {
+                                        "type": "object",
+                                        "description": "Expression-based value",
+                                        "required": ["expression"],
+                                        "properties": {
+                                            "expression": {
+                                                "type": "string",
+                                                "minLength": 1,
+                                                "description": "JSONata expression (must be non-empty)"
+                                            }
+                                        },
+                                        "additionalProperties": false
+                                    }
+                                ],
+                                "default": true,
+                                "description": "Whether this input is required (boolean or expression object). Defaults to true."
+                            }
+                        }
+                    }
+                },
+                "participants": {
+                    "type": "array",
+                    "description": "People who will perform actions (sign, review, etc.) in this workflow. Each participant has a key referenced by orchestration steps. Name and email can be literal strings or JSONata expressions that pull from inputs (e.g., expression: '$.employee.email'). Define participants statically - for conditional participants, use step conditions rather than dynamic participant lists. Typical workflows have 2-5 participants.",
+                    "items": {
+                        "type": "object",
+                        "required": ["key", "name", "email"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "key": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                "description": "Unique identifier for the participant"
+                            },
+                            "name": {
+                                "oneOf": [
+                                    { "type": "string" },
+                                    {
+                                        "type": "object",
+                                        "required": ["expression"],
+                                        "additionalProperties": false,
+                                        "properties": {
+                                            "expression": {
+                                                "type": "string",
+                                                "description": "JSONata expression"
+                                            }
+                                        }
+                                    }
+                                ],
+                                "description": "Display name (literal or JSONata expression)"
+                            },
+                            "email": {
+                                "oneOf": [
+                                    { "type": "string", "format": "email" },
+                                    {
+                                        "type": "object",
+                                        "required": ["expression"],
+                                        "additionalProperties": false,
+                                        "properties": {
+                                            "expression": {
+                                                "type": "string",
+                                                "description": "JSONata expression"
+                                            }
+                                        }
+                                    }
+                                ],
+                                "description": "Email address (literal or JSONata expression)"
+                            },
+                            "roleCategory": {
+                                "type": "string",
+                                "description": "Category of the participant (e.g. signer, viewer, approver). Free-form string."
+                            }
+                        }
+                    }
+                },
+                "functions": {
+                    "description": "JsonataFunction references. Two shapes are accepted: (1) an object map where keys are aliases used in $<alias>() calls within JSONata expressions and values are versioned references (key@version) — this decouples call-site names from resource keys and pins exact versions; (2) an array of 'key@version' strings — alias defaults to functionKey.",
+                    "oneOf": [
+                        {
+                            "type": "object",
+                            "propertyNames": {
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$"
+                            },
+                            "additionalProperties": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$"
+                            }
+                        },
+                        {
+                            "type": "array",
+                            "items": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$"
+                            }
+                        }
+                    ]
+                },
+                "envelopes": {
+                    "type": "array",
+                    "minItems": 1,
+                    "description": "Envelopes group documents that are sent together in a single signing session. Use multiple envelopes when different document sets need different signing flows. Example: 'offer_envelope' (offer letter + job description) vs 'compliance_envelope' (NDA + IP agreement). Each envelope can have conditions and contains one or more documents referencing templates.",
+                    "items": {
+                        "type": "object",
+                        "required": ["key", "documents"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "key": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                "description": "Unique identifier for the envelope"
+                            },
+                            "name": {
+                                "type": "string",
+                                "description": "Human-readable name"
+                            },
+                            "subject": {
+                                "type": "string",
+                                "minLength": 1,
+                                "maxLength": 100,
+                                "description": "Email subject line used when sending this envelope for signing. Also used as the envelope display name in signing certificates and PDF filenames. Defaults to the envelope key if not specified."
+                            },
+                            "documents": {
+                                "type": "array",
+                                "minItems": 1,
+                                "description": "Documents within this envelope",
+                                "items": {
+                                    "type": "object",
+                                    "required": ["key"],
+                                    "additionalProperties": false,
+                                    "properties": {
+                                        "key": {
+                                            "type": "string",
+                                            "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                            "description": "Unique identifier for the document within the envelope"
+                                        },
+                                        "name": {
+                                            "type": "string",
+                                            "description": "Human-readable name"
+                                        },
+                                        "template": {
+                                            "type": "string",
+                                            "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*@(draft|(0|[1-9]\\d*)\\.(0|[1-9]\\d*)\\.(0|[1-9]\\d*))$",
+                                            "description": "Reference to template (key@version)"
+                                        },
+                                        "inputMap": {
+                                            "type": "object",
+                                            "additionalProperties": { "type": "string" },
+                                            "description": "Maps template input keys to JSONata expressions. Optional: blueprint inputs are auto-mapped to template inputs by matching keys. Use inputMap to override auto-mapping or provide values for template inputs that don't match any blueprint input key. Unmapped template inputs resolve to undefined."
+                                        },
+                                        "includeIf": {
+                                            "type": "string",
+                                            "description": "JSONata expression - include document if true. When iterator is present, the current array item is available as __iterator__."
+                                        },
+                                        "iterator": {
+                                            "type": "string",
+                                            "description": "JSONata path to an array (e.g. '$.position.supplements'). When specified, one document instance is created per array item. Expressions in includeIf and fileId can reference the current item via __iterator__."
+                                        },
+                                        "fileId": {
+                                            "oneOf": [
+                                                { "type": "string", "pattern": "^f_[0-9a-z]{26}$" },
+                                                {
+                                                    "type": "object",
+                                                    "required": ["expression"],
+                                                    "additionalProperties": false,
+                                                    "properties": {
+                                                        "expression": { "type": "string" }
+                                                    }
+                                                }
+                                            ],
+                                            "description": "Override the template's backing file. Can be a literal file ID string or an expression { expression: '...' } evaluated at resolution time. When iterator is present, the current array item is available as __iterator__."
+                                        }
+                                    }
+                                }
+                            },
+                            "includeIf": {
+                                "type": "string",
+                                "description": "JSONata expression - include envelope if true"
+                            }
+                        }
+                    }
+                },
+                "orchestration": {
+                    "$ref": "#/$defs/step",
+                    "description": "Root step of the orchestration tree. Can be a group (contains child steps) or participant (signing task)."
+                },
+                "customFields": {
+                    "type": "array",
+                    "description": "Custom fields for storing additional metadata or computed values. Values can be literals or JSONata expressions.",
+                    "items": {
+                        "type": "object",
+                        "required": ["key", "name"],
+                        "additionalProperties": false,
+                        "properties": {
+                            "key": {
+                                "type": "string",
+                                "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                "description": "Unique identifier for the custom field"
+                            },
+                            "name": {
+                                "type": "string",
+                                "minLength": 1,
+                                "description": "Human-readable name"
+                            },
+                            "value": {
+                                "anyOf": [
+                                    {
+                                        "type": ["string", "number", "boolean"],
+                                        "minLength": 1,
+                                        "description": "Literal value (must be non-empty for strings)"
+                                    },
+                                    {
+                                        "type": "string",
+                                        "format": "date-time",
+                                        "minLength": 1,
+                                        "description": "Date value (ISO string)"
+                                    },
+                                    {
+                                        "type": "object",
+                                        "description": "Expression-based value",
+                                        "required": ["expression"],
+                                        "properties": {
+                                            "expression": {
+                                                "type": "string",
+                                                "minLength": 1,
+                                                "description": "JSONata expression (must be non-empty)"
+                                            }
+                                        },
+                                        "additionalProperties": false
+                                    }
+                                ],
+                                "description": "Value of the custom field: non-empty literal (string, number, boolean) or object with a non-empty expression"
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    },
+    "$defs": {
+        "step": {
+            "type": "object",
+            "required": ["key", "type"],
+            "additionalProperties": false,
+            "description": "A step in the orchestration tree. Two types: (1) 'group' - contains child steps with mode (sequential/parallel) and completionRule (all/any/quorum), (2) 'participant' - assigns a person to sign documents via an action. Steps can be nested: groups contain children which can be groups or participants. The root orchestration can be either type.",
+            "properties": {
+                "key": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                    "description": "Unique identifier for this step"
+                },
+                "type": {
+                    "type": "string",
+                    "enum": ["group", "participant"],
+                    "description": "Step type: 'group' contains child steps with an execution mode, 'participant' defines a signing task"
+                },
+                "name": {
+                    "type": "string",
+                    "description": "Human-readable name"
+                },
+                "includeIf": {
+                    "type": "string",
+                    "description": "JSONata expression - include step if true"
+                },
+                "execution": {
+                    "type": "string",
+                    "enum": ["sequential", "parallel"],
+                    "default": "sequential",
+                    "description": "When children START (group only). 'sequential': children execute one at a time in order. 'parallel': all children can execute concurrently. Execution is independent of completion. Example: execution=parallel + completion=all means everyone signs at once but we wait for all."
+                },
+                "completion": {
+                    "type": "string",
+                    "enum": ["all", "any", "quorum"],
+                    "default": "all",
+                    "description": "When the group is COMPLETE (group only). 'all': wait for every child (default). 'any': complete when first child finishes (race). 'quorum': complete when quorum children finish. Common patterns: parallel+all (everyone signs concurrently), parallel+quorum (2 of 3 board members), sequential+all (sign in order)."
+                },
+                "quorum": {
+                    "type": "integer",
+                    "minimum": 1,
+                    "description": "Number of children required to complete when completion='quorum'. Example: 3 board members with quorum=2 means any 2 signatures are sufficient. Must be less than or equal to number of children."
+                },
+                "children": {
+                    "type": "array",
+                    "minItems": 1,
+                    "description": "Child steps (group only)",
+                    "items": {
+                        "$ref": "#/$defs/step"
+                    }
+                },
+                "participant": {
+                    "type": "string",
+                    "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                    "description": "Participant key (participant only, must reference a key from participants array)"
+                },
+                "onComplete": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "description": "Actions triggered when this step completes. Can validate the step result and apply data updates to entities.",
+                    "properties": {
+                        "validate": {
+                            "type": "string",
+                            "description": "JSONata expression that must evaluate to true for the step to be considered valid. Root context has three keys: $.inputs.<entityKey> (blueprint inputs at current value), $.docOutputs.<documentKey>.<roleKey> (role output payloads, participant steps only), $.childOutputs.<childStepKey>.<entityKey> (child entity snapshots, parent group steps only). Plus JSONata built-ins like $now(), $exists()."
+                        },
+                        "updates": {
+                            "type": "array",
+                            "description": "Data updates to apply when the step completes. Each update targets an entity; the transform's return value REPLACES the target entity's data wholesale (no automatic merge).",
+                            "items": {
+                                "type": "object",
+                                "required": ["key", "transform"],
+                                "additionalProperties": false,
+                                "properties": {
+                                    "key": {
+                                        "type": "string",
+                                        "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                        "description": "Target entity key to update (must match an input key)"
+                                    },
+                                    "transform": {
+                                        "type": "string",
+                                        "description": "JSONata expression whose return value REPLACES the target entity wholesale (no automatic merge). Use $merge([$.inputs.<entityKey>, { ... }]) to preserve existing fields. Root context has three keys: $.inputs.<entityKey>, $.docOutputs.<documentKey>.<roleKey>, $.childOutputs.<childStepKey>.<entityKey>. Plus JSONata built-ins like $now()."
+                                    }
+                                }
+                            }
+                        }
+                    }
+                },
+                "action": {
+                    "type": "object",
+                    "required": ["type"],
+                    "additionalProperties": false,
+                    "description": "What this participant does. Currently supports type='sign'. Groups envelope reference and role assignments together for clarity.",
+                    "properties": {
+                        "type": {
+                            "type": "string",
+                            "enum": ["sign"],
+                            "description": "Action type. 'sign' = participant signs documents in the envelope. Future types may include 'review', 'approve', 'fill'."
+                        },
+                        "envelope": {
+                            "type": "string",
+                            "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                            "description": "Which envelope this participant acts on. Must match a key from spec.envelopes array."
+                        },
+                        "assignments": {
+                            "type": "array",
+                            "minItems": 1,
+                            "description": "Maps this participant to template roles for each document. Each assignment says 'for document X, this participant fills the Y role'. The role must exist in that document's template. One participant can have different roles on different documents.",
+                            "items": {
+                                "type": "object",
+                                "required": ["document", "role"],
+                                "additionalProperties": false,
+                                "properties": {
+                                    "document": {
+                                        "type": "string",
+                                        "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                        "description": "Document key (must match a key from this step's envelope)"
+                                    },
+                                    "role": {
+                                        "type": "string",
+                                        "pattern": "^[a-z][a-z0-9]*(_[a-z0-9]+)*$",
+                                        "description": "Role key from the template"
+                                    }
+                                }
+                            }
+                        }
+                    },
+                    "allOf": [
+                        {
+                            "if": { "properties": { "type": { "const": "sign" } } },
+                            "then": { "required": ["envelope", "assignments"] }
+                        }
+                    ]
+                }
+            },
+            "allOf": [
+                {
+                    "if": { "properties": { "type": { "const": "group" } } },
+                    "then": { "required": ["execution", "children"] }
+                },
+                {
+                    "if": { "properties": { "type": { "const": "participant" } } },
+                    "then": { "required": ["participant", "action"] }
+                },
+                {
+                    "if": {
+                        "properties": {
+                            "type": { "const": "group" },
+                            "completion": { "const": "quorum" }
+                        },
+                        "required": ["completion"]
+                    },
+                    "then": { "required": ["quorum"] }
+                }
+            ]
+        }
+    }
+}