{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://rangka-os.github.io/rangka-os/schema/0.5/screen.json",
  "title": "Rangka work screen",
  "description": "A work screen a module ships in screens/<name>.rk (contract 0030): one staff job on a phone or tablet, rendered by the web app from one of seven types. It writes only through the record API, so permissions, row scope, rules, flows and approvals apply as for a form.",
  "type": "object",
  "required": [
    "name",
    "type",
    "label",
    "roles"
  ],
  "additionalProperties": false,
  "properties": {
    "$schema": {
      "type": "string"
    },
    "name": {
      "$ref": "model.json#/$defs/name"
    },
    "type": {
      "enum": [
        "counter",
        "queue",
        "roll",
        "route",
        "handover",
        "clock",
        "entry"
      ]
    },
    "label": {
      "$ref": "model.json#/$defs/label"
    },
    "description": {
      "$ref": "model.json#/$defs/label"
    },
    "icon": {
      "type": "string"
    },
    "roles": {
      "type": "array",
      "minItems": 1,
      "items": {
        "$ref": "model.json#/$defs/name"
      },
      "description": "Roles that may open the screen (the owner always may)"
    },
    "device": {
      "enum": [
        "phone",
        "tablet",
        "any"
      ],
      "description": "Layout hint, never a lock"
    },
    "needs": {
      "type": "array",
      "items": {
        "enum": [
          "scan",
          "photo",
          "location",
          "signature",
          "print"
        ]
      },
      "description": "Device capabilities; the screen still opens without them, with a notice"
    },
    "offline": {
      "enum": [
        "none",
        "queue",
        "edge"
      ]
    },
    "if": {
      "type": "string",
      "description": "CEL over user (and org, tax); false hides the screen"
    },
    "entry": {
      "$ref": "#/$defs/entry"
    },
    "counter": {
      "$ref": "#/$defs/counter"
    },
    "queue": {
      "$ref": "#/$defs/queue"
    },
    "roll": {
      "$ref": "#/$defs/roll"
    },
    "route": {
      "$ref": "#/$defs/route"
    },
    "handover": {
      "$ref": "#/$defs/handover"
    },
    "clock": {
      "$ref": "#/$defs/clock"
    }
  },
  "$defs": {
    "block": {
      "type": "object",
      "description": "The slots of a type whose renderer is not built yet; its PR gives the block its own shape (contract 0030 §2)"
    },
    "set": {
      "type": "object",
      "description": "field: CEL over user, org, tax, today(), now() and the record the screen was opened for (stop, doc), evaluated by the kernel when the screen opens",
      "propertyNames": {
        "$ref": "model.json#/$defs/name"
      },
      "additionalProperties": {
        "type": "string"
      }
    },
    "entry": {
      "type": "object",
      "description": "A short phone form: fill, save, next (contract 0030 §2)",
      "required": [
        "model",
        "fields"
      ],
      "additionalProperties": false,
      "properties": {
        "model": {
          "$ref": "model.json#/$defs/name"
        },
        "fields": {
          "type": "array",
          "minItems": 1,
          "maxItems": 8,
          "items": {
            "$ref": "model.json#/$defs/name"
          }
        },
        "set": {
          "$ref": "#/$defs/set"
        },
        "submit": {
          "type": "boolean",
          "description": "Submit the record after saving it (the model must be submittable)"
        },
        "again": {
          "type": "boolean",
          "description": "After saving, open an empty form again (default true)"
        }
      }
    },
    "counter": {
      "type": "object",
      "description": "Sell or take payment at a counter: catalogue, cart, tender, receipt (contract 0030 §2)",
      "required": [
        "catalogue",
        "document"
      ],
      "additionalProperties": false,
      "properties": {
        "catalogue": {
          "type": "object",
          "required": [
            "model",
            "price"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "filter": {
              "type": "string",
              "description": "List filter (field names, CEL) over the catalogue model, with user"
            },
            "title": {
              "$ref": "model.json#/$defs/name"
            },
            "search": {
              "type": "array",
              "items": {
                "$ref": "model.json#/$defs/name"
              }
            },
            "group_by": {
              "$ref": "model.json#/$defs/name"
            },
            "price": {
              "$ref": "model.json#/$defs/name"
            },
            "barcode": {
              "$ref": "model.json#/$defs/name"
            },
            "image": {
              "$ref": "model.json#/$defs/name"
            },
            "available": {
              "description": "What is left to sell: a number field of the catalogue model (contract 0034), or a balance model read for the open session's outlet (contract 0039). The card shows 'Sisa N' at 5 or less and 'Habis' at 0 or less; it never blocks a sale",
              "oneOf": [
                {
                  "$ref": "model.json#/$defs/name"
                },
                {
                  "type": "object",
                  "required": [
                    "model",
                    "item",
                    "qty"
                  ],
                  "additionalProperties": false,
                  "properties": {
                    "model": {
                      "$ref": "model.json#/$defs/name",
                      "description": "The balance model (e.g. stock_balance)"
                    },
                    "item": {
                      "$ref": "model.json#/$defs/name",
                      "description": "Its link field to the catalogue model"
                    },
                    "qty": {
                      "$ref": "model.json#/$defs/name",
                      "description": "Its number field, summed per item"
                    },
                    "match": {
                      "type": "object",
                      "description": "Balance field: session field; only rows whose field equals the open session's value",
                      "additionalProperties": {
                        "$ref": "model.json#/$defs/name"
                      }
                    }
                  }
                }
              ]
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 2000,
              "description": "Rows loaded (default 500)"
            }
          }
        },
        "document": {
          "type": "object",
          "required": [
            "model",
            "lines",
            "line"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "lines": {
              "$ref": "model.json#/$defs/name"
            },
            "line": {
              "type": "object",
              "required": [
                "item",
                "qty"
              ],
              "additionalProperties": false,
              "properties": {
                "item": {
                  "$ref": "model.json#/$defs/name"
                },
                "qty": {
                  "$ref": "model.json#/$defs/name"
                },
                "price": {
                  "$ref": "model.json#/$defs/name"
                },
                "note": {
                  "$ref": "model.json#/$defs/name"
                }
              }
            },
            "set": {
              "$ref": "#/$defs/set"
            },
            "total": {
              "$ref": "model.json#/$defs/name",
              "description": "The document's total field (a number); the receipt panel shows the server's value"
            },
            "change": {
              "$ref": "model.json#/$defs/name",
              "description": "The document's change field (a number); the receipt panel shows the server's value"
            },
            "summary": {
              "type": "array",
              "maxItems": 8,
              "items": {
                "$ref": "model.json#/$defs/name"
              },
              "description": "Number fields of the document shown under the cart, in this order, as POST /api/v1/compute answers them; the last one is the total line (contract 0034)"
            }
          }
        },
        "payments": {
          "type": "object",
          "required": [
            "table",
            "method",
            "amount"
          ],
          "additionalProperties": false,
          "properties": {
            "table": {
              "$ref": "model.json#/$defs/name"
            },
            "method": {
              "$ref": "model.json#/$defs/name"
            },
            "amount": {
              "$ref": "model.json#/$defs/name"
            },
            "ref": {
              "$ref": "model.json#/$defs/name"
            },
            "methods": {
              "type": "array",
              "minItems": 1,
              "items": {
                "type": "string"
              }
            }
          }
        },
        "session": {
          "type": "object",
          "required": [
            "model",
            "link",
            "state"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "link": {
              "$ref": "model.json#/$defs/name"
            },
            "filter": {
              "type": "string",
              "description": "List filter for the caller's open session, e.g. cashier == user.email"
            },
            "state": {
              "type": "object",
              "required": [
                "field",
                "open"
              ],
              "additionalProperties": false,
              "properties": {
                "field": {
                  "$ref": "model.json#/$defs/name"
                },
                "open": {
                  "type": "string"
                },
                "closed": {
                  "type": "string"
                }
              }
            },
            "open": {
              "type": "array",
              "items": {
                "$ref": "model.json#/$defs/name"
              }
            },
            "set": {
              "$ref": "#/$defs/set"
            },
            "close": {
              "type": "object",
              "required": [
                "model",
                "link",
                "fields"
              ],
              "additionalProperties": false,
              "properties": {
                "model": {
                  "$ref": "model.json#/$defs/name"
                },
                "link": {
                  "$ref": "model.json#/$defs/name"
                },
                "fields": {
                  "type": "array",
                  "items": {
                    "$ref": "model.json#/$defs/name"
                  }
                },
                "set": {
                  "$ref": "#/$defs/set"
                }
              }
            },
            "blind": {
              "type": "boolean",
              "description": "The cashier counts cash without seeing the expected amount (default true)"
            }
          }
        },
        "hold": {
          "type": "boolean"
        },
        "customer": {
          "type": "object",
          "required": [
            "field"
          ],
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "model.json#/$defs/name"
            },
            "required": {
              "type": "boolean"
            }
          }
        },
        "print": {
          "$ref": "model.json#/$defs/name"
        },
        "submit": {
          "type": "boolean"
        }
      }
    },
    "queue": {
      "type": "object",
      "description": "Work through cards that change state: kitchen tickets, today's jobs (contract 0030 §2)",
      "required": [
        "source",
        "card",
        "steps"
      ],
      "additionalProperties": false,
      "properties": {
        "source": {
          "type": "object",
          "required": [
            "model"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "filter": {
              "type": "string",
              "description": "List filter (field names, CEL, with user and today())"
            },
            "sort": {
              "type": "string",
              "description": "List sort, e.g. created_at or -date"
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            }
          }
        },
        "card": {
          "type": "object",
          "required": [
            "title"
          ],
          "additionalProperties": false,
          "properties": {
            "title": {
              "$ref": "model.json#/$defs/name"
            },
            "subtitle": {
              "$ref": "model.json#/$defs/name"
            },
            "lines": {
              "$ref": "model.json#/$defs/name"
            },
            "line": {
              "type": "array",
              "items": {
                "$ref": "model.json#/$defs/name"
              }
            },
            "fields": {
              "type": "array",
              "items": {
                "$ref": "model.json#/$defs/name"
              }
            },
            "age_from": {
              "type": "string",
              "description": "A date or datetime field (or created_at, modified_at) the card's age counts from"
            }
          }
        },
        "steps": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "when",
              "label"
            ],
            "additionalProperties": false,
            "properties": {
              "when": {
                "type": "string",
                "description": "CEL over the card's record"
              },
              "label": {
                "$ref": "model.json#/$defs/label"
              },
              "action": {
                "type": "string",
                "description": "submit, or an action of the model"
              },
              "set": {
                "type": "object",
                "propertyNames": {
                  "$ref": "model.json#/$defs/name"
                },
                "additionalProperties": {
                  "type": [
                    "string",
                    "number",
                    "boolean"
                  ]
                },
                "description": "field: literal value"
              }
            }
          }
        },
        "columns": {
          "type": "object",
          "required": [
            "by"
          ],
          "additionalProperties": false,
          "properties": {
            "by": {
              "$ref": "model.json#/$defs/name"
            },
            "values": {
              "type": "array",
              "items": {
                "type": "string"
              }
            }
          }
        },
        "refresh": {
          "type": "integer",
          "minimum": 3,
          "maximum": 300,
          "description": "Seconds between refreshes (default 10)"
        }
      }
    },
    "roll": {
      "type": "object",
      "required": [
        "document",
        "rows"
      ],
      "additionalProperties": false,
      "properties": {
        "document": {
          "type": "object",
          "required": [
            "model"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "find": {
              "type": "string",
              "description": "List filter of the parent records offered (e.g. today's open drafts of the user); ?doc=<name> opens one directly"
            },
            "create": {
              "type": "boolean",
              "description": "Offer \"Mulai baru\": create a parent with set: (default false)"
            },
            "set": {
              "$ref": "#/$defs/set"
            },
            "title": {
              "$ref": "model.json#/$defs/name"
            },
            "subtitle": {
              "$ref": "model.json#/$defs/name"
            },
            "sort": {
              "type": "string"
            }
          },
          "description": "The parent record: picked among find:, opened by ?doc=, or created"
        },
        "rows": {
          "type": "object",
          "required": [
            "table",
            "label"
          ],
          "additionalProperties": false,
          "properties": {
            "table": {
              "$ref": "model.json#/$defs/name"
            },
            "label": {
              "$ref": "model.json#/$defs/name"
            },
            "note": {
              "$ref": "model.json#/$defs/name"
            },
            "qty": {
              "$ref": "model.json#/$defs/name"
            },
            "mark": {
              "type": "object",
              "required": [
                "field"
              ],
              "additionalProperties": false,
              "properties": {
                "field": {
                  "$ref": "model.json#/$defs/name"
                },
                "values": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "default": {
                  "type": "string"
                }
              },
              "description": "A select field of the row marked with one tap; rows start at default"
            }
          }
        },
        "add_by": {
          "enum": [
            "scan",
            "search",
            "none"
          ]
        },
        "scan": {
          "type": "object",
          "required": [
            "field"
          ],
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "model.json#/$defs/name"
            },
            "match": {
              "$ref": "model.json#/$defs/name"
            }
          },
          "description": "Adds a row by camera, scanner or search: field is the row's link filled, match the field of the linked model that holds the code (default its name)"
        },
        "submit": {
          "type": "boolean"
        }
      },
      "description": "One parent, many rows marked fast or added by scan: class attendance, stock count, receiving (contract 0030 §2)"
    },
    "handover": {
      "type": "object",
      "required": [
        "document",
        "rows"
      ],
      "additionalProperties": false,
      "properties": {
        "document": {
          "type": "object",
          "required": [
            "model"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "find": {
              "type": "string",
              "description": "List filter of the parent records offered (e.g. today's open drafts of the user); ?doc=<name> opens one directly"
            },
            "create": {
              "type": "boolean",
              "description": "Offer \"Mulai baru\": create a parent with set: (default false)"
            },
            "set": {
              "$ref": "#/$defs/set"
            },
            "title": {
              "$ref": "model.json#/$defs/name"
            },
            "subtitle": {
              "$ref": "model.json#/$defs/name"
            },
            "sort": {
              "type": "string"
            }
          },
          "description": "The parent record: picked among find:, opened by ?doc=, or created"
        },
        "rows": {
          "type": "object",
          "required": [
            "table",
            "unit"
          ],
          "additionalProperties": false,
          "properties": {
            "table": {
              "$ref": "model.json#/$defs/name"
            },
            "unit": {
              "$ref": "model.json#/$defs/name"
            },
            "condition": {
              "$ref": "model.json#/$defs/name"
            },
            "qty": {
              "$ref": "model.json#/$defs/name"
            },
            "note": {
              "$ref": "model.json#/$defs/name"
            }
          }
        },
        "scan": {
          "type": "object",
          "required": [],
          "additionalProperties": false,
          "properties": {
            "match": {
              "$ref": "model.json#/$defs/name"
            }
          },
          "description": "A scanned code adds the unit whose match field (default its name) holds it"
        },
        "photos": {
          "type": "object",
          "required": [
            "field"
          ],
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "model.json#/$defs/name"
            },
            "min": {
              "type": "integer",
              "minimum": 0,
              "maximum": 10
            }
          },
          "description": "field: an image field of the document (the first photo); every photo is an attachment of the document"
        },
        "signature": {
          "type": "object",
          "required": [
            "field"
          ],
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "model.json#/$defs/name"
            },
            "by": {
              "$ref": "model.json#/$defs/name"
            }
          },
          "description": "field: a signature field of the document; by: the field naming the signer"
        },
        "print": {
          "type": "string"
        },
        "submit": {
          "type": "boolean"
        }
      },
      "description": "Hand items over with proof: rental out/in, proof of delivery (contract 0030 §2)"
    },
    "clock": {
      "type": "object",
      "required": [
        "record",
        "in",
        "out"
      ],
      "additionalProperties": false,
      "properties": {
        "record": {
          "type": "object",
          "required": [
            "model"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "filter": {
              "type": "string",
              "description": "List filter (field names, CEL, with user and today())"
            },
            "set": {
              "$ref": "#/$defs/set"
            }
          }
        },
        "in": {
          "type": "object",
          "required": [
            "field"
          ],
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "model.json#/$defs/name"
            },
            "location": {
              "$ref": "model.json#/$defs/name"
            },
            "photo": {
              "$ref": "model.json#/$defs/name"
            }
          },
          "description": "field: a datetime field set at the press; location: a geo field; photo: an image field"
        },
        "out": {
          "type": "object",
          "required": [
            "field"
          ],
          "additionalProperties": false,
          "properties": {
            "field": {
              "$ref": "model.json#/$defs/name"
            },
            "location": {
              "$ref": "model.json#/$defs/name"
            },
            "photo": {
              "$ref": "model.json#/$defs/name"
            }
          },
          "description": "field: a datetime field set at the press; location: a geo field; photo: an image field"
        },
        "site": {
          "type": "object",
          "required": [
            "model",
            "link",
            "location",
            "radius_m"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "link": {
              "$ref": "model.json#/$defs/name"
            },
            "filter": {
              "type": "string",
              "description": "List filter (field names, CEL, with user and today())"
            },
            "title": {
              "$ref": "model.json#/$defs/name"
            },
            "location": {
              "$ref": "model.json#/$defs/name"
            },
            "radius_m": {
              "$ref": "model.json#/$defs/name"
            }
          },
          "description": "Where the user clocks: link is the record's link to the site model, location its geo field, radius_m its radius"
        },
        "reason": {
          "$ref": "model.json#/$defs/name"
        },
        "submit": {
          "type": "boolean",
          "description": "Submit the record after clock-out (default false)"
        }
      },
      "description": "Clock in and out at a site (contract 0030 §2)"
    },
    "route": {
      "type": "object",
      "required": [
        "stops",
        "actions"
      ],
      "additionalProperties": false,
      "properties": {
        "stops": {
          "type": "object",
          "required": [
            "model",
            "title"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "filter": {
              "type": "string",
              "description": "List filter (field names, CEL, with user and today())"
            },
            "sort": {
              "type": "string"
            },
            "limit": {
              "type": "integer",
              "minimum": 1,
              "maximum": 500
            },
            "title": {
              "$ref": "model.json#/$defs/name"
            },
            "subtitle": {
              "$ref": "model.json#/$defs/name"
            },
            "address": {
              "$ref": "model.json#/$defs/name"
            },
            "location": {
              "$ref": "model.json#/$defs/name"
            }
          }
        },
        "visit": {
          "type": "object",
          "required": [
            "model",
            "link"
          ],
          "additionalProperties": false,
          "properties": {
            "model": {
              "$ref": "model.json#/$defs/name"
            },
            "link": {
              "$ref": "model.json#/$defs/name"
            },
            "set": {
              "$ref": "#/$defs/set"
            },
            "location": {
              "$ref": "model.json#/$defs/name"
            },
            "photo": {
              "$ref": "model.json#/$defs/name"
            },
            "submit": {
              "type": "boolean"
            }
          },
          "description": "The check-in record made at a stop"
        },
        "actions": {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "label"
            ],
            "additionalProperties": false,
            "properties": {
              "label": {
                "$ref": "model.json#/$defs/label"
              },
              "screen": {
                "$ref": "model.json#/$defs/name"
              },
              "create": {
                "$ref": "model.json#/$defs/name"
              },
              "set": {
                "$ref": "#/$defs/set"
              }
            }
          },
          "description": "Open another screen for the stop (?stop=) or create a record from it; set: may read stop"
        }
      },
      "description": "Today's stops: visit, check in, act there (contract 0030 §2)"
    }
  }
}
