{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://qubesync.com/api/v2/workflows/schema.json",
  "title": "QuBeSync workflow chart",
  "description": "A workflow is one JSON document: a Harel statechart whose states queue QuickBooks requests, pause for a decision from the calling app, or transform data. Qube.Workflows.Chart.validate/1 is the source of truth; this schema is documentation and a first-pass check. A run takes at most 500 transitions, then fails with fault transition_limit: a paginating loop costs about two per page, so about 250 pages a run.",
  "type": "object",
  "required": [
    "version",
    "initial",
    "states"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "const": 1
    },
    "key": {
      "$ref": "#/$defs/workflowKey"
    },
    "name": {
      "type": "string"
    },
    "description": {
      "type": "string"
    },
    "input": {
      "type": "object",
      "description": "What a run accepts. Validated at run start and published as a JSON Schema.",
      "propertyNames": {
        "$ref": "#/$defs/identifier"
      },
      "additionalProperties": {
        "$ref": "#/$defs/inputDeclaration"
      }
    },
    "outcomes": {
      "type": "object",
      "description": "Extra ways a run can end, beyond completed and failed. Each is a success (the default: the workflow worked as designed and this is how it ended; the run ends `completed` with this `outcome`) or, with `\"kind\": \"failure\"`, a named failure (the run ends `failed` with this `outcome`, and `error` is whatever the transition assigned to `error`, else the description, else `ended with outcome <key>`). A transition may target a declared outcome from anywhere, and no state at any level may use one of these keys.",
      "propertyNames": {
        "pattern": "^[a-z][a-z0-9_]{0,49}$"
      },
      "additionalProperties": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string",
            "description": "What this ending means, when its key does not say it already. Optional. Shown on the canvas, in the usage contract and in the guide."
          },
          "kind": {
            "enum": [
              "success",
              "failure"
            ],
            "default": "success",
            "description": "success: the run ends completed with this outcome. failure: the run ends failed with this outcome, and a workflow calling this one receives it as an error with response.outcome set."
          },
          "output": {
            "description": "Template rendered when the run ends this way, instead of the chart's own `output`. While it renders, `meta.outcome` holds the outcome key."
          },
          "headline": {
            "type": "string",
            "description": "One plain sentence saying what happened when the run ends this way, the `headline` of its webhook: a template, rendered with the run's context and `output` (and `error` on a failure), such as \"Created ${output.record.full_name} in QuickBooks.\" A value it names that is missing, or a template that does not render, gives the engine's own sentence instead. For people: an app never parses it."
          }
        }
      }
    },
    "initial": {
      "$ref": "#/$defs/identifier"
    },
    "on": {
      "$ref": "#/$defs/eventMap"
    },
    "states": {
      "$ref": "#/$defs/statesMap"
    },
    "headline": {
      "type": "string",
      "description": "One plain sentence saying what happened when the run ends `completed`, the `headline` of its webhook, rendered as a declared outcome's `headline` is. Without one the webhook says \"<name> completed.\""
    },
    "output": {
      "description": "Template evaluated against the final context when the run reaches `completed` or an outcome with no `output` of its own. Defaults to ${vars}. While it renders, `meta.outcome` holds the outcome key."
    },
    "ui": {
      "type": "object",
      "description": "Canvas bookkeeping for the chart itself, ignored by the engine: one entry per outcome placing its terminal node, and `transitions` placing the pills of the root's own handlers, keyed \"<event>|<index>\"."
    }
  },
  "$defs": {
    "identifier": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{0,49}$"
    },
    "workflowKey": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9_]{0,63}$"
    },
    "reservedStateKeys": {
      "enum": [
        "completed",
        "failed"
      ]
    },
    "statesMap": {
      "type": "object",
      "minProperties": 1,
      "propertyNames": {
        "allOf": [
          {
            "$ref": "#/$defs/identifier"
          },
          {
            "not": {
              "$ref": "#/$defs/reservedStateKeys"
            }
          }
        ]
      },
      "additionalProperties": {
        "$ref": "#/$defs/state"
      }
    },
    "state": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "enum": [
            "request",
            "wait",
            "workflow",
            "transform",
            "choice",
            "compound",
            "final",
            "notify",
            "match"
          ]
        },
        "description": {
          "type": "string"
        },
        "entry": {
          "$ref": "#/$defs/assignMap"
        },
        "exit": {
          "$ref": "#/$defs/assignMap"
        },
        "on": {
          "$ref": "#/$defs/eventMap"
        },
        "ui": {
          "type": "object",
          "description": "Canvas bookkeeping, ignored by the engine. `x`/`y` place the state; `transitions` places the pill drawn for each of its transitions, keyed `\"<event>|<index>\"` -- the event and the transition's position within it, which is what identifies a transition. Free-form: anything here is presentation, and a chart with no `ui` at all lays itself out.",
          "properties": {
            "x": {
              "type": "number"
            },
            "y": {
              "type": "number"
            },
            "transitions": {
              "type": "object",
              "description": "Pill positions, keyed \"<event>|<index>\".",
              "additionalProperties": {
                "type": "object",
                "properties": {
                  "x": {
                    "type": "number"
                  },
                  "y": {
                    "type": "number"
                  }
                }
              }
            }
          }
        }
      },
      "allOf": [
        {
          "if": {
            "properties": {
              "type": {
                "const": "request"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "oneOf": [
              {
                "required": [
                  "operation"
                ]
              },
              {
                "required": [
                  "requests"
                ]
              }
            ],
            "properties": {
              "operation": {
                "type": "string",
                "description": "A Semantic.Registry id, e.g. customer.query -- or a template that renders to one, such as ${input.find.operation}, checked when the state is entered."
              },
              "params": {
                "$ref": "#/$defs/template"
              },
              "qbxml_version": {
                "type": "string",
                "default": "16.0"
              },
              "settle": {
                "type": "boolean",
                "default": true,
                "description": "Whether a request QuickBooks never answered is settled before the state raises anything: the engine finds out whether it was applied (a list add by its full name, a transaction add by the external_guid it stamps on it, an update by reading the record back, a delete by its id) and raises success as if the answer had arrived, re-sends, or raises error with type unsettled and the candidates when only the app can tell. false raises error with type no_response at once, as a query does when re-sending fails. Either way a no_response carries response.error.reason, why it went unanswered (timed_out or connector_error: it was sent, so QuickBooks may have applied it; rejected: QuickBooks could not read it; withdrawn: the app withdrew it before it was sent; page_expired: a later page never fetched; too_large: QuickBooks ran it, but its answer was over QuBe Sync's size limit, so a query is not re-sent and a write is settled as a timed_out one is), and, for an add, response.error.external_guid, the GUID it was sent with, so a chart that does its own looking can recognise the record. An add is stamped with a GUID whether settling is on or off."
              },
     "on_conflict": {
       "enum": ["ask", "overwrite", "fail"],
       "default": "ask",
       "description": "For an update: what happens when QuickBooks says the record changed after it was read (a stale edit sequence, 3200). ask (the default) pauses the run with a conflict prompt carrying the diff, which the app answers with overwrite (optionally with different params) or keep; overwrite re-sends with the current edit sequence without asking; fail raises error 3200 with the diff under response.error.conflict for the chart to handle. An update may leave edit_sequence out: the engine reads the record first and fills it in, and that read is the baseline the diff is judged against."
     },
     "paginate": {
                "type": "boolean",
                "description": "Page through a query's results: the state raises `page` once per page (response.data that page's records, response.page its number from 1, response.more whether more follow), then `success` once every page is in (response.data the page set, response.count and response.pages its size). Only on a single `operation` that is a query (a create, update, delete or other operation has no results to page through, and one named by reference that renders to such fails the run before it is sent); `params` may not also set `iterator` or `max_returned`. A query QuickBooks does not iterate (the short lists such as account.query, the deleted-records queries, the company, preferences and host queries, the reports) is sent as it is and answers whole, which arrives as page 1 with `more` false, so a chart written for pages works over any query. Each handled page costs about two of a run's 500 transitions (fault transition_limit past them), so one run pages about 250 times: raise page_size, or split the job over runs."
              },
              "page_size": {
                "type": "integer",
                "minimum": 1,
                "maximum": 200,
                "default": 100,
                "description": "Records per page, with `paginate`."
              },
              "requests": {
                "type": "array",
                "minItems": 1,
                "items": {
                  "type": "object",
                  "required": [
                    "operation"
                  ],
                  "properties": {
                    "operation": {
                      "type": "string"
                    },
                    "params": {
                      "$ref": "#/$defs/template"
                    }
                  }
                }
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "wait"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "prompt"
            ],
            "properties": {
              "prompt": {
                "$ref": "#/$defs/prompt"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "workflow"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "workflow"
            ],
            "properties": {
              "workflow": {
                "type": "string",
                "pattern": "^[a-z][a-z0-9_]{0,63}$",
                "description": "The key of another workflow of the same app to run as this step."
              },
              "input": {
                "$ref": "#/$defs/template",
                "description": "Rendered against this run's context and passed to the child as its input. With `each`, rendered once per element, with each.<as>, each.index and each.count bound."
              },
              "each": {
                "type": [
                  "string",
                  "array"
                ],
                "description": "Run the child once per element of this list, one at a time and in order: a template that renders to a list, such as ${input.lines}. The state then raises success with response.items, one entry per element in order: {index, name, outcome, and the element's output keys (record, ...) or error}, and response.counts: {total, failed, and one count per outcome}. response.data (the outputs alone), response.outcomes and response.errors are the same in parallel lists. An empty list raises success at once with response.items []. At most 200 elements."
              },
              "as": {
                "$ref": "#/$defs/identifier",
                "default": "item",
                "not": {
                  "enum": [
                    "index",
                    "count"
                  ]
                },
                "description": "The name the current element is bound to under each: each.line when as is line."
              },
              "on_item_error": {
                "enum": [
                  "stop",
                  "continue"
                ],
                "default": "stop",
                "description": "stop: the first child that fails raises error, with the elements so far in response.items. continue: a failed element is an entry of response.items with its error (and null in response.data), and the state still raises success; response.counts.failed says how many failed."
              },
              "item_name": {
                "type": "string",
                "description": "What names each element in response.items, rendered with each as the input is: ${each.record.add.name}. Without it, an element is named by its output's record (full_name, else name), and not at all when it has none."
              },
              "stop_on": {
                "type": "array",
                "minItems": 1,
                "uniqueItems": true,
                "items": {
                  "$ref": "#/$defs/identifier"
                },
                "description": "Endings of the called workflow, such as [\"cancelled\"], that end the loop: the first element whose run ends in one of them is the last, and the elements after it never start -- no requests, no questions. The state then raises success with the outputs up to and including that element in response.data, their endings in response.outcomes, and response.stopped: {index, outcome}, which element ended the loop and how (absent when every element ran). Not a failure, which on_item_error decides; each name must be an outcome the called workflow declares, or completed."
              }
            },
            "not": {
              "anyOf": [
                {
                  "required": [
                    "always"
                  ]
                },
                {
                  "required": [
                    "params"
                  ]
                },
                {
                  "required": [
                    "operation"
                  ]
                },
                {
                  "required": [
                    "prompt"
                  ]
                }
              ]
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "transform"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "assign",
              "always"
            ],
            "properties": {
              "assign": {
                "$ref": "#/$defs/assignMap",
                "minProperties": 1
              },
              "always": {
                "$ref": "#/$defs/transitionList"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "choice"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "always"
            ],
            "not": {
              "anyOf": [
                {
                  "required": [
                    "assign"
                  ]
                },
                {
                  "required": [
                    "entry"
                  ]
                },
                {
                  "required": [
                    "exit"
                  ]
                }
              ]
            },
            "properties": {
              "always": {
                "$ref": "#/$defs/transitionList"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "compound"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "initial",
              "states"
            ],
            "properties": {
              "initial": {
                "$ref": "#/$defs/identifier"
              },
              "states": {
                "$ref": "#/$defs/statesMap"
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "final"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "not": {
              "anyOf": [
                {
                  "required": [
                    "on"
                  ]
                },
                {
                  "required": [
                    "always"
                  ]
                }
              ]
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "notify"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "name",
              "data"
            ],
            "properties": {
              "name": {
                "$ref": "#/$defs/identifier",
                "description": "What the app routes on, such as customers_page: the webhook's `name`."
              },
              "data": {
                "$ref": "#/$defs/template",
                "description": "Any JSON, rendered as the state is entered and sent to the app as a workflow_run.notification webhook, to the webhook_url the run was started with (a run of a workflow that can send one is refused without it: 422 webhook_url_required). `response` here is the response of the event that entered the state -- on a paginated query's `page`, that page -- so `${response.data}` sends the page's records; a page set (a paginating query's `success`) cannot be sent. At most 4 MB once encoded. The run waits for the app's 2xx: then the state raises success with response.delivery_id (the same on every retry), response.seq (1, 2, ... in send order for the run) and response.attempts. Delivery is retried for about an hour (10 attempts); if none succeeds, or the data is over 4 MB, it raises error with response.error.type not_delivered or too_large."
              }
            },
            "not": {
              "anyOf": [
                {
                  "required": [
                    "url"
                  ]
                },
                {
                  "required": [
                    "webhook_url"
                  ]
                },
                {
                  "required": [
                    "operation"
                  ]
                },
                {
                  "required": [
                    "params"
                  ]
                },
                {
                  "required": [
                    "prompt"
                  ]
                },
                {
                  "required": [
                    "workflow"
                  ]
                },
                {
                  "required": [
                    "input"
                  ]
                },
                {
                  "required": [
                    "each"
                  ]
                },
                {
                  "required": [
                    "always"
                  ]
                }
              ]
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "const": "match"
              }
            },
            "required": [
              "type"
            ]
          },
          "then": {
            "required": [
              "kind",
              "name"
            ],
            "properties": {
              "kind": {
                "$ref": "#/$defs/template",
                "description": "The list to look in: customer, vendor, employee, other_name, entity (those four together, one name space), item (every item type), account, class, or another reference list a transaction names (standard_terms, date_driven_terms, sales_tax_code, payment_method, ship_method, price_level, customer_type, vendor_type, job_type, sales_rep, customer_msg); or a template that renders to one, such as ${input.kind}."
              },
              "name": {
                "$ref": "#/$defs/template",
                "description": "The record's own name, without its parent's: a template such as ${input.name}. At most 255 characters once rendered."
              },
              "parent": {
                "$ref": "#/$defs/template",
                "description": "Optional: the parent's full name or ListID, for a job (kind customer) or a sub-item (kind item), or another kind whose records have parents. With one, name has no colon. A template that renders to nothing, or a blank one, is left out."
              },
              "fields": {
                "$ref": "#/$defs/template",
                "description": "Optional, for customer, vendor, employee, other_name and entity: an object of company_name, email, phone, account_number, city and postal_code (each a template; an employee has no company_name) to match on as well as the name. One that renders to nothing is left out."
              },
              "exact_only": {
                "$ref": "#/$defs/template",
                "description": "Optional, true or false (or a template): with true the answer is exact or none."
              },
              "min_score": {
                "$ref": "#/$defs/template",
                "description": "Optional: a number from 0.3 to 1.0 (or a template), this match's candidate threshold in place of 0.44. Not with exact_only."
              },
              "refresh": {
                "$ref": "#/$defs/template",
                "description": "Optional, default true: refresh the connection's name index from QuickBooks first, the run waiting until it is in -- unless the last refresh finished less than a minute ago, when it matches at once, so the matches of one burst share a refresh (one already on its way is waited on). false matches the index as it stands (response.data.index.as_of says how current)."
              }
            },
            "not": {
              "anyOf": [
                {
                  "required": [
                    "operation"
                  ]
                },
                {
                  "required": [
                    "requests"
                  ]
                },
                {
                  "required": [
                    "params"
                  ]
                },
                {
                  "required": [
                    "prompt"
                  ]
                },
                {
                  "required": [
                    "workflow"
                  ]
                },
                {
                  "required": [
                    "input"
                  ]
                },
                {
                  "required": [
                    "data"
                  ]
                },
                {
                  "required": [
                    "url"
                  ]
                },
                {
                  "required": [
                    "webhook_url"
                  ]
                },
                {
                  "required": [
                    "always"
                  ]
                },
                {
                  "required": [
                    "paginate"
                  ]
                },
                {
                  "required": [
                    "page_size"
                  ]
                },
                {
                  "required": [
                    "settle"
                  ]
                },
                {
                  "required": [
                    "on_conflict"
                  ]
                },
                {
                  "required": [
                    "qbxml_version"
                  ]
                },
                {
                  "required": [
                    "each"
                  ]
                }
              ]
            }
          }
        }
      ]
    },
    "eventMap": {
      "type": "object",
      "description": "Event name -> transitions. Request states raise success/error, compounds raise done, wait states raise the chosen option id, notify states raise success/error, match states raise success (response.data is the answer: match is exact, strong, candidates or none; record; candidates; candidates_total; candidates_total_complete; index) or error (its fields refused once rendered: invalid_match; or QuickBooks failing the fallback queries on a connection without a name index).",
      "propertyNames": {
        "allOf": [
          {
            "$ref": "#/$defs/identifier"
          },
          {
            "not": {
              "const": "always"
            }
          }
        ]
      },
      "additionalProperties": {
        "$ref": "#/$defs/transitionList"
      }
    },
    "transitionList": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "#/$defs/transition"
      }
    },
    "transition": {
      "type": "object",
      "required": [
        "target"
      ],
      "additionalProperties": false,
      "properties": {
        "if": {
          "$ref": "#/$defs/condition"
        },
        "target": {
          "type": "string",
          "description": "completed, failed, a sibling key (searched upward), or an absolute dotted path."
        },
        "assign": {
          "$ref": "#/$defs/assignMap"
        },
        "description": {
          "type": "string"
        }
      }
    },
    "condition": {
      "type": "object",
      "oneOf": [
        {
          "required": [
            "path",
            "op"
          ],
          "properties": {
            "path": {
              "type": "string",
              "minLength": 1
            },
            "op": {
              "enum": [
                "present",
                "absent",
                "eq",
                "neq",
                "gt",
                "gte",
                "lt",
                "lte",
                "contains",
                "starts_with",
                "in"
              ]
            },
            "value": {}
          },
          "additionalProperties": false
        },
        {
          "required": [
            "all"
          ],
          "properties": {
            "all": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/$defs/condition"
              }
            }
          },
          "additionalProperties": false
        },
        {
          "required": [
            "any"
          ],
          "properties": {
            "any": {
              "type": "array",
              "minItems": 1,
              "items": {
                "$ref": "#/$defs/condition"
              }
            }
          },
          "additionalProperties": false
        },
        {
          "required": [
            "not"
          ],
          "properties": {
            "not": {
              "$ref": "#/$defs/condition"
            }
          },
          "additionalProperties": false
        }
      ]
    },
    "assignMap": {
      "type": "object",
      "description": "Variable name -> template. Every value is rendered against the same context snapshot, then merged into vars at once.",
      "propertyNames": {
        "$ref": "#/$defs/identifier"
      },
      "additionalProperties": {
        "$ref": "#/$defs/template"
      }
    },
    "template": {
      "description": "Any JSON value. Strings may hold ${...} references; a map may hold the reserved \"$from\" key, whose rendered map the rest of the map is deep-merged onto. A map holding \"$map\" is a list built from another: {\"$map\": \"${vars.items}\", \"as\": \"item\", \"template\": ...} renders template once per element, with the element at each.<as>, its position at each.index and the length at each.count. With \"key\" (a template per element), it is an object instead: each element's template under the key or keys it renders.\n\n{\"$add\": [...]} sums its operands and {\"$default\": [...]} is the first that renders to something. {\"$merge\": [a, b, ...]} deep-merges each object onto the ones before it, as \"$from\" does (objects merge key by key; lists and scalars replace; an operand that renders to nothing is skipped). {\"$find\": \"${vars.items}\", \"where\": condition} is the first element the condition holds for (at each.<as>), or nothing.\n\n{\"$refs\": \"${input.params}\", \"operation\": \"invoice.create\"} lists an add's references, or with \"list_ids\" puts their ListIDs back. {\"$read\": id, \"operation\": an add} reads that record whole. {\"$kind_name\": \"${input.kind}\"} is a kind, or an operation's, as a person reads it (Customer, Service item, Invoice for invoice.create), for a question's details. No other $-prefixed key is allowed.",
      "if": {
        "type": "object"
      },
      "then": {
        "properties": {
          "$from": {
            "type": "string"
          },
          "$map": {
            "type": "string",
            "description": "A template that renders to a list. With \"template\" (required) and \"as\" (default item): the list of the template rendered once per element, the element at each.<as>, each.index and each.count. With \"key\" too (a template rendered per element, such as ${each.ref.paths}, to a string or a list of strings): an object, each element's rendered template under its key or keys. Only $map, as, template and key."
          },
          "$add": {
            "type": "array",
            "minItems": 1,
            "description": "The sum of its operands: numbers, or templates that render to numbers; nothing counts as 0."
          },
          "$default": {
            "type": "array",
            "minItems": 1,
            "description": "The first of its candidates that renders to something other than nothing or an empty string."
          },
          "$merge": {
            "type": "array",
            "minItems": 1,
            "description": "Objects, or templates that render to objects, each deep-merged onto the ones before it: objects merge key by key, lists and scalars replace. An operand that renders to nothing is skipped. Alone in its object."
          },
          "$find": {
            "type": "string",
            "description": "A template that renders to a list. With \"where\" (a condition, required) and \"as\" (default item): the first element for which the condition holds, the element at each.<as>, each.index and each.count; nothing when none does. Only $find, as and where."
          },
          "$refs": {
            "type": [
              "string",
              "object"
            ],
            "description": "An add's params (an object, or a template for one). With \"operation\" (the add's operation id, or a template; required): the distinct references the params make, in the order they first appear -- every *_ref field the operation has, its kind derived from the field's name (customer_ref is customer, ar_account_ref account, item_group_ref item_group), one entry per kind and full name with every path it appears at: {kind, field, full_name, name, parent, list_id, paths}. A kind with no full-name lookup (template) is left out.\n\nWith \"adds\" (a list of {kind, add, fields, accept}, as ensure takes them) and \"rules\" (an object of kind to ensure, create or must_exist; ensure by default), each also has \"rule\", \"ensure\": {kind, add}, the add from adds that makes it, one of its name alone under create, or none, \"pick\", true when there is no add, and \"fields\" and \"accept\" from its entry in adds, for resolve.\n\nWith \"found\" (the response of a for-each over the references: its data and outcomes, one per reference in order), each also has \"outcome\", \"how\" and \"record\" from its element (null for one the loop never reached); with \"made\" too (the response of a for-each over the ones found answered not_found), those take its outcome and record. \"missing\": true keeps the references whose outcome is still not_found.\n\nWith \"list_ids\" instead (one per reference, in that order), it is the params, every reference replaced by {\"list_id\": ...}. Only $refs, operation, adds, rules, found, made, missing and list_ids."
          },
          "$read": {
            "type": "string",
            "description": "A record's id, or a template for it. With \"operation\" (an add's operation id, or a template; required): {\"operation\", \"params\"}, the query that reads the record that add makes, whole, by that id -- for a transaction add its type's query by txn_id with the flag that asks for its lines (include_line_items, or a build assembly's include_component_line_items), for a list add its type's query by list_id. A request state sends it with \"operation\": \"${vars.read.operation}\" and \"params\": {\"$from\": \"${vars.read.params}\"}. Only $read and operation."
          },
          "$kind_name": {
            "type": "string",
            "description": "A kind or an operation id, or a template for one (customer, item_service, invoice.create, ${input.kind}): its name as a person reads it -- Customer, Service item, Sales tax code, Invoice -- or nothing for anything but a non-empty string. For a question's details. Only $kind_name."
          }
        },
        "propertyNames": {
          "not": {
            "pattern": "^\\$(?!(from|map|add|default|merge|find|refs|read|kind_name)$)"
          }
        }
      }
    },
    "prompt": {
      "type": "object",
      "required": [
        "message",
        "options"
      ],
      "properties": {
        "message": {
          "type": "string"
        },
        "data": {
          "$ref": "#/$defs/template"
        },
        "details": {
          "type": "array",
          "maxItems": 20,
          "description": "What the question is about, as label and value rows a person reads above the choices: the name and kind, a transaction's number, the operation. Each label and value is a template rendered when the run asks, to a string (a number as its text, a list as its parts joined with ' · '); a row whose value renders to nothing is left out.",
          "items": {
            "type": "object",
            "required": [
              "label",
              "value"
            ],
            "additionalProperties": false,
            "properties": {
              "label": {
                "$ref": "#/$defs/template"
              },
              "value": {
                "$ref": "#/$defs/template"
              }
            }
          }
        },
        "options": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "id",
              "label"
            ],
            "properties": {
              "id": {
                "allOf": [
                  {
                    "$ref": "#/$defs/identifier"
                  },
                  {
                    "not": {
                      "enum": [
                        "success",
                        "error",
                        "done",
                        "always"
                      ]
                    }
                  }
                ]
              },
              "label": {
                "type": "string"
              },
              "description": {
                "type": "string"
              },
              "fields": {
                "type": "object",
                "propertyNames": {
                  "$ref": "#/$defs/identifier"
                },
                "additionalProperties": {
                  "type": "object",
                  "required": [
                    "type"
                  ],
                  "properties": {
                    "type": {
                      "description": "string, number, boolean, object or array, as an input declares them; or rows: the same columns asked of each row of a list (rows and columns), answered as an object keyed by each row's key (docs/missing-records-question.md).",
                      "enum": [
                        "string",
                        "number",
                        "boolean",
                        "object",
                        "array",
                        "rows"
                      ]
                    },
                    "required": {
                      "type": "boolean"
                    },
                    "enum": {
                      "$ref": "#/$defs/promptEnum"
                    },
                    "rows": {
                      "type": "object",
                      "description": "For a field of type rows: one row per element of from, each rendered with the element at item.",
                      "required": [
                        "from",
                        "key",
                        "label"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "from": {
                          "type": "string",
                          "description": "A template that renders to a list, such as ${vars.asking}. At most 100 rows."
                        },
                        "key": {
                          "$ref": "#/$defs/template",
                          "description": "The row's key, unique among the rows: the answer is keyed by it."
                        },
                        "label": {
                          "$ref": "#/$defs/template",
                          "description": "What the row says, such as ${item.full_name}."
                        },
                        "detail": {
                          "$ref": "#/$defs/template",
                          "description": "A short second line, such as the record's kind."
                        },
                        "columns": {
                          "$ref": "#/$defs/template",
                          "description": "The names of the columns this row asks, such as ${item.ask.columns}; left out, every column."
                        },
                        "values": {
                          "$ref": "#/$defs/template",
                          "description": "What the row already has for columns it doesn't ask, an object: a column's when reads them too, and the answer carries them."
                        }
                      }
                    },
                    "columns": {
                      "type": "array",
                      "minItems": 1,
                      "description": "For a field of type rows: what each row is asked, in order. Every row shares them, so an app's screen can set one column on many rows at once.",
                      "items": {
                        "type": "object",
                        "required": [
                          "name",
                          "type"
                        ],
                        "additionalProperties": false,
                        "properties": {
                          "name": {
                            "$ref": "#/$defs/identifier"
                          },
                          "type": {
                            "enum": [
                              "string",
                              "number",
                              "boolean"
                            ]
                          },
                          "required": {
                            "type": "boolean",
                            "description": "Every row the column applies to (its columns name it, and its when holds) must answer it."
                          },
                          "label": {
                            "type": "string"
                          },
                          "enum": {
                            "$ref": "#/$defs/promptEnum"
                          },
                          "record": {
                            "type": "object",
                            "description": "A search column: a row's value comes from the run's search (links.search with field=<field>.<column> and row=<key>). Its type is string: a search answers a ListID.",
                            "required": [
                              "kind"
                            ],
                            "additionalProperties": false,
                            "properties": {
                              "kind": {
                                "type": "string",
                                "description": "The list to search, or a template for it over item, the row's element: ${item.kind}."
                              }
                            }
                          },
                          "when": {
                            "type": "object",
                            "description": "The values of the row's other columns this one applies under, such as {\"action\": [\"create\"], \"item_type\": [\"item_inventory\"]}. A column whose when doesn't hold isn't asked, and an answer to it is dropped.",
                            "additionalProperties": {
                              "type": "array",
                              "minItems": 1
                            }
                          }
                        }
                      }
                    },
                    "label": {
                      "type": "string"
                    },
                    "choose": {
                      "type": "object",
                      "description": "One choice per element of from, this field already filled: the choice's id is the option's and its position (use:1, use:2, ...), and the app answers it with {\"choice\": \"use:1\"}, never the value itself. value, label and detail are templates rendered for each element, which is at item (${item.list_id}). At most 25 are offered, and 26 choices in all. At most one field of an option has choose.",
                      "required": [
                        "from",
                        "value",
                        "label"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "from": {
                          "type": "string",
                          "description": "A template that renders to a list, such as ${vars.found.candidates}."
                        },
                        "value": {
                          "$ref": "#/$defs/template",
                          "description": "What the field is filled with for the element, such as ${item.list_id}."
                        },
                        "label": {
                          "$ref": "#/$defs/template",
                          "description": "What the choice says, such as ${item.full_name}."
                        },
                        "detail": {
                          "$ref": "#/$defs/template",
                          "description": "A short second line, such as the record's list or city: a list renders as its parts joined with ' · '."
                        }
                      }
                    },
                    "record": {
                      "type": "object",
                      "description": "A search choice: the option once more, this field of type record, filled from the run's search (links.search) of the connection's name index. Only on a realtime or simulated connection, which has one; on a standard one the choice isn't offered, so give the question another way to answer too. The field's type is string: a search answers a ListID.",
                      "required": [
                        "kind"
                      ],
                      "additionalProperties": false,
                      "properties": {
                        "kind": {
                          "type": "string",
                          "description": "The list to search, or a template for it: customer, vendor, entity, item, an item type such as item_service, account, class, ... (a kind a match takes)."
                        },
                        "label": {
                          "type": "string",
                          "description": "What the search choice says, such as Another customer…"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "promptEnum": {
      "type": "array",
      "minItems": 1,
      "description": "The values a string or number field may take, each with what a person reads for it: the choice's field carries them, and an answer outside them is refused.",
      "items": {
        "type": "object",
        "required": [
          "value"
        ],
        "additionalProperties": false,
        "properties": {
          "value": {
            "type": [
              "string",
              "number"
            ]
          },
          "label": {
            "type": "string"
          }
        }
      }
    },
    "inputDeclaration": {
      "type": "object",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "enum": [
            "string",
            "number",
            "boolean",
            "object",
            "array",
            "operation"
          ]
        },
        "required": {
          "type": "boolean"
        },
        "description": {
          "type": "string"
        },
        "example": {
          "description": "An example value, in the input's own JSON type: a string, a number, an object, or for a list the whole list. It is what the usage contract's start body and the dashboard's Run drawer show. An operation input needs none: its example is built from the operation. Nor does a list of objects a workflow state runs through (each: ${input.<name>}): its example is one element of what that workflow takes."
        },
        "operation": {
          "type": "string",
          "description": "The operation this input is a body for. Left out, the input takes a pair -- {\"operation\": \"customer.query\", \"params\": {...}} -- validated against whichever operation the run names, which a request state sends with \"operation\": \"${input.<name>.operation}\" and \"params\": {\"$from\": \"${input.<name>.params}\"}."
        },
        "only": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "list": {
          "type": "boolean",
          "default": false,
          "description": "A list of what the rest of the declaration describes: with type operation, a list of that operation's bodies. The run input then takes an array, and each element is validated on its own."
        },
        "schema": {
          "$ref": "#/$defs/inputSchema",
          "description": "The shape of one value of this input (of each element, for a list), checked when a run starts and against the example: a subset of JSON Schema (type, properties, required, additionalProperties, items, enum, description, body_of). Allowed on an object or array input, or a list input that isn't an operation. Its top-level type defaults to the input's type. The reference picker and lint read its fields, so ${input.<name>.<field>} naming a field it lacks is a warning."
        },
        "enum": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "string"
          },
          "description": "On a string input: the values a run may give it, checked when the run starts (add_transaction's operation lists the transaction adds). An object or array input says its values with schema."
        },
        "body_of": {
          "$ref": "#/$defs/inputSchema/properties/body_of",
          "description": "On an object input that isn't a list: it is the body of the QuickBooks operation another input names, validated against that operation's params when the run starts, so a field the operation doesn't take is a 422 at the start (input.params: unknown parameter: \"customer_rf\"). {\"operation\": \"<input>\"} when that input holds an operation id (add_transaction's params, named by operation); {\"kind\": \"<input>\", \"action\": \"create\" | \"update\" | \"query\"} when it holds a kind (ensure's add, named by kind: <kind>.create). The input it names is a string input, not a list. Inside a schema, body_of goes on a property and names a property beside it. The typed starts the libraries generate (GET /api/v2/workflows/types) read it."
        }
      },
      "if": {
        "properties": {
          "type": {
            "const": "operation"
          }
        },
        "required": [
          "type"
        ]
      },
      "then": {
        "not": {
          "required": [
            "schema"
          ]
        }
      },
      "else": {
        "not": {
          "required": [
            "operation"
          ]
        }
      }
    },
    "inputSchema": {
      "type": "object",
      "description": "A JSON Schema subset describing one value of this input: type, properties, required, additionalProperties, items, enum, description, body_of.",
      "properties": {
        "type": {
          "description": "string, number, integer, boolean, object, array or null, or a list of them ([\"string\", \"null\"]). At the top it defaults to the input's own type.",
          "anyOf": [
            {
              "enum": [
                "string",
                "number",
                "integer",
                "boolean",
                "object",
                "array",
                "null"
              ]
            },
            {
              "type": "array",
              "items": {
                "enum": [
                  "string",
                  "number",
                  "integer",
                  "boolean",
                  "object",
                  "array",
                  "null"
                ]
              },
              "minItems": 1
            }
          ]
        },
        "properties": {
          "type": "object",
          "description": "An object's fields, each a schema.",
          "additionalProperties": {
            "$ref": "#/$defs/inputSchema"
          }
        },
        "required": {
          "type": "array",
          "description": "The fields an object must have.",
          "items": {
            "type": "string"
          }
        },
        "additionalProperties": {
          "description": "false refuses fields that properties doesn't name; true (the default) allows them; a schema allows them when they match it.",
          "anyOf": [
            {
              "type": "boolean"
            },
            {
              "$ref": "#/$defs/inputSchema"
            }
          ]
        },
        "items": {
          "$ref": "#/$defs/inputSchema",
          "description": "Every element of an array."
        },
        "enum": {
          "type": "array",
          "minItems": 1,
          "description": "The values allowed."
        },
        "description": {
          "type": "string",
          "description": "What it is, shown in the usage contract's fields table."
        },
        "body_of": {
          "description": "On an object: it is the body of the QuickBooks operation a sibling field names, validated against that operation's params when the run starts. {\"operation\": \"<sibling>\"} when the sibling holds an operation id (invoice.create); {\"kind\": \"<sibling>\", \"action\": \"create\"} when it holds a kind (customer), for the operation <kind>.<action>.",
          "oneOf": [
            {
              "type": "object",
              "properties": {
                "operation": {
                  "type": "string"
                }
              },
              "required": [
                "operation"
              ],
              "additionalProperties": false
            },
            {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string"
                },
                "action": {
                  "enum": [
                    "create",
                    "update",
                    "query"
                  ]
                }
              },
              "required": [
                "kind",
                "action"
              ],
              "additionalProperties": false
            }
          ]
        }
      },
      "additionalProperties": false
    }
  }
}
