{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://theamateur.co.uk/schemas/dpl/dpl.diagnostics-1.schema.json",
  "title": "DPL validation diagnostics (dpl.diagnostics/1)",
  "description": "What `dpl validate <plan> --format json` writes: every error and warning found in a plan, each with the rule that found it, where it is (a JSON path into the plan), what is wrong, and `fix`: what to change next, using the plan's own ids and paths. Every member listed here is always written, or left out when null; nothing else appears.",
  "$comment": "`valid` is true when there is no error (warnings do not make a plan invalid). `plan_hash` is the SHA-256 of the plan in its standard layout (`dpl format`), the same revision hash `dpl readiness` and `dpl missing` report; it is present only when the plan could be read. When it could not, the one diagnostic is `DPL-JSON`, with the path of the unreadable value. The same checks give the `DPL-*` findings of `dpl readiness`.",
  "type": "object",
  "properties": {
    "schema": {
      "type": "string",
      "const": "dpl.diagnostics/1"
    },
    "plan_hash": {
      "description": "SHA-256 of the plan in its standard layout; absent when the plan could not be read.",
      "type": [
        "string",
        "null"
      ],
      "pattern": "^[0-9a-f]{64}$"
    },
    "valid": {
      "description": "True when there is no error (warnings do not make a plan invalid).",
      "type": "boolean"
    },
    "summary": {
      "$ref": "#/$defs/DiagnosticsSummary"
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/DiagnosticItem"
      }
    }
  },
  "required": [
    "schema",
    "valid",
    "summary",
    "diagnostics"
  ],
  "additionalProperties": false,
  "$defs": {
    "DiagnosticItem": {
      "type": "object",
      "description": "One diagnostic as an agent reads it: what rule, where, what is wrong, and what to change.",
      "properties": {
        "code": {
          "type": "string",
          "pattern": "^DPL-[A-Z]+(-[A-Z]+)*$"
        },
        "severity": {
          "$ref": "#/$defs/PlanSeverity"
        },
        "path": {
          "type": "string",
          "pattern": "^\\$"
        },
        "message": {
          "type": "string"
        },
        "fix": {
          "type": "string",
          "pattern": "\\S"
        }
      },
      "required": [
        "code",
        "severity",
        "path",
        "message",
        "fix"
      ],
      "additionalProperties": false
    },
    "DiagnosticsSummary": {
      "type": "object",
      "description": "How many errors and warnings a plan has.",
      "properties": {
        "errors": {
          "type": "integer",
          "minimum": 0
        },
        "warnings": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "errors",
        "warnings"
      ],
      "additionalProperties": false
    },
    "PlanSeverity": {
      "type": "string",
      "enum": [
        "error",
        "warning"
      ]
    }
  }
}