Documentation

XML validation API

One POST, one verdict. Syntax, namespace, SOAP/XSD vocabulary, and optional schema failures become actionable JSON or SARIF annotations instead of a line in a build log nobody reads.

Authentication

Keys are issued from Account → API keys once you have a free account, and sent 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: 4 MB document; keep the complete request under 4 MB including JSON escaping and schemas (2 MB maximum for schemas).
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 checks XML syntax, namespaces, and selected SOAP or XML Schema vocabulary rules when the document uses those vocabularies.

Syntax and vocabulary

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 document receives selected XSD vocabulary checks before it is compiled, then it 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"}')"

Reusable validation policies

Create a policy in Validation policies to save an XSD bundle, vocabulary profile and rule severities. Each save creates an immutable revision with its own ID, scoped to your account.

Use a saved policy revision

{"xml":"<order/>","policyId":"YOUR_POLICY_REVISION_UUID","filename":"order.xml"}

For a raw XML body, use ?policy=YOUR_POLICY_REVISION_UUID. JSON and SARIF use the same settings. A policy cannot be combined with an inline XSD. Missing or inaccessible policies return 404; a policy storage failure returns 503. XML parse errors cannot be suppressed. Validation success means no errors remain after the selected severity overrides.

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 about WellFormed
xml/schema-validerror
The document parses but violates the schema it was validated against.
Read more about SchemaValid
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 about NamespaceUndeclared
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 about NamespaceUnused
soap/vocabularyerror
The document parses as XML but violates a selected SOAP 1.1 or SOAP 1.2 envelope, body, header, or fault rule.
Read more about SoapVocabulary
xsd/vocabularyerror
The schema document parses as XML but violates a selected XML Schema structure or declaration rule.
Read more about XsdVocabulary

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