{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/attestwire-com/json-schema/attestwire-com-teaching-error-schema.json",
  "title": "TeachingError",
  "description": "One finding, with enough context to fix the invoice without opening the specification. Almost always a rule failure. The exception is a finding the engine raises about a document as a whole, whose `rule` starts `AW-` — such as `AW-PROFILE-SUBSET`, fatal, on a Factur-X or ZUGFeRD file whose BT-24 declares MINIMUM or BASIC WL, profiles that carry too little to be an EN 16931 invoice. It comes first, ahead of the rule failures it explains. The others are about a Factur-X or ZUGFeRD PDF's container and never fatal: `AW-PDF-ATTACHMENT`, `AW-PDF-AF`, `AW-PDF-RELATIONSHIP` and `AW-PDF-MIME` on the attached invoice XML, `AW-PDF-XMP` and `AW-PDF-XMP-PROFILE` on the XMP metadata, all on field `document` except an `AW-PDF-XMP-PROFILE` that contradicts the XML's own BT-24, which is on `BT-24`. An `AW-` finding has no rules page, so no `docsUrl`, and no `xpath` or `location`: its `message` and `fix` are the whole explanation.",
  "x-generated": "2026-11-02",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/attestwire-com-openapi.json#/components/schemas/TeachingError",
  "type": "object",
  "required": [
    "rule",
    "field",
    "severity",
    "message",
    "fix"
  ],
  "properties": {
    "rule": {
      "type": "string",
      "description": "The rule id, as the KoSIT validator prints it: BR-*, BR-DE-*, PEPPOL-EN16931-R*. `ATW-*` is a check of this validator's own rather than the regulation's. `AW-*` is not a rule at all: see above."
    },
    "field": {
      "description": "Business term(s) the rule constrains.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      ]
    },
    "severity": {
      "type": "string",
      "enum": [
        "fatal",
        "warning",
        "information"
      ],
      "description": "The reference validators' own three levels. `fatal` rejects the document; `warning` does not; `information` is advisory — KoSIT raises it and then accepts the invoice."
    },
    "message": {
      "type": "string"
    },
    "fix": {
      "type": "string"
    },
    "xpath": {
      "type": "string",
      "description": "Where the element is. For a JSON invoice, its place in the UBL this API would generate. For an XML document, its path in that document as written when it is there, otherwise where it belongs, in the document's own syntax."
    },
    "docsUrl": {
      "type": "string",
      "format": "uri",
      "description": "Where the rule is explained. On every finding except an `AW-` one, which is not a rule and has no page."
    },
    "location": {
      "$ref": "#/$defs/SourceLocation"
    }
  },
  "$defs": {
    "SourceLocation": {
      "type": "object",
      "description": "Only on findings for a document, and not on an `AW-` one, which is about the whole document. The line and column of the element in the document that was sent. When the element is missing, or several could be meant and nothing says which, `exact` is false and this is the nearest enclosing element that is there.",
      "required": [
        "line",
        "column",
        "path",
        "exact"
      ],
      "properties": {
        "line": {
          "type": "integer",
          "minimum": 1
        },
        "column": {
          "type": "integer",
          "minimum": 1,
          "description": "Of the start tag, in UTF-16 code units."
        },
        "path": {
          "type": "string",
          "description": "The element's path, with the document's own prefixes."
        },
        "exact": {
          "type": "boolean"
        },
        "attachment": {
          "type": "string",
          "description": "Only when a PDF was sent: the name of the attachment the XML was read from. `line` and `column` are then in that XML, not in the PDF."
        }
      }
    }
  }
}