ValidationResponse

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/invoicexml-com/json-schema/invoicexml-com-validation-response-schema.json",
  "title": "ValidationResponse",
  "description": "The JSON verdict every `/v1/validate/*` endpoint answers with on HTTP 200, whether\nthe document passed or failed (the `/report` siblings answer with a PDF instead).",
  "x-generated": "2026-10-30",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/invoicexml-com-openapi.json#/components/schemas/ValidationResponse",
  "required": [
    "valid",
    "detail",
    "data",
    "errors",
    "warnings"
  ],
  "type": "object",
  "properties": {
    "valid": {
      "type": "boolean",
      "description": "`true` when the document passed every fatal rule."
    },
    "detail": {
      "type": "string",
      "description": "One sentence summarising the verdict."
    },
    "data": {
      "description": "What was validated and the outcome per layer.",
      "$ref": "#/$defs/ValidationResponseData"
    },
    "errors": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ValidationFinding"
      },
      "description": "Fatal findings. Empty when Valid is `true`."
    },
    "warnings": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/ValidationFinding"
      },
      "description": "Non-blocking findings (Schematron warnings and advisories such as an unrecognised profile). Never affect the verdict."
    },
    "report": {
      "type": [
        "null",
        "array"
      ],
      "items": {
        "$ref": "#/$defs/InvoiceReportRow"
      },
      "description": "The invoice's Business Terms (BT-x) with their values and the findings attached to\neach, for field-level display. `null` when the document could not be parsed into\nthe invoice model. Absent on `/v1/validate/order-x` and when no invoice XML could\nbe read (a PDF without an embedded XML, or one embedding the wrong syntax)."
    }
  },
  "$defs": {
    "InvoiceReportFinding": {
      "required": [
        "rule",
        "message"
      ],
      "type": "object",
      "properties": {
        "rule": {
          "type": "string"
        },
        "message": {
          "type": "string"
        }
      }
    },
    "InvoiceReportRow": {
      "required": [
        "code",
        "name",
        "section",
        "path",
        "value",
        "isValid",
        "errors",
        "warnings"
      ],
      "type": "object",
      "properties": {
        "code": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "section": {
          "type": "string"
        },
        "path": {
          "type": "string"
        },
        "value": {
          "type": [
            "null",
            "string"
          ]
        },
        "isValid": {
          "type": "boolean"
        },
        "errors": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/InvoiceReportFinding"
          }
        },
        "warnings": {
          "type": "array",
          "items": {
            "$ref": "#/$defs/InvoiceReportFinding"
          }
        }
      }
    },
    "ValidationFinding": {
      "required": [
        "rule",
        "layer",
        "line",
        "message",
        "btCodes",
        "fields",
        "raw"
      ],
      "type": "object",
      "properties": {
        "rule": {
          "type": [
            "null",
            "string"
          ],
          "description": "Identifier of the rule that fired (for example `BR-CO-15`, `PEPPOL-EN16931-R010`, `PDF-EMBED`). `null` for a request model finding that reports no rule."
        },
        "layer": {
          "type": [
            "null",
            "string"
          ],
          "description": "Validation layer the finding came from: `xsd`, `en16931` or `cius`. `null` for findings outside the XML validation pipeline."
        },
        "line": {
          "type": [
            "null",
            "integer"
          ],
          "description": "1-based invoice line the finding refers to, or `null` for document-level findings.",
          "format": "int32"
        },
        "message": {
          "type": "string",
          "description": "Human-readable explanation of the finding and how to fix it, in the language the request asked for with `validationLanguage` (`en`, `de` or `fr`; English by default). The text of a rule that has no curated message stays in the rule set's own wording."
        },
        "btCodes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "EN 16931 Business Terms involved (for example `BT-31`). Empty when the rule maps to none."
        },
        "fields": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Dotted paths into the invoice JSON model (for example `seller.vatIdentifier`, `lines[0].quantity`). Empty when the rule maps to none."
        },
        "raw": {
          "type": [
            "null",
            "string"
          ],
          "description": "The validator's verbatim output line for the finding, whatever the `validationLanguage`. `null` when there is none."
        }
      },
      "description": "One self-contained finding, as listed in the `errors` and `warnings` arrays of\nthe validate verdict and of the 400 problem responses. Every finding carries all seven\nfields; the ones that do not apply are `null` or empty."
    },
    "ValidationResponseData": {
      "type": "object",
      "properties": {
        "hasEmbeddedXml": {
          "type": [
            "null",
            "boolean"
          ],
          "description": "Hybrid PDF endpoints only (`facturx`, `zugferd`, `order-x`): whether the\nPDF carried an invoice XML attachment. When `false`, no other field is present."
        },
        "schemaValid": {
          "type": [
            "null",
            "boolean"
          ],
          "description": "Whether the XML passed the XSD schema layer."
        },
        "schematronValid": {
          "type": [
            "null",
            "boolean"
          ],
          "description": "Whether the XML passed the EN 16931 and profile (CIUS) business rules."
        },
        "conformanceLevel": {
          "type": [
            "null",
            "string"
          ],
          "description": "The standard validated against: `EN16931`, `UBL 2.1`, `XRechnung` or `Order-X`."
        },
        "profile": {
          "type": [
            "null",
            "string"
          ],
          "description": "Slug of the profile whose rule set ran (for example `peppol-bis-3`,\n`xrechnung`, `facturx-basic`). `null` when the document declares no\nprofile this validator has dedicated rules for."
        },
        "customizationId": {
          "type": [
            "null",
            "string"
          ],
          "description": "The specification identifier (BT-24) the document declares, verbatim."
        }
      },
      "description": "Outcome per validation layer plus the profile the document was checked against.\nWhich fields are present depends on the endpoint and on how far validation got."
    }
  }
}