json_schema_validate MCP tool: JSON Schema in AI agents

“Does this payload match our API schema?” sounds like a question a model can answer by reading both documents. For a short schema it often can. For a real one, with $refs, oneOf branches, required lists in three places and a pattern on every identifier, reading isn’t checking. The model will say “looks valid” about a document that fails on a field it never got to.

The devtoolbox.cc MCP server includes json_schema_validate, a real JSON Schema validator that the assistant can call on your files. It’s the same validator as the JSON Schema tool on this site and supports drafts 4, 7, 2019-09 and 2020-12. Setup instructions are on the MCP page.

What the tool reports

The tool takes a schema and a document, both either inline or as file paths, and gives one of three answers:

• Valid: the document matches, with the draft that was used.
• Invalid: every error, each with a JSON Pointer to the failing value in the document, a readable message, the keyword that failed and where that keyword sits in the schema.
• The schema itself is invalid: if the schema breaks the rules of its own draft (an unknown type, a minimum that’s a string), the tool reports that and doesn’t validate the data against a broken schema.

The draft is read from the schema’s $schema keyword, or set explicitly. Format checks for email, date-time, uri and the other standard formats are on by default and can be switched off.

Invalid data is a normal result, not a tool failure. The call succeeds and the text starts with “Invalid”. Tool errors are reserved for problems such as unreadable files or a schema that isn’t JSON at all.

Arguments

Argument	Type	Meaning
schema	string	The schema as JSON text. Use this or schema_path.
schema_path	string	A local schema file.
data	string	The JSON to validate. Use this or data_path.
data_path	string	A local data file.
draft	"auto", "2020-12", "2019-09", "7", "4"	Default "auto" (from $schema, else 2020-12).
formats	boolean	Check format keywords. Default true.

Examples

These examples were run against the real tool. The schema describes a user record:

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "required": ["id", "email", "roles"],
  "properties": {
    "id": { "type": "integer", "minimum": 1 },
    "email": { "type": "string", "format": "email" },
    "roles": { "type": "array", "items": { "enum": ["admin", "editor", "viewer"] }, "minItems": 1 }
  },
  "additionalProperties": false
}

A record with several problems:

{ "id": 0, "email": "anna-at-example.com", "roles": ["owner"], "team": "core" }

{ "schema_path": "/home/dev/api/user.schema.json", "data_path": "/home/dev/api/user.json" }

Invalid: 4 errors (draft 2020-12).
- /id: 0 is less than 1 (minimum at #/properties/id/minimum)
- /email: String does not match format "email" (format at #/properties/email/format)
- /roles/0: Instance does not match any of ["admin","editor","viewer"] (enum at #/properties/roles/items/enum)
- /team: Property "team" is not allowed (additionalProperties at #/additionalProperties)

Every error is listed, not just the first, so the model can fix them all in one go. A corrected record passes:

{
  "schema_path": "/home/dev/api/user.schema.json",
  "data": "{\"id\": 7, \"email\": \"anna@example.com\", \"roles\": [\"editor\"]}"
}

Valid: the data matches the schema (draft 2020-12).

When the schema is the problem, the tool says so before looking at the data. Here "type": "text" isn’t a JSON Schema type:

{
  "schema": "{\"type\": \"object\", \"properties\": {\"name\": {\"type\": \"text\"}}}",
  "data": "{\"name\": \"Anna\"}"
}

The schema itself is invalid (draft 2020-12); the data was not validated:
- /properties/name/type: Invalid "type": use string, number, integer, boolean, object, array or null (or an array of them) (anyOf at #/allOf/1/$ref/properties/properties/additionalProperties/$ref/allOf/3/$ref/properties/type/anyOf)

And when one of the inputs isn’t valid JSON, the call fails with the position of the syntax error:

{ "schema_path": "/home/dev/api/user.schema.json", "data": "{\"id\": 7,}" }

Invalid JSON in the data at line 1, column 10: Unexpected character "}", expected a double-quoted property name

Drafts are not interchangeable

The draft decides what some keywords mean. In draft 7, items with an array of schemas validates a tuple. In 2020-12 that job moved to prefixItems, and items with an array is a schema error. Draft 4 writes exclusiveMinimum as a boolean next to minimum; later drafts use a number. A schema written for one draft and validated as another can pass or fail for the wrong reasons, which is why the tool reads $schema and prints the draft it used in every answer.

Formats are another difference. Since 2019-09 the specification treats format as an annotation unless a validator is configured to assert it. This tool asserts formats by default, because that’s what most people expect when they write "format": "email". Pass "formats": false to match a validator that only annotates.

Things to ask your assistant

• “Validate every file in fixtures/ against schema/order.json and summarise which ones fail and why.”
• “Our client sent request.json. Does it match openapi-components/Customer.schema.json?”
• “Write a JSON Schema for sample.json, then validate sample.json against it to check the schema.”
• “Fix config.json so it passes config.schema.json, and validate again afterwards.”

The last two show why a tool helps even when the model writes the schema itself. The assistant can test its own work and keep going until the validator agrees, instead of handing you a schema that has never been run.

For one-off checks, the JSON Schema validator on this site shows the same errors in the browser, next to both documents. If the data won’t parse, the JSON formatter points at the syntax error first.

Numbers and limits

The JSON is parsed exactly, so a long integer doesn’t change before validation. The validation library compares numbers as floating point, though, so a const or maximum that relies on digits beyond 2^53 is checked approximately. The web tool’s help text mentions the same limit. References to other schemas by URL aren’t fetched, because the tool never touches the network: bundle referenced schemas into one file, or put them under $defs.

Install

json_schema_validate is one of 15 tools in the devtoolbox.cc MCP server, which runs locally and makes no network requests. Schemas and payloads stay on your computer. Claude Desktop, Claude Code, Cursor and VS Code setup is on the MCP install page.