Schema: Is draft 07 strictly followed?

[jokemanfire]

Pre-submission Checklist

• I have checked that this question would not be more appropriate as an issue in a specific repository
• I have searched existing discussions and documentation for answers

Question Category

• Protocol Specification
• SDK Usage
• Server Implementation
• General Implementation
• Documentation
• Other

Your Question

There is currently no clear indication in the spec file to follow the draft-07.
This has led to many conflicting parts in the development of SDKs, especially with mainstream clients such as cursor and claude or inspector using different schema, there have been some issues with the development of the SDK. Can the schema specification used be clearly specified in the spec file?

[Hendler]

As I learn MCP spec, I am looking for clarity, along with others, on

1. How implementations should handle null inputSchema between different implementations (code references) If this is null, is it going to do any param validation? Most tool endpoints must require a schema and do so by generating them for users automatically, sometimes with unexpected behaviors
2. The version of schema validation supported seems to cause issues between MCP implementations. In the Rust MCP, there is a JSON schema generator that used the OpenAPI spec, while some clients expected v2 or v3. Some validators don't enforce the spec the same way. So, even if they ingest the same spec, they enforce differently.
3. Perhaps unrelated, in one case, the hosted OpenAPI JSON schema v3 disappeared altogether, causing all validation to fail. Should validation failure be fatal or optional?

Hope these questions help the discussion.

[jviotti]

Hey there! I'm a TSC member of JSON Schema. To avoid ambiguity, as @jokemanfire pointed out, the MCP specification should clearly define what dialect of JSON Schema is in use. That could be JSON Schema Draft 7 or the newest JSON Schema 2020-12 dialect.

While a bit more advanced, this is how OpenAPI itself does it: https://spec.openapis.org/oas/latest.html#json-schema-keywords.

• The specification clearly states that OpenAPI follows JSON Schema 2020-12
• Maybe not applicable to MCP, but OpenAPI defines its own dialect based on JSON Schema 2020-12 with a custom vocabulary to define some additional OpenAPI specific extensions. These extensions follow the standard JSON Schema vocabulary mechanism (maybe useful to MCP at some point if you need to add your own custom keywords)

As some extra resources worth keeping an eye on:

