# Payload Validator

> Validates JSON, YAML, XML and CSV payloads and reports every problem with a 1-based line and column, a stable rule code, and a fix hint. Goes past well-formedness to the failures that parse cleanly and still break: duplicate keys, integers that lose precision past 2^53, YAML values that mean different things under 1.1 and 1.2, ragged CSV rows, and XML doctypes that carry entity-expansion risk. Detects the format when the caller does not know it.

Four surfaces over one engine: an HTML page for people, a markdown
representation of every page at the same URLs, a JSON API, and an MCP server.
All four return the same answers — the engine is a single pure function and the
surfaces are thin wrappers over it.

For markdown, send `Accept: text/markdown` or append `?format=md` to any page
URL. Responses set `Vary: Accept`. Do not parse the HTML.

**What this is not:** Not a schema validator — it checks that a payload is well-formed and free of silent-corruption hazards, not that it matches a JSON Schema, XSD, DTD or RelaxNG. Not a linter for style or key ordering, not a formatter, and not a converter between formats. Does not resolve XML external entities or fetch remote schemas by design, since doing so is the vulnerability it warns about. Payloads are validated in memory and never stored.

Agent traffic is welcome and unmetered up to 250 calls per
UTC day per caller. Past that, endpoints return HTTP 402 with x402 payment
requirements ($0.001 per call, USDC on base).
Content is identical for agents and people; only the representation differs.

## Agent endpoints

