{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://git.novox.be/novox/mesh-contracts/format/seat-definition.schema.json",
  "title": "A seat's definition (novox/hq ADR 0608 §1, design 26), format 1",
  "description": "One file per seat, seats/<seat>/seat.json. A whole definition (grain whole) gives every verb's input and answer, every message's body and where its events are kept; one at the seat list's grain (seat-list) holds what mesh-sdk's compiled seat list held (ADR 0613 §2). At most 256 KiB. Read strictly: a field not named here is refused.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "format",
    "seat",
    "scope",
    "grain",
    "domain",
    "decision"
  ],
  "properties": {
    "format": {
      "const": 1
    },
    "seat": {
      "type": "string",
      "pattern": "^[a-z][a-z0-9-]*[a-z0-9]$"
    },
    "scope": {
      "enum": [
        "mesh",
        "node"
      ]
    },
    "grain": {
      "enum": [
        "whole",
        "seat-list"
      ]
    },
    "domain": {
      "description": "the glossary domain the seat belongs to, by its heading (ADR 0636 §5)",
      "enum": [
        "Module",
        "Config",
        "Core",
        "Provisioning",
        "Identity and access",
        "Delivery",
        "Health and repair",
        "Data",
        "Connectivity",
        "Operator and conversation"
      ]
    },
    "decision": {
      "type": "string",
      "minLength": 1
    },
    "description": {
      "type": "string"
    },
    "holder-declares": {
      "type": "boolean",
      "description": "the seat is not in the compiled seat list; its holder's manifest declares it"
    },
    "delivers": {
      "type": "string"
    },
    "replicated": {
      "type": "boolean"
    },
    "pulled-by-kind": {
      "type": "boolean"
    },
    "yields": {
      "type": "boolean"
    },
    "held-by-the-engine": {
      "type": "boolean"
    },
    "includes": {
      "type": "array",
      "items": {
        "type": "string",
        "pattern": "^[a-z][a-z0-9-]*$"
      },
      "description": "parts/<name>.json taken in whole"
    },
    "verbs": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/verb"
      }
    },
    "accepts": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/message"
      }
    },
    "events": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/event"
      },
      "description": "published on mesh.seat.<seat>.event.<name>, or on its subject when it carries parts"
    },
    "family": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "max-age-days"
      ],
      "properties": {
        "name": {
          "type": "string"
        },
        "max-age-days": {
          "const": 7,
          "description": "the shared events stream's age: a seat's events ride it, filtered to the seat's subjects"
        }
      }
    },
    "holder-events": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "subject"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$"
          },
          "subject": {
            "type": "string"
          },
          "family": {
            "type": "string"
          },
          "body": {
            "type": "object",
            "description": "a JSON Schema"
          }
        }
      },
      "description": "the holder's own events listed beside the seat, keeping the holder's subjects (ADR 0620 §2)"
    },
    "states": {
      "type": "array",
      "description": "the layouts of the state the holder keeps on the bus for the seat (ADR 0608 §1, ADR 0634 §6); a whole definition's. No holder module is named: each reader takes the holder from its own manifest's reads",
      "items": {
        "$ref": "#/$defs/state"
      }
    },
    "provisions": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "form"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "form": {
            "type": "object",
            "description": "a JSON Schema"
          }
        }
      }
    },
    "receives": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind"
        ],
        "properties": {
          "kind": {
            "type": "string"
          },
          "comment": {
            "type": "string"
          },
          "dirs": {
            "type": "boolean"
          },
          "offered": {
            "type": "boolean"
          },
          "shape": {
            "type": "object",
            "additionalProperties": false,
            "properties": {
              "places": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "field"
                  ],
                  "properties": {
                    "field": {
                      "type": "string"
                    },
                    "values": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              },
              "order": {
                "type": "string"
              },
              "examples": {
                "type": "array",
                "items": {
                  "type": "object"
                }
              },
              "text": {
                "type": "boolean"
              }
            }
          }
        }
      }
    },
    "paths": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "path"
        ],
        "properties": {
          "path": {
            "type": "string",
            "pattern": "^/"
          },
          "steps-back-for": {
            "type": "string"
          }
        }
      }
    },
    "defs": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "description": "a JSON Schema"
      }
    },
    "acts": {
      "type": "array",
      "description": "the seat's acting rules (design 47 G 203): each step of a delivery the seat's holder acts in, on which modules, and how long an entry waits there for the holder's new version",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "step"
        ],
        "properties": {
          "step": {
            "type": "string",
            "enum": [
              "take-in",
              "validate",
              "check",
              "pipeline",
              "build",
              "compose",
              "grant",
              "place"
            ]
          },
          "on": {
            "type": "string",
            "pattern": "^(every|kind:image|[a-z][a-z0-9-]*)$",
            "description": "every (the default), a language, or kind:image (design 47 G 397)"
          },
          "bound": {
            "type": "string",
            "pattern": "^([0-9]+(\\.[0-9]+)?(h|m|s|ms))+$",
            "description": "how long an entry waits in the step for the holder's new version, such as 30m (design 47 G 397); none is the step's default"
          }
        }
      }
    },
    "bodies": {
      "type": "object",
      "additionalProperties": {
        "type": "object",
        "description": "a JSON Schema"
      },
      "description": "the bodies other modules say on their own streams, from which the grants part makes no seat event or stream (design 47 G 439)"
    }
  },
  "$defs": {
    "verb": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "description": {
          "type": "string"
        },
        "optional": {
          "type": "boolean"
        },
        "replaces": {
          "type": "array",
          "items": {
            "type": "string"
          }
        },
        "input": {
          "type": "object",
          "description": "a JSON Schema"
        },
        "answer": {
          "type": "object",
          "description": "a JSON Schema"
        },
        "class": {
          "enum": [
            "read",
            "act",
            "warrant"
          ],
          "description": "read: invokers, persons and sessions; act and warrant: operator, sessions and invokers (design 47 G 610); no verb names its callers, and a definition naming a `callers` is refused. A verb that names no class is a read, whether it is on main or design 47 G adds it, and nothing refuses a verb for naming none (design 47 G 456)"
        },
        "needs-approval": {
          "type": "boolean",
          "description": "the verb runs only on the operator's Approve of the call, for every holder (design 46 milestone 7, 2)"
        },
        "by-caller": {
          "type": "boolean",
          "description": "the holder's process answers the verb itself and tells callers apart by the account the bus proved (ADR 0259 3; design 47 G 554, 621, 656)"
        },
        "chunks": {
          "type": "boolean",
          "description": "the holder's process sends the answer's file in chunks on mesh.seat.<seat>.chunk.<verb>.<call>.<n>, each acknowledged by the caller on mesh.seat.<seat>.ack.<verb>.<call>.<n>; only with by-caller (design 47 G 681)"
        }
      }
    },
    "message": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "stream": {
          "enum": [
            "check",
            "delivery"
          ],
          "description": "the stream an accepted kind rides: its subject is <stream>.<kind>, and one kind name may ride both streams, as the build seats accept step on check and on delivery (design 47 G 455)"
        },
        "body": {
          "type": "object",
          "description": "a JSON Schema"
        },
        "by-caller": {
          "type": "boolean"
        }
      }
    },
    "part": {
      "description": "parts/<name>.json",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "format",
        "part"
      ],
      "properties": {
        "format": {
          "const": 1
        },
        "part": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "description": {
          "type": "string"
        },
        "verbs": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/verb"
          }
        },
        "events": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/message"
          }
        },
        "defs": {
          "type": "object",
          "additionalProperties": {
            "type": "object",
            "description": "a JSON Schema"
          }
        }
      }
    },
    "fixtures": {
      "description": "seats/<seat>/fixtures/*.json: data, never functions",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name",
          "of",
          "given"
        ],
        "properties": {
          "name": {
            "type": "string"
          },
          "of": {
            "type": "string",
            "pattern": "^(verb:[a-z][a-z0-9-]*\\.(input|answer)|accept:[a-z][a-z0-9-]*|event:[a-z][a-z0-9-]*|state:[a-z][a-z0-9-]*/.+|holder-event:[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*)$"
          },
          "subject": {
            "type": "string"
          },
          "given": {},
          "wire": {},
          "why": {
            "type": "string"
          }
        }
      }
    },
    "index": {
      "description": "seats/index.json: the seat list's reading order",
      "type": "object",
      "additionalProperties": false,
      "required": [
        "format",
        "seats"
      ],
      "properties": {
        "format": {
          "const": 1
        },
        "seats": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "uniqueItems": true
        }
      }
    },
    "state": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name",
        "template",
        "key-forms"
      ],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*$"
        },
        "template": {
          "enum": [
            "state",
            "events",
            "work-queue",
            "log",
            "objects",
            "ledger"
          ],
          "description": "ADR 0595 §2"
        },
        "writer": {
          "enum": [
            "holder",
            "caller"
          ],
          "description": "holder when not given; caller when the seat's callers write their own keys"
        },
        "key-forms": {
          "type": "array",
          "minItems": 1,
          "items": {
            "$ref": "#/$defs/keyForm"
          }
        },
        "history": {
          "type": "integer",
          "minimum": 0,
          "description": "past values a key keeps; the state template only"
        },
        "max-age-days": {
          "type": "integer",
          "minimum": 0,
          "description": "days a message is kept; the events, work-queue and log templates only"
        },
        "description": {
          "type": "string"
        },
        "view": {
          "type": "boolean",
          "const": true,
          "description": "true when the seat offers the state as a view for a module to follow by `consumes` (design 47 G 699; ADR 0571 §6); the manifest validator refuses a seat-named view of a state without it"
        }
      }
    },
    "keyForm": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "key",
        "value"
      ],
      "properties": {
        "key": {
          "type": "string",
          "minLength": 1,
          "description": "a pattern of named parts between angle brackets, the rest literal: <asker>.<id>"
        },
        "value": {
          "type": "object",
          "description": "a JSON Schema"
        },
        "description": {
          "type": "string"
        }
      }
    },
    "event": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "name"
      ],
      "properties": {
        "name": {
          "type": "string",
          "pattern": "^[a-z][a-z0-9-]*(\\.[a-z][a-z0-9-]*)*$",
          "description": "lower-case words; a dot only in an event that names no keep, which stays on its seat's family (design 47 G 396)"
        },
        "body": {
          "type": "object",
          "description": "a JSON Schema"
        },
        "by-caller": {
          "type": "boolean"
        },
        "subject": {
          "type": "string",
          "pattern": "^([a-z][a-z0-9-]*|<[a-z][a-z0-9-]*>)(\\.([a-z][a-z0-9-]*|<[a-z][a-z0-9-]*>))*$",
          "description": "the words after mesh.seat.<seat>.event. with <part> tokens, <node> written out (design 47 G 397); a part <node> is the publishing node's. Not with by-caller"
        },
        "keep": {
          "type": "object",
          "additionalProperties": false,
          "description": "the event is kept on the stream SEAT_<seat>_<event> (design 47 G 396); without it the event stays on the seat's family",
          "properties": {
            "max-age-days": {
              "type": "integer",
              "minimum": 0,
              "description": "days a message is kept; 0 is no age limit; 90 when not named"
            },
            "max-mib": {
              "type": "integer",
              "minimum": 1,
              "description": "the stream's cap in MiB; 16 when not named"
            },
            "last-per-subject": {
              "type": "boolean",
              "description": "keep the last message of each subject; no when not named"
            }
          }
        }
      },
      "allOf": [
        {
          "if": {
            "required": [
              "keep"
            ]
          },
          "then": {
            "properties": {
              "name": {
                "pattern": "^[a-z][a-z0-9-]*$"
              }
            }
          }
        }
      ]
    }
  }
}