• Bowtie (https://bowtie.report): A project by another member of TSC for tracking compliance of JSON Schema implementations across dialects. There you can see which tools properly support i.e. Draft 7 or 2020-12, and which ones fall a bit behind
• Learn JSON Schema (https://www.learnjsonschema.com/2020-12/): A project by me. It's an in-progress reference documentation site for JSON Schema. 2020-12 is fully documented but previous dialects not so much yet
• My JSON Schema CLI (https://github.com/sourcemeta/jsonschema): lots of little things to work with JSON Schema. Potentially useful for working with, linting, and testing schemas deployed alongside the specification (if any), etc

Of course, if the MCP team needs any assistance with JSON Schema, don't hesitate in reaching out to us. We are friendly :) https://json-schema.org

[Hendler]

Other notes and examples:

The spec mandates fatal validation and the error code – the Tools section’s Security Considerations says servers “MUST validate all tool inputs,” and the Error-Handling example shows JSON-RPC -32602 for invalid params. specification/2025-03-26/server/tools

Concrete bug triggered by empty or missing arguments – several SDKs (e.g., TypeScript v1.9.0) and clients (Windsurf) throw
[ { "code":"invalid_type", "expected":"object", "received":"undefined" … } ] when a no-arg tool’s inputSchema is null and the client omits {}. See typescript-sdk/issues/400 Server-side fix example – Supabase MCP server v0.3.5 patched this exact error, adding a fallback that injects an empty object for null-schema tools. supabase-mcp/releases

Anthropic production API is a strict outlier – it rejects any schema that isn’t Draft 2020-12, returning
“JSON schema is invalid. It must match JSON Schema draft 2020-12”
claude-code/issues/586 There's also a missing-type edge case – FastMCP can emit an argument schema without a root "type", and downstream adapters rewrite it to "", causing Anthropic to fail the tool list.
agno-agi/agno/issues/2791

Something related; OpenAPI-style "nullable": true is not legal JSON Schema – strict validators expect anyOf or ["T","null"];

A workaround for no-arg tools may be to publish or default to an explicitly empty schema, but seems a hack.
{ "$schema":"https://json-schema.org/draft/2020-12/schema", "type":"object", "properties":{} }

[GREsau]

Some related issues I found from a quick search:

• Improve JSON Schema explanation and add reference link in "Tool definition structure" section modelcontextprotocol#508
• McpServer builder extensions result in Tool InputSchema which isn't spec compliant csharp-sdk#342
• Tool.inputSchema does not cover actual values sent by servers modelcontextprotocol#156
• What's the official scheme for inputSchema? modelcontextprotocol#513
• Underspecified Tool Type python-sdk#528

And some options for MCP off the top of my head:

• Choose a specific version of JSON Schema (e.g. draft-07, or the current latest 2020-12) and mandate the use of that version
  • Can't make use of newer versions of JSON Schema when they're released, at least not without introducing a breaking change to MCP
• Require JSON Schemas within MCP documents to specify the version of JSON Schema, e.g. using the $schema keyword
  • Greater burden on MCP consumers, who must support multiple versions of JSON Schema
• Default to a specific version, but allow JSON Schemas within MCP documents to opt in to different versions, e.g. using the $schema keyword (similar to above)
• Use a custom subset of JSON Schema, e.g. limit supported keywords to type, properties, enum, items
  • May cause friction for MCP users trying to integrate with the rest of the JSON Schema ecosystem
  • Difficult (or impossible) to represent more complex type definitions e.g. tagged unions

[jviotti]

Default to a specific version, but allow JSON Schemas within MCP documents to opt in to different versions, e.g. using the $schema keyword (similar to above)

This is, in my opinion, the way to go. What some other standards do is exactly this. They define what the "default dialect" is if the schema does not explicitly state the one it's using. If the schema does declare an explicitly dialect, then it's up to the tooling maker to support anything beyond the default one. Most JSON Schema implementations do support a good range of dialects, so it shouldn't be too hard for MCP tooling to support many.

[jeremyfiel]

A workaround for no-arg tools may be to publish or default to an explicitly empty schema, but seems a hack.\n{ "$schema":"https://json-schema.org/draft/2020-12/schema\", "type":"object", "properties":{} }

An explicitly empty JSON Schema is

{
"$schema": "https://json-schema.org/draft/2020-12/schema"
}

This means the schema is unconstrained but defined as a 2020-12 complaint instance.

The problem with using type: object, properties:{} is you're constraining the instance to only be an object, which is different than "explicitly empty".

[Hendler]

A workaround for no-arg tools may be to publish or default to an explicitly empty schema, but seems a hack.\n{ "$schema":"[https://json-schema.org/draft/2020-12/schema](https://json-schema.org/draft/2020-12/schema%5C)", "type":"object", "properties":{} }

An explicitly empty JSON Schema is

{
"$schema": "https://json-schema.org/draft/2020-12/schema"
}

This means the schema is unconstrained but defined as a 2020-12 complaint instance.

The problem with using type: object, properties:{} is you're constraining the instance to only be an object, which is different than "explicitly empty".

Agreed @jeremyfiel .

Many MCP implementations come from strongly-typed languages where developers expect object properties to always exist (even if null), leading to schemas like:

{
 "type": "object",
 "properties": {
   "description": null,
   "annotations": null
 }
}

This creates validation failures across different JSON Schema validators and MCP clients (Anthropic's API, Windsurf, etc.). This is a hack to solve.

private removeNullValues(obj: any): any {
  if (obj === null || obj === undefined) return undefined;
  if (typeof obj !== 'object') return obj;
  if (Array.isArray(obj)) return obj.map(item => this.removeNullValues(item));
  
  const cleaned: any = {};
  for (const [key, value] of Object.entries(obj)) {
    const cleanedValue = this.removeNullValues(value);
    if (cleanedValue !== null && cleanedValue !== undefined) {
      cleaned[key] = cleanedValue;
    }
  }
  return cleaned;
}

We may need one or all of these:

• Mandate the suggested empty schema format: {"$schema": "https://json-schema.org/draft/2020-12/schema"}
• Require implementations to sanitize schemas before transmission or on reception
• Provide canonical examples for no-argument tools

[jviotti]

@Hendler Note that this is invalid JSON Schema. In no version JSON Schema allows a subschema to be null. Only an object or a boolean value:

{
 "type": "object",
 "properties": {
   "description": null,
   "annotations": null
 }
}