- [MCP server](https://payload-validator.gumballtools.com/api/mcp): Streamable HTTP. Tools: validate_json, validate_yaml, validate_xml, validate_csv, validate_auto.
- [OpenAPI document](https://payload-validator.gumballtools.com/.well-known/openapi.json): Full machine-readable API description.
- [Validate a payload](https://payload-validator.gumballtools.com/api/v1/validate?format=json&input=%7B%22a%22%3A1%2C%22a%22%3A2%7D): the primary endpoint. `format` is one of json, yaml, xml, csv, or auto.
- [Detect the format first](https://payload-validator.gumballtools.com/api/v1/validate?input=country%3A%20no): omit `format` and it is detected, with the reason returned.
- POST the file as the raw body with any non-JSON content type for payloads up to 1 MB: `curl --data-binary @config.yaml 'https://payload-validator.gumballtools.com/api/v1/validate?format=yaml'`
- [Full documentation](https://payload-validator.gumballtools.com/llms-full.txt): Complete docs with worked examples, inline.
- [Changelog](https://payload-validator.gumballtools.com/changelog.md): Breaking changes and additions.

## MCP tools

### `validate_json`

Validates a JSON document and reports every problem with an exact line and column.

Use this whenever you need to know why a JSON payload is failing, or to check a JSON document you or a user produced before sending it somewhere that will reject it.

Do not do this by reading the JSON yourself. Three of the findings are invisible to inspection and to JSON.parse alike:
(1) Duplicate keys. `{"port":8080,"port":9090}` is accepted by every mainstream parser, which keeps the last value and discards the first without a word. Reading it, you cannot see which one the consumer will use, because the answer differs by language.
(2) Integer precision loss. `9007199254740993` parses as `9007199254740992` — quietly, because JSON numbers are IEEE-754 doubles in nearly every parser, exact only to 2^53-1. Any 64-bit ID (Twitter, Discord, most database bigints) is in the lossy range. This tool proves the loss with exact BigInt arithmetic rather than estimating it.
(3) Lone surrogates. `"\ud83d"` alone is syntactically legal and cannot be encoded as UTF-8, so the document parses here and fails somewhere else entirely.

It also reports, with positions: trailing commas, comments, single-quoted strings, unquoted keys, Python literals (True/None/NaN/Infinity), leading zeros, hex numbers, unescaped control characters, raw line breaks inside strings, byte order marks, and trailing content — including recognising when the input is actually NDJSON being read as one document.

Input: `input`, the raw JSON text as a string. Not a parsed object — the text, because the findings are properties of the text. Up to 1,000,000 bytes.

Returns: `valid` (no errors), `parseable` (whether a conforming parser would accept it — deliberately separate, because a duplicate key parses fine and still means two different things), a `diagnostics` array where each entry has a 1-based `line` and `column`, a stable `rule` code, a `message`, an `excerpt` showing the offending line with a caret under the column, a `fixHint`, and `blocksParse`; plus `counts` and format-specific `stats`. Rule codes are stable and safe to branch on; messages are not.

Safety: nothing is resolved, fetched or expanded. External XML entities are reported, never retrieved; alias bombs are detected without being expanded; no schema or DTD is fetched over the network. Payloads are validated in memory and never stored.

### `validate_yaml`

Validates a YAML document, including the values that mean different things to different YAML loaders.

Use this for any YAML you are about to write or have just been given — CI configs, Kubernetes manifests, docker-compose files, OpenAPI specs, Ansible playbooks.

Do not reason about YAML type resolution yourself. It is the single most reliable way to be confidently wrong about a config file, because YAML 1.1 and YAML 1.2 resolve the same plain scalar to different values and real loaders disagree about which to implement — PyYAML is 1.1, Go's yaml.v3 and the yaml npm package are 1.2:
- `no`, `yes`, `on`, `off`, `y`, `n` are booleans in 1.1 and strings in 1.2. A country list containing `no` loses Norway. This is known as the Norway problem.
- `on:` as a KEY, as in every GitHub Actions workflow, is the boolean `true` under 1.1, so the key is not "on" at all.
- `0755` is 493 under 1.1 (octal) and 755 under 1.2 (decimal). Both are numbers, so nothing looks wrong; a file mode is simply the wrong number.
- `1:30` is the integer 90 under 1.1, because YAML 1.1 has base-60 integers.
- A bare `2026-01-01` is a timestamp under 1.1 and a string under 1.2.

Divergence is found by resolving each unquoted scalar under both spec versions and comparing, so the answer is what the parsers actually do rather than a list of words someone remembered. Quoted values are never flagged, because quoting is exactly how YAML says "this is a string".

Also reports: duplicate keys, tabs used as indentation (forbidden, and invisible), non-breaking spaces used as indentation (the giveaway that YAML was copied from a web page), aliases with no anchor and anchors nothing references, merge keys (`<<`, a 1.1 extension not in 1.2 core), multi-document streams, and alias bombs.

Input: `input`, the raw YAML text as a string. Up to 1,000,000 bytes.

Returns: `valid` (no errors), `parseable` (whether a conforming parser would accept it — deliberately separate, because a duplicate key parses fine and still means two different things), a `diagnostics` array where each entry has a 1-based `line` and `column`, a stable `rule` code, a `message`, an `excerpt` showing the offending line with a caret under the column, a `fixHint`, and `blocksParse`; plus `counts` and format-specific `stats`. Rule codes are stable and safe to branch on; messages are not.

Safety: nothing is resolved, fetched or expanded. External XML entities are reported, never retrieved; alias bombs are detected without being expanded; no schema or DTD is fetched over the network. Payloads are validated in memory and never stored.

### `validate_xml`

Validates an XML document for well-formedness, namespace correctness, and the entity-based attacks that arrive as XML.

Use this before parsing XML you received, and when an XML document is being rejected by something that will not say why.

Do not eyeball this. Four classes of genuinely invalid XML are accepted by ordinary well-formedness checkers, so "it validated" does not mean what it appears to:
(1) Two root elements. `<a/><b/>` is not a valid XML document; XML permits exactly one outermost element. Concatenated records hit this constantly.
(2) Undeclared namespace prefixes. `<x:a>` with no `xmlns:x` is well-formed as raw XML and invalid under Namespaces in XML — so it passes a syntax check and is then rejected by XPath, XSLT, SOAP and every schema validator.
(3) Undeclared entities. XML predefines only five (`&lt; &gt; &amp; &apos; &quot;`). `&nbsp;` is an HTML entity and is simply undefined in XML.
(4) A bare `&`, almost always arriving inside a URL.

Security findings, which are the reason to run this on input you did not write: external entity declarations (XXE — reported with the URI they point at and the remediation for Python, Java and .NET), nested entity expansion (billion laughs), parameter entities (the out-of-band XXE vehicle), external DTD references (an SSRF vector and a runtime dependency on someone else's host), and any DOCTYPE at all, since hardened parsers reject them outright.

Input: `input`, the raw XML text as a string. Up to 1,000,000 bytes.

Returns: `valid` (no errors), `parseable` (whether a conforming parser would accept it — deliberately separate, because a duplicate key parses fine and still means two different things), a `diagnostics` array where each entry has a 1-based `line` and `column`, a stable `rule` code, a `message`, an `excerpt` showing the offending line with a caret under the column, a `fixHint`, and `blocksParse`; plus `counts` and format-specific `stats`. Rule codes are stable and safe to branch on; messages are not.

Safety: nothing is resolved, fetched or expanded. External XML entities are reported, never retrieved; alias bombs are detected without being expanded; no schema or DTD is fetched over the network. Payloads are validated in memory and never stored.

### `validate_csv`

Validates CSV text against RFC 4180 and reports ragged rows individually, with both field counts.

Use this before loading a CSV, and whenever a CSV-derived number looks wrong.

Do not attempt this by reading the file, and be aware that loading it successfully proves nothing. The failure that matters is the ragged row: a file where one row has six fields and the header has five loads without complaint almost everywhere — pandas pads or throws depending on the engine, Excel shifts the columns, and `split(",")` silently mis-assigns every field after the extra one. Nobody notices until a figure is wrong in a report. This reports it as "row 4813 has 6 fields; the header has 5", per row.

The other half is the delimiter. A European CSV is semicolon-separated because the comma is the decimal separator; reading it as comma-separated yields one column of nonsense and no error. The delimiter is sniffed from the header — ignoring quoted regions so their contents cannot vote — and always reported, with a warning when the guess was a close call. Pass `delimiter` to remove the guess entirely.

Also reports: unterminated quotes (which swallow the rest of the file into one field, which is why one typo can make thousands of rows look ragged), text after a closing quote, stray quotes in unquoted fields, duplicate column names, unnamed columns, column names with invisible leading or trailing whitespace, mixed CRLF/LF line endings, CR-only endings, and a byte order mark — which becomes part of the first column's name, so a lookup for "id" fails against a column that prints identically.

Input: `input`, the raw CSV text. Optional `delimiter` (a single character) and `hasHeader` (default true; pass false and rows are compared against the first row instead, and header checks are skipped). Up to 1,000,000 bytes.

Returns: `valid` (no errors), `parseable` (whether a conforming parser would accept it — deliberately separate, because a duplicate key parses fine and still means two different things), a `diagnostics` array where each entry has a 1-based `line` and `column`, a stable `rule` code, a `message`, an `excerpt` showing the offending line with a caret under the column, a `fixHint`, and `blocksParse`; plus `counts` and format-specific `stats`. Rule codes are stable and safe to branch on; messages are not.

Safety: nothing is resolved, fetched or expanded. External XML entities are reported, never retrieved; alias bombs are detected without being expanded; no schema or DTD is fetched over the network. Payloads are validated in memory and never stored.

### `validate_auto`

Detects whether a payload is JSON, YAML, XML or CSV, then validates it.

Use this when you have a blob of text and do not know what it is — a file with no extension, a clipboard paste, a response body with an unhelpful content type, or a config file whose format you would otherwise have to guess.

Detection is structural and the reason is always returned, so the assumption is visible rather than hidden: a leading `<` is XML, a leading `{` or `[` is JSON, a `%YAML` directive or `key: value` lines are YAML, and a consistent delimiter count across multiple lines is CSV. JSON is checked before YAML on purpose, because JSON is a strict subset of YAML 1.2 and every JSON document would otherwise be ambiguous.

If the detected format does not validate but JSON or XML does, the result is corrected and `detection.corrected` is true. Only those two can win a correction, because only they have decisive grammars — CSV will read almost any text as a valid single-column file, so "it validates as CSV" is not evidence, and allowing it would silently reinterpret broken JSON as fine.

Prefer the format-specific tool when you already know the format: it skips detection and cannot be corrected out from under you.

Input: `input`, the raw text. Up to 1,000,000 bytes.

Returns: `valid` (no errors), `parseable` (whether a conforming parser would accept it — deliberately separate, because a duplicate key parses fine and still means two different things), a `diagnostics` array where each entry has a 1-based `line` and `column`, a stable `rule` code, a `message`, an `excerpt` showing the offending line with a caret under the column, a `fixHint`, and `blocksParse`; plus `counts` and format-specific `stats`. Rule codes are stable and safe to branch on; messages are not. Additionally `detection` with the chosen `format`, the `reason` in one sentence, and `corrected`.

Safety: nothing is resolved, fetched or expanded. External XML entities are reported, never retrieved; alias bombs are detected without being expanded; no schema or DTD is fetched over the network. Payloads are validated in memory and never stored.

## Markdown representations

Every page is available as markdown at the same canonical URL. Send
`Accept: text/markdown` or append `?format=md`. Responses set
`Vary: Accept`. Do not parse the HTML.

## Docs

- [Documentation and MCP setup](https://payload-validator.gumballtools.com/docs): Copy-paste MCP config for Claude Code, Claude Desktop, and Cursor, plus curl examples.

## Pages

- [Payload Validator](https://payload-validator.gumballtools.com/): Validate JSON, YAML, XML and CSV — with the exact line, the rule, and the fix.
- [API and MCP setup](https://payload-validator.gumballtools.com/docs): JSON API reference and MCP configuration
- [JSON validator with exact line and column](https://payload-validator.gumballtools.com/validate/json): Reports every problem in one pass with a 1-based line and column, including the three that JSON.parse cannot report at all: duplicate keys, integer precision loss, and unpaired surrogates.
- [YAML validator that catches the 1.1 versus 1.2 traps](https://payload-validator.gumballtools.com/validate/yaml): Checks well-formedness, then reports the values that mean different things to different loaders — found by resolving each unquoted scalar under both spec versions and comparing, not by matching a list of suspicious words.
- [XML validator with namespace and XXE checks](https://payload-validator.gumballtools.com/validate/xml): Well-formedness plus the four classes of invalid XML that ordinary checkers accept, plus the entity-based attacks — reported, never resolved.
- [CSV validator that reports ragged rows individually](https://payload-validator.gumballtools.com/validate/csv): RFC 4180 scanning with the delimiter sniffed from the header. Ragged rows are reported per row with both field counts, because that is the entire answer.