{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://digihome.cc/feedback.schema.json",
  "title": "Digihome feedback",
  "description": "One feedback message about Digihome, from a person (the form on docs.html#feedback) or an agent. This file is the one place the shape lives; the form checks against it. There is no public endpoint: the form composes the message for the person to send.",
  "type": "object",
  "required": [
    "version",
    "from",
    "message",
    "os"
  ],
  "additionalProperties": false,
  "properties": {
    "version": {
      "type": "integer",
      "const": 1,
      "description": "Shape version. Always 1 for now."
    },
    "from": {
      "type": "string",
      "enum": [
        "human",
        "agent"
      ],
      "description": "Who wrote it: a person using the form, or an agent."
    },
    "message": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "The feedback itself, plain text."
    },
    "os": {
      "type": "string",
      "enum": [
        "macos",
        "windows",
        "linux",
        "chromeos",
        "other"
      ],
      "description": "The computer Digihome runs (or would run) on."
    },
    "topic": {
      "type": "string",
      "enum": [
        "general",
        "setup",
        "bug",
        "idea",
        "pricing",
        "windows"
      ],
      "description": "What it is about."
    },
    "name": {
      "type": "string",
      "maxLength": 80,
      "description": "Optional. How to address the sender."
    },
    "contact": {
      "type": "string",
      "maxLength": 200,
      "description": "Optional. An email or handle, only if the sender wants a reply."
    },
    "agent_name": {
      "type": "string",
      "maxLength": 120,
      "description": "With from agent: the agent's name, and whose behalf it acts on if any."
    },
    "page": {
      "type": "string",
      "maxLength": 500,
      "description": "The page the feedback was written on."
    },
    "sent_at": {
      "type": "string",
      "maxLength": 40,
      "pattern": "^\\d{4}-\\d{2}-\\d{2}T",
      "description": "When it was written, ISO 8601 (the sender's clock)."
    }
  },
  "examples": [
    {
      "version": 1,
      "from": "human",
      "message": "Typing stopped after I updated macOS.",
      "os": "macos",
      "topic": "bug"
    },
    {
      "version": 1,
      "from": "agent",
      "agent_name": "a research agent for a reader",
      "message": "Setup was clear; the person wants to know when Windows ships.",
      "os": "windows",
      "topic": "windows"
    }
  ]
}