dashboard.overview

{
  "additionalProperties": false,
  "description": "No input.",
  "title": "Empty",
  "type": "object"
}

{
  "$defs": {
    "DashboardCard": {
      "description": "One fact on a dashboard: a value read out of one capability's answer, the verdict the\nsource gives it, where a reader drills in, and what acts on it.\n\n```\nuse majordomus_cli::capability::builtin::dashboard::DashboardCard;\nuse serde_json::json;\n\nlet card: DashboardCard = serde_json::from_value(json!({\n    \"id\": \"health-status\",\n    \"title\": \"Health\",\n    \"value\": \"ok\",\n    \"status\": \"ok\",\n    \"detail\": \"the worst of 8 check(s)\",\n    \"source\": { \"capability\": \"health.report\", \"input\": {}, \"pointer\": \"/status\", \"measure\": \"exact\" },\n    \"route\": \"/cockpit/health\",\n})).unwrap();\n// the value is the source's: reading the pointer out of its answer gives it back\nassert_eq!(card.source.measure.read(&json!({ \"status\": \"ok\" }), &card.source.pointer), card.value);\nassert!(card.action.is_none());\n```",
      "properties": {
        "action": {
          "description": "The command that acts on it, when one does.",
          "type": [
            "string",
            "null"
          ]
        },
        "detail": {
          "description": "One line: what the value means, or why the source could not answer.",
          "type": "string"
        },
        "id": {
          "description": "A stable id, `[a-z][a-z0-9-]*`, unique across the dashboard.",
          "type": "string"
        },
        "route": {
          "description": "The Cockpit page a reader drills into for the evidence.",
          "type": "string"
        },
        "source": {
          "$ref": "#/$defs/DashboardSource",
          "description": "Where the value came from."
        },
        "status": {
          "$ref": "#/$defs/HealthStatus",
          "description": "The source's verdict on it; `unknown` when the source could not answer."
        },
        "title": {
          "description": "What the value is.",
          "type": "string"
        },
        "value": {
          "description": "The value, read out of the source's answer by the source's measure: a number, a\nstring or a boolean, or `null` when the source holds none."
        }
      },
      "required": [
        "id",
        "title",
        "value",
        "status",
        "detail",
        "source",
        "route"
      ],
      "type": "object"
    },
    "DashboardMeasure": {
      "description": "How a card's value is read out of its source's answer. Neither reading is arithmetic on\nthe source's behalf.\n\n```\nuse majordomus_cli::capability::builtin::dashboard::DashboardMeasure;\nuse serde_json::json;\n\nlet answer = json!({ \"status\": \"warn\", \"tallies\": { \"ok\": 6 }, \"overlaps\": [1, 2] });\n// exact: the value at the pointer, null when there is none\nassert_eq!(DashboardMeasure::Exact.read(&answer, \"/status\"), json!(\"warn\"));\nassert_eq!(DashboardMeasure::Exact.read(&answer, \"/tallies/fail\"), json!(null));\n// count: a number as it stands, a list or map by its length, and an omitted one is none\nassert_eq!(DashboardMeasure::Count.read(&answer, \"/tallies/ok\"), json!(6));\nassert_eq!(DashboardMeasure::Count.read(&answer, \"/overlaps\"), json!(2));\nassert_eq!(DashboardMeasure::Count.read(&answer, \"/tallies/fail\"), json!(0));\n```",
      "oneOf": [
        {
          "const": "exact",
          "description": "The value at the pointer, exactly; `null` when the pointer resolves to nothing.",
          "type": "string"
        },
        {
          "const": "count",
          "description": "The number at the pointer, or the length of the list or map there; `0` when the\nsource left it out, which is how the sources say an empty list or a zero tally.",
          "type": "string"
        }
      ]
    },
    "DashboardQuestion": {
      "description": "One of the four questions the Overview answers, with the cards that answer it.\n\n```\nuse majordomus_cli::capability::builtin::dashboard::DashboardQuestion;\nuse majordomus_cli::capability::builtin::HealthStatus;\nuse serde_json::json;\n\nlet q: DashboardQuestion = serde_json::from_value(json!({\n    \"id\": \"healthy\", \"title\": \"Is it healthy?\", \"status\": \"ok\", \"cards\": [],\n})).unwrap();\nassert_eq!(q.status, HealthStatus::Ok);\n```",
      "properties": {
        "cards": {
          "description": "The facts that answer it, each read from a capability.",
          "items": {
            "$ref": "#/$defs/DashboardCard"
          },
          "type": "array"
        },
        "id": {
          "description": "`healthy`, `changed`, `broken` or `action`.",
          "type": "string"
        },
        "status": {
          "$ref": "#/$defs/HealthStatus",
          "description": "The worst of its cards."
        },
        "title": {
          "description": "The question, as a reader asks it.",
          "type": "string"
        }
      },
      "required": [
        "id",
        "title",
        "status",
        "cards"
      ],
      "type": "object"
    },
    "DashboardSource": {
      "description": "Where a card's value came from: the capability asked, the input it was asked with, and\nthe pointer into its answer. Asking the capability the same question and reading the\npointer with the same measure yields the card's value; that is the whole contract.\n\n```\nuse majordomus_cli::capability::builtin::dashboard::{DashboardMeasure, DashboardSource};\nuse serde_json::json;\n\nlet s: DashboardSource = serde_json::from_value(json!({\n    \"capability\": \"health.report\",\n    \"input\": {},\n    \"pointer\": \"/status\",\n    \"measure\": \"exact\",\n})).unwrap();\nassert_eq!(s.measure, DashboardMeasure::Exact);\nassert_eq!(s.measure.read(&json!({ \"status\": \"ok\" }), &s.pointer), json!(\"ok\"));\n```",
      "properties": {
        "capability": {
          "description": "The canonical id of the capability the value was read from.",
          "type": "string"
        },
        "input": {
          "description": "The input it was asked with, as its input schema takes it."
        },
        "measure": {
          "$ref": "#/$defs/DashboardMeasure",
          "description": "How the value is read at the pointer."
        },
        "pointer": {
          "description": "An RFC 6901 JSON pointer into that capability's answer.",
          "type": "string"
        }
      },
      "required": [
        "capability",
        "input",
        "pointer",
        "measure"
      ],
      "type": "object"
    },
    "HealthStatus": {
      "description": "Where one dimension of the system stands. Ordered by severity, so the worst check\ndecides the whole.",
      "oneOf": [
        {
          "const": "ok",
          "description": "The engine that decides this dimension is satisfied.",
          "type": "string"
        },
        {
          "const": "warn",
          "description": "Nothing is broken and something is worth looking at.",
          "type": "string"
        },
        {
          "const": "fail",
          "description": "The engine that decides this dimension is not satisfied.",
          "type": "string"
        },
        {
          "const": "unknown",
          "description": "This process cannot decide it, and says so rather than reporting `ok`.",
          "type": "string"
        }
      ]
    }
  },
  "description": "The Overview: four questions, each answered by facts other capabilities hold.\n\n```\nuse majordomus_cli::capability::builtin::dashboard::DashboardOverview;\nuse majordomus_cli::capability::builtin::HealthStatus;\nuse serde_json::json;\n\nlet o: DashboardOverview = serde_json::from_value(json!({ \"status\": \"unknown\", \"questions\": [] })).unwrap();\nassert_eq!(o.status, HealthStatus::Unknown);\n```",
  "properties": {
    "questions": {
      "description": "`healthy`, `changed`, `broken`, `action`, in that order.",
      "items": {
        "$ref": "#/$defs/DashboardQuestion"
      },
      "type": "array"
    },
    "status": {
      "$ref": "#/$defs/HealthStatus",
      "description": "The worst of the questions: `unknown` outranks `fail`, because an undecided fact is\nnot a healthy one."
    }
  },
  "required": [
    "status",
    "questions"
  ],
  "title": "DashboardOverview",
  "type": "object"
}