{"openapi":"3.1.0","info":{"title":"Payload Validator","version":"1.0.0","summary":"Validate JSON, YAML, XML and CSV — with the exact line, the rule, and the fix.","description":"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.\n\n**Not for:** 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.\n\nFree tier: 250 calls per UTC day per caller. Past that, endpoints return 402 with x402 payment requirements. An MCP server exposing the same capabilities is available at https://payload-validator.gumballtools.com/api/mcp.\n\nAn invalid payload is a 200, not a 4xx. \"Your payload is broken\" and \"your request was broken\" are different problems, and a caller cannot tell them apart from a status code alone. 4xx is reserved for the request itself.","contact":{"url":"https://github.com/bwalvoord/gumball"}},"servers":[{"url":"https://payload-validator.gumballtools.com","description":"Production"}],"externalDocs":{"url":"https://payload-validator.gumballtools.com/llms-full.txt","description":"Full documentation for agents"},"paths":{"/api/v1/validate":{"get":{"operationId":"validate","summary":"Validate a payload","description":"Validates JSON, YAML, XML or CSV. Detects the format when none is given.\n\nGET puts the payload in the URL, which caps out around 8 KB — use POST for anything real. See the POST operation for the raw-body form.\n\nDetects whether a payload is JSON, YAML, XML or CSV, then validates it.\n\nUse 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.\n\nDetection 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.\n\nIf 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.\n\nPrefer the format-specific tool when you already know the format: it skips detection and cannot be corrected out from under you.\n\nInput: `input`, the raw text. Up to 1,000,000 bytes.\n\nReturns: `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`.\n\nSafety: 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.","parameters":[{"name":"input","in":"query","required":true,"description":"The raw document text. Up to 1,000,000 bytes.","schema":{"type":"string"}},{"name":"format","in":"query","required":false,"description":"The format to validate against, or \"auto\" to detect it. Defaults to auto. Prefer naming the format when you know it: detection cannot then be corrected out from under you.","schema":{"type":"string","enum":["json","yaml","xml","csv","auto"],"default":"auto"}},{"name":"delimiter","in":"query","required":false,"description":"CSV only. A single character. Omit to sniff it from the header. Pass it when you know it — a semicolon-separated file read as comma-separated produces one column and no error.","schema":{"type":"string","minLength":1,"maxLength":1}},{"name":"hasHeader","in":"query","required":false,"description":"CSV only. Whether the first row names the columns. Defaults to true. Pass false and rows are compared against the first row instead, and header checks are skipped.","schema":{"type":"boolean","default":true}}],"responses":{"200":{"description":"The validation result. Returned whether or not the payload is valid — check `valid` and `parseable`, not the status code.","content":{"application/json":{"schema":{"type":"object","required":["format","valid","parseable","diagnostics","counts","stats","summary"],"properties":{"format":{"type":"string","enum":["json","yaml","xml","csv"]},"valid":{"type":"boolean","description":"No errors. Well-formed and unambiguous."},"parseable":{"type":"boolean","description":"Whether a conforming parser accepts the input. Deliberately separate from `valid`: a duplicate key parses fine and still means two different things."},"diagnostics":{"type":"array","items":{"type":"object","required":["severity","rule","message","line","column","offset","excerpt","fixHint","blocksParse"],"properties":{"severity":{"type":"string","enum":["error","warning"],"description":"A warning means the payload is well-formed but two conforming parsers would disagree about what it means."},"rule":{"type":"string","description":"Stable dotted code, e.g. \"json.duplicate_key\". Safe to branch on; messages are not.","examples":["json.duplicate_key","yaml.version_divergence","csv.ragged_row"]},"message":{"type":"string"},"line":{"type":"integer","minimum":1,"description":"1-based, as editors report it."},"column":{"type":"integer","minimum":1,"description":"1-based, in UTF-16 code units."},"offset":{"type":"integer","minimum":0,"description":"0-based index into the input."},"excerpt":{"type":"string","description":"The offending source line with a caret under the column, as two lines."},"fixHint":{"type":"string","description":"What to change. Never empty."},"blocksParse":{"type":"boolean","description":"Whether a conforming parser would reject the document over this finding. False for an error means the document parses and is ambiguous."}}}},"counts":{"type":"object","required":["errors","warnings"],"properties":{"errors":{"type":"integer","minimum":0},"warnings":{"type":"integer","minimum":0}}},"stats":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"}]},"description":"Format-specific facts — key count, max depth, row count, delimiter, byte size. Includes diagnosticsOmitted when the list was capped at 200."},"summary":{"type":"string","description":"One-paragraph plain-language verdict."},"detection":{"type":"object","description":"Present only when format=auto was used.","required":["format","reason","corrected"],"properties":{"format":{"type":"string","enum":["json","yaml","xml","csv"]},"reason":{"type":"string","description":"Why this format was chosen, in one sentence."},"corrected":{"type":"boolean","description":"True when the structural guess failed to validate and JSON or XML did, so the result was reinterpreted."}}}}}}}},"400":{"description":"The request was malformed: no input, or an unknown format. Not used for an invalid payload.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}},"402":{"description":"Free quota of 250 calls per UTC day exhausted. Body is an x402 v1 payment requirement ($0.001 per call). While settlement is disabled the body carries payment_enabled: false and the call cannot be unblocked by paying — wait for quota.resetsAt.","content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"The payload exceeded 1,000,000 bytes.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}}}},"post":{"operationId":"validatePost","summary":"Validate a payload sent in the request body","description":"Two body forms.\n\nWith `Content-Type: application/json`, send `{\"input\": \"...\", \"format\": \"yaml\"}`. Query parameters still apply and the body wins where both are given.\n\nWith any other content type, the entire raw body is the payload and the format comes from the query string:\n\n```\ncurl --data-binary @config.yaml 'https://payload-validator.gumballtools.com/api/v1/validate?format=yaml'\n```\n\nThe raw form exists because escaping a file into a JSON string field is exactly the kind of step that introduces the problem you were trying to detect.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["input"],"properties":{"input":{"type":"string","description":"The raw document text."},"format":{"type":"string","enum":["json","yaml","xml","csv","auto"],"default":"auto"},"delimiter":{"type":"string","minLength":1,"maxLength":1},"hasHeader":{"type":"boolean","default":true}}}},"text/plain":{"schema":{"type":"string","description":"The raw document, as the whole body."}},"application/octet-stream":{"schema":{"type":"string","description":"The raw document, as the whole body."}}}},"responses":{"200":{"description":"The validation result. Returned whether or not the payload is valid — check `valid` and `parseable`, not the status code.","content":{"application/json":{"schema":{"type":"object","required":["format","valid","parseable","diagnostics","counts","stats","summary"],"properties":{"format":{"type":"string","enum":["json","yaml","xml","csv"]},"valid":{"type":"boolean","description":"No errors. Well-formed and unambiguous."},"parseable":{"type":"boolean","description":"Whether a conforming parser accepts the input. Deliberately separate from `valid`: a duplicate key parses fine and still means two different things."},"diagnostics":{"type":"array","items":{"type":"object","required":["severity","rule","message","line","column","offset","excerpt","fixHint","blocksParse"],"properties":{"severity":{"type":"string","enum":["error","warning"],"description":"A warning means the payload is well-formed but two conforming parsers would disagree about what it means."},"rule":{"type":"string","description":"Stable dotted code, e.g. \"json.duplicate_key\". Safe to branch on; messages are not.","examples":["json.duplicate_key","yaml.version_divergence","csv.ragged_row"]},"message":{"type":"string"},"line":{"type":"integer","minimum":1,"description":"1-based, as editors report it."},"column":{"type":"integer","minimum":1,"description":"1-based, in UTF-16 code units."},"offset":{"type":"integer","minimum":0,"description":"0-based index into the input."},"excerpt":{"type":"string","description":"The offending source line with a caret under the column, as two lines."},"fixHint":{"type":"string","description":"What to change. Never empty."},"blocksParse":{"type":"boolean","description":"Whether a conforming parser would reject the document over this finding. False for an error means the document parses and is ambiguous."}}}},"counts":{"type":"object","required":["errors","warnings"],"properties":{"errors":{"type":"integer","minimum":0},"warnings":{"type":"integer","minimum":0}}},"stats":{"type":"object","additionalProperties":{"oneOf":[{"type":"string"},{"type":"number"}]},"description":"Format-specific facts — key count, max depth, row count, delimiter, byte size. Includes diagnosticsOmitted when the list was capped at 200."},"summary":{"type":"string","description":"One-paragraph plain-language verdict."},"detection":{"type":"object","description":"Present only when format=auto was used.","required":["format","reason","corrected"],"properties":{"format":{"type":"string","enum":["json","yaml","xml","csv"]},"reason":{"type":"string","description":"Why this format was chosen, in one sentence."},"corrected":{"type":"boolean","description":"True when the structural guess failed to validate and JSON or XML did, so the result was reinterpreted."}}}}}}}},"400":{"description":"The request was malformed: no input, or an unknown format. Not used for an invalid payload.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}},"402":{"description":"Free quota of 250 calls per UTC day exhausted. Body is an x402 v1 payment requirement ($0.001 per call). While settlement is disabled the body carries payment_enabled: false and the call cannot be unblocked by paying — wait for quota.resetsAt.","content":{"application/json":{"schema":{"type":"object"}}}},"413":{"description":"The payload exceeded 1,000,000 bytes.","content":{"application/json":{"schema":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message","fix_hint","docs"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code."},"message":{"type":"string"},"fix_hint":{"type":"string","description":"What to change before retrying."},"field":{"type":"string"},"token":{"type":"string"},"examples":{"type":"array","items":{"type":"string"}},"docs":{"type":"string","format":"uri"}}}}}}}}}}}},"x-mcp":{"endpoint":"https://payload-validator.gumballtools.com/api/mcp","transport":"streamable-http","tools":[{"name":"validate_json","description":"Validates a JSON document and reports every problem with an exact line and column.\n\nUse 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.\n\nDo not do this by reading the JSON yourself. Three of the findings are invisible to inspection and to JSON.parse alike:\n(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.\n(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.\n(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.\n\nIt 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.\n\nInput: `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.\n\nReturns: `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.\n\nSafety: 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."},{"name":"validate_yaml","description":"Validates a YAML document, including the values that mean different things to different YAML loaders.\n\nUse 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.\n\nDo 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:\n- `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.\n- `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.\n- `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.\n- `1:30` is the integer 90 under 1.1, because YAML 1.1 has base-60 integers.\n- A bare `2026-01-01` is a timestamp under 1.1 and a string under 1.2.\n\nDivergence 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\".\n\nAlso 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.\n\nInput: `input`, the raw YAML text as a string. Up to 1,000,000 bytes.\n\nReturns: `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.\n\nSafety: 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."},{"name":"validate_xml","description":"Validates an XML document for well-formedness, namespace correctness, and the entity-based attacks that arrive as XML.\n\nUse this before parsing XML you received, and when an XML document is being rejected by something that will not say why.\n\nDo 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:\n(1) Two root elements. `<a/><b/>` is not a valid XML document; XML permits exactly one outermost element. Concatenated records hit this constantly.\n(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.\n(3) Undeclared entities. XML predefines only five (`&lt; &gt; &amp; &apos; &quot;`). `&nbsp;` is an HTML entity and is simply undefined in XML.\n(4) A bare `&`, almost always arriving inside a URL.\n\nSecurity 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.\n\nInput: `input`, the raw XML text as a string. Up to 1,000,000 bytes.\n\nReturns: `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.\n\nSafety: 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."},{"name":"validate_csv","description":"Validates CSV text against RFC 4180 and reports ragged rows individually, with both field counts.\n\nUse this before loading a CSV, and whenever a CSV-derived number looks wrong.\n\nDo 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.\n\nThe 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.\n\nAlso 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.\n\nInput: `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.\n\nReturns: `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.\n\nSafety: 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."},{"name":"validate_auto","description":"Detects whether a payload is JSON, YAML, XML or CSV, then validates it.\n\nUse 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.\n\nDetection 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.\n\nIf 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.\n\nPrefer the format-specific tool when you already know the format: it skips detection and cannot be corrected out from under you.\n\nInput: `input`, the raw text. Up to 1,000,000 bytes.\n\nReturns: `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`.\n\nSafety: 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."}]}}