QuestionScript

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/buildbatch-co-uk/json-schema/buildbatch-co-uk-question-script-schema.json",
  "title": "QuestionScript",
  "x-generated": "2026-11-03",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/buildbatch-co-uk-openapi.json#/components/schemas/QuestionScript",
  "type": "object",
  "required": [
    "api",
    "document",
    "v",
    "instructions",
    "questions"
  ],
  "properties": {
    "api": {
      "type": "string",
      "const": "buildbatch-assistant"
    },
    "document": {
      "type": "string",
      "const": "question-script"
    },
    "v": {
      "type": "integer",
      "const": 1
    },
    "instructions": {
      "type": "object",
      "description": "Rules for the assistant: what to ask, what never to do, and what to tell the person afterwards."
    },
    "questions": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Question"
      }
    },
    "productFigures": {
      "type": "array",
      "description": "Optional figures a person may read off a tin, pack, roll or box.",
      "items": {
        "type": "object"
      }
    },
    "typicalRooms": {
      "type": "array",
      "description": "Offer only if the person does not know their room's size.",
      "items": {
        "type": "object"
      }
    },
    "typicalOpenings": {
      "type": "array",
      "description": "The door and window names a call may use.",
      "items": {
        "type": "object"
      }
    }
  },
  "$defs": {
    "Question": {
      "type": "object",
      "required": [
        "id",
        "ask",
        "type",
        "required",
        "fills"
      ],
      "properties": {
        "id": {
          "type": "string"
        },
        "ask": {
          "type": "string",
          "description": "The wording to use."
        },
        "type": {
          "type": "string",
          "enum": [
            "choice",
            "yes-no",
            "length",
            "lengths",
            "openings",
            "corners"
          ]
        },
        "required": {
          "type": "boolean",
          "description": "True: the planner refuses without it whenever the question applies."
        },
        "requiredWhen": {
          "type": "object",
          "description": "Another condition under which it is required."
        },
        "when": {
          "type": [
            "object",
            "null"
          ],
          "description": "When to ask: null is always; otherwise every key must hold (job is one of the values listed)."
        },
        "whenText": {
          "type": "string"
        },
        "fills": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The /plan.json parameters the answer fills."
        },
        "choices": {
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "value": {
                "type": "string"
              },
              "label": {
                "type": "string"
              },
              "sets": {
                "type": "object",
                "additionalProperties": {
                  "type": "string"
                },
                "description": "The parameters to send for this answer."
              }
            }
          }
        },
        "ifUnknown": {
          "type": "string",
          "description": "What to do if the person does not know."
        },
        "default": {
          "type": "string",
          "description": "What the planner assumes if the parameter is left out."
        },
        "notes": {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  }
}