{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://www.cuddler.dev/standards/document-role/template/v1.0.0/cuddler.template.diagnostics.schema.1.0.0.json",
  "title": "Cuddler Template Diagnostics Schema",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "valid",
    "diagnostics"
  ],
  "properties": {
    "valid": {
      "type": "boolean",
      "for-ai": [
        {
          "instruction": "Use this guidance when preparing a valid value for this schema node.",
          "input": "",
          "output": "True when the validated artifact passed schema and semantic validation."
        }
      ]
    },
    "diagnostics": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/Diagnostic"
      },
      "for-ai": [
        {
          "instruction": "Use this guidance when preparing a valid value for this schema node.",
          "input": "",
          "output": "Ordered list of validation or render diagnostics."
        }
      ]
    },
    "metadata": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "validatorId": {
          "type": "string",
          "minLength": 1
        },
        "specVersion": {
          "type": "string",
          "minLength": 1
        },
        "schemaUri": {
          "type": "string",
          "format": "uri"
        },
        "templateUri": {
          "type": "string",
          "format": "uri"
        },
        "dataSchemaUri": {
          "type": "string",
          "format": "uri"
        }
      },
      "for-ai": [
        {
          "instruction": "Use this guidance when preparing a valid value for this schema node.",
          "input": "",
      "output": "Optional metadata about the validator, schema version, and run context."
        }
      ]
    }
  },
  "$defs": {
    "Severity": {
      "type": "string",
      "enum": [
        "error",
        "warning",
        "info"
      ]
    },
    "Diagnostic": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "code",
        "message",
        "path",
        "severity"
      ],
      "properties": {
        "code": {
          "type": "string",
          "minLength": 1,
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Stable machine-readable diagnostic code."
            }
          ]
        },
        "ruleId": {
          "type": "string",
          "minLength": 1,
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional lint or conformance rule identifier associated with this diagnostic."
            }
          ]
        },
        "message": {
          "type": "string",
          "minLength": 1,
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Human-readable diagnostic summary."
            }
          ]
        },
        "path": {
          "type": "string",
          "minLength": 1,
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Primary path for the problem, usually a JSONPath-like or pointer-like location."
            }
          ]
        },
        "instancePath": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional instance path pointing at the failing artifact location."
            }
          ]
        },
        "schemaPath": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional schema path that triggered the failure."
            }
          ]
        },
        "specSection": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional specification section identifier that defines the violated rule or behavior."
            }
          ]
        },
        "templatePath": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional path inside a template file."
            }
          ]
        },
        "dataPath": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional path inside the paired data document."
            }
          ]
        },
        "severity": {
          "$ref": "#/$defs/Severity",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Diagnostic severity."
            }
          ]
        },
        "expected": {
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional expected value or shape."
            }
          ]
        },
        "actual": {
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional actual value or shape."
            }
          ]
        },
        "hint": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional remediation hint."
            }
          ]
        },
        "suggestedFix": {
          "type": "string",
          "for-ai": [
            {
              "instruction": "Use this guidance when preparing a valid value for this schema node.",
              "input": "",
              "output": "Optional short corrective action suitable for automated repair loops."
            }
          ]
        }
      }
    }
  },
  "for-ai": [
    {
      "instruction": "Use this guidance when preparing a valid value for this schema node.",
      "input": "",
      "output": "Diagnostic-output schema for Cuddler template-schema, markdown-template, and renderer validation results in v1.0.0."
    }
  ]
}