Documentation

XML validation API

One POST, one verdict. Ask for SARIF and a broken sitemap shows up as an annotation on the pull request that broke it, instead of a line in a build log nobody reads.

Authentication

Create a key at API keys and send it as a bearer token. Only a hash of the key is stored, so it is shown exactly once — if you lose it, revoke it and issue another.

Endpoint: POST /api/v1/validate
Auth: Authorization: Bearer xmldir_live_…
Body: The document itself, or {"xml": "…", "xsd": "…", "filename": "…"} with a JSON content type
Formats: JSON by default; ?format=sarif or an Accept: application/sarif+json header for SARIF 2.1.0
Size limit: 5 MB
Rate limit: 1,000 requests per hour, per account

Nothing sent to this endpoint is stored

The API validates in memory and returns a verdict. It does not ingest: no document reaches your workspace, and none is written to a database or a log — only counts, so usage can be metered. Use the workspace when you want a document kept, versioned and monitored.

Validate a document

The simplest call: post the file, get a verdict.

Well-formedness only

curl -X POST https://xmldir.com/api/v1/validate \
  -H "Authorization: Bearer $XMLDIR_API_KEY" \
  -H "Content-Type: application/xml" \
  --data-binary @sitemap.xml

Response

{
  "valid": false,
  "wellFormed": false,
  "schemaChecked": false,
  "document": {
    "kind": "unknown",
    "rootElement": null,
    "encoding": "UTF-8",
    "byteSize": 214,
    "elementCount": 0,
    "distinctPaths": 0,
    "attributes": 0,
    "namespaces": 0
  },
  "errorCount": 1,
  "warningCount": 0,
  "findings": [
    {
      "rule": "xml/well-formed",
      "level": "error",
      "message": "Entity 'nbsp' not defined (line 4)",
      "line": 4
    }
  ]
}

Against a schema

Send an XSD alongside the document and it is validated against it too. The schema is used and discarded; it is not stored either.

With an XSD

curl -X POST https://xmldir.com/api/v1/validate \
  -H "Authorization: Bearer $XMLDIR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$(jq -n --rawfile xml order.xml --rawfile xsd order.xsd \
        '{xml: $xml, xsd: $xsd, filename: "order.xml"}')"

SARIF in CI

SARIF is the format GitHub code scanning, Azure DevOps and most CI dashboards already understand. Upload the output and each problem becomes an annotation on the offending line, with a link back to the page explaining that error.

.github/workflows/xml.yml

- name: Validate sitemap
  run: |
    curl -sS -X POST "https://xmldir.com/api/v1/validate?format=sarif" \
      -H "Authorization: Bearer ${{ secrets.XMLDIR_API_KEY }}" \
      -H "Content-Type: application/xml" \
      --data-binary @public/sitemap.xml > xmldir.sarif

- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: xmldir.sarif

A clean run returns a valid SARIF log with an empty results array, which is what clears previous annotations — so wire it up unconditionally rather than only on failure.

What gets checked

xml/well-formederror
The document could not be parsed. A document that is not well-formed cannot be read by any conforming XML parser.
Read more
xml/schema-validerror
The document parses but violates the schema it was validated against.
Read more
xml/namespace-undeclarederror
A prefix is used but never bound to a namespace URI. The document is well-formed XML 1.0, but a namespace-aware consumer will reject it.
Read more
xml/namespace-unusedwarning
A namespace is declared but nothing in the document uses it. Harmless in itself, but often the trace of something that was removed by accident.
Read more

Status codes

200 — the document was checked. Read `valid` for the verdict; a document with errors is still a successful request.
400 — no document, or a malformed request body.
401 — missing, unknown or revoked key. All three respond identically.
413 — the document is over the size limit.
429 — rate limit exceeded. Retry-After and X-RateLimit headers are set.

Get started

Wire XML validation into the pipeline that breaks it.

Create a free account, issue a key, and fail the build before a malformed sitemap or a drifted partner payload reaches production.

Get started free Sign in