Merge pull request modelcontextprotocol#655 from olaservo/clarify-json-schema-version

SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP

Author: localden

docs/specification/draft/basic/index.mdx

@@ -104,7 +104,7 @@ and instead retrieve credentials from the environment.
 Additionally, clients and servers **MAY** negotiate their own custom authentication and
 authorization strategies.
 
-For further discussions and contributions to the evolution of MCP’s auth mechanisms, join
+For further discussions and contributions to the evolution of MCP's auth mechanisms, join
 us in
 [GitHub Discussions](https://github.com/modelcontextprotocol/specification/discussions)
 to help shape the future of the protocol!
@@ -120,9 +120,61 @@ There is also a
 which is automatically generated from the TypeScript source of truth, for use with
 various automated tooling.
 
-### General fields
+## JSON Schema Usage
 
-#### `_meta`
+The Model Context Protocol uses JSON Schema for validation throughout the protocol. This section clarifies how JSON Schema should be used within MCP messages.
+
+### Schema Dialect
+
+MCP supports JSON Schema with the following rules:
+
+1. **Default dialect**: When a schema does not include a `$schema` field, it defaults to JSON Schema 2020-12 (`https://json-schema.org/draft/2020-12/schema`)
+1. **Explicit dialect**: Schemas MAY include a `$schema` field to specify a different dialect
+1. **Supported dialects**: Implementations MUST support at least 2020-12 and SHOULD document which additional dialects they support
+1. **Recommendation**: Implementors are RECOMMENDED to use JSON Schema 2020-12.
+
+### Example Usage
+
+#### Default dialect (2020-12):
+
+```json
+{
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "age": { "type": "integer", "minimum": 0 }
+  },
+  "required": ["name"]
+}
+```
+
+#### Explicit dialect (draft-07):
+
+```json
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "type": "object",
+  "properties": {
+    "name": { "type": "string" },
+    "age": { "type": "integer", "minimum": 0 }
+  },
+  "required": ["name"]
+}
+```
+
+### Implementation Requirements
+
+- Clients and servers **MUST** support JSON Schema 2020-12 for schemas without an explicit `$schema` field
+- Clients and servers **MUST** validate schemas according to their declared or default dialect. They **MUST** handle unsupported dialects gracefully by returning an appropriate error indicating the dialect is not supported.
+- Clients and servers **SHOULD** document which schema dialects they support
+
+### Schema Validation
+
+- Schemas **MUST** be valid according to their declared or default dialect
+
+## General fields
+
+### `_meta`
 
 The `_meta` property/parameter is reserved by MCP to allow clients and servers
 to attach additional metadata to their interactions.

docs/specification/draft/schema.mdx

@@ -194,14 +194,20 @@ A tool definition includes:
 - `title`: Optional human-readable name of the tool for display purposes.
 - `description`: Human-readable description of functionality
 - `inputSchema`: JSON Schema defining expected parameters
+  - Follows the [JSON Schema usage guidelines](/specification/draft/basic#json-schema-usage)
+  - Defaults to 2020-12 if no `$schema` field is present
+  - **MUST** be a valid JSON Schema object (not `null`)
+  - For tools with no parameters, use one of these valid approaches:
+    - `{ "type": "object", "additionalProperties": false }` - **Recommended**: explicitly accepts only empty objects
+    - `{ "type": "object" }` - accepts any object (including with properties)
 - `outputSchema`: Optional JSON Schema defining expected output structure
+  - Follows the [JSON Schema usage guidelines](/specification/draft/basic#json-schema-usage)
+  - Defaults to 2020-12 if no `$schema` field is present
 - `annotations`: optional properties describing tool behavior
 
 <Warning>
-
-For trust & safety and security, clients **MUST** consider
-tool annotations to be untrusted unless they come from trusted servers.
-
+  For trust & safety and security, clients **MUST** consider tool annotations to
+  be untrusted unless they come from trusted servers.
 </Warning>
 
 #### Tool Names
@@ -390,6 +396,56 @@ Providing an output schema helps clients and LLMs understand and properly handle
 - Guiding clients and LLMs to properly parse and utilize the returned data
 - Supporting better documentation and developer experience
 
+### Schema Examples
+
+#### Tool with default 2020-12 schema:
+
+```json
+{
+  "name": "calculate_sum",
+  "description": "Add two numbers",
+  "inputSchema": {
+    "type": "object",
+    "properties": {
+      "a": { "type": "number" },
+      "b": { "type": "number" }
+    },
+    "required": ["a", "b"]
+  }
+}
+```
+
+#### Tool with explicit draft-07 schema:
+
+```json
+{
+  "name": "calculate_sum",
+  "description": "Add two numbers",
+  "inputSchema": {
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "type": "object",
+    "properties": {
+      "a": { "type": "number" },
+      "b": { "type": "number" }
+    },
+    "required": ["a", "b"]
+  }
+}
+```
+
+#### Tool with no parameters:
+
+```json
+{
+  "name": "get_current_time",
+  "description": "Returns the current server time",
+  "inputSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}
+```
+
 ## Error Handling
 
 Tools use two error reporting mechanisms: