SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #655
Conversation
|
Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? |
|
Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻 |
|
This is a good point from @jba though (maybe as a separate PR?)
Maybe better to default to 2020-12 but still suggest support for previous versions in case some users need it? |
Co-authored-by: Juan Cruz Viotti <jv@jviotti.com>
Using draft-07 as default came from the original discussion where @jviotti recommended this approach. Since that was a general suggestion based on general tooling support, we still need to take into account MCP implementers' pending feedback on what would make the most sense to reduce the most schema validation challenges. |
|
In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12: Major Structural ChangesDraft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:
Key New Features in Draft 2020-12Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via New Keywords:
Enhanced Conditionals: Breaking ChangesDependencies Restructure: Draft-07's Array Validation: The way positional array validation works changed significantly with Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent. Backward CompatibilitySchemas using only basic Draft-07 features will generally work, but schemas using Adoption ConsiderationsDraft 2020-12 offers more powerful validation capabilities and better composability, but Draft-07 still has broader tooling support across languages and platforms. Consider your ecosystem's library support when choosing between versions. |
…no parameters more flexible
- Replace restrictive 'use true for tools with no parameters' guidance
- Provide multiple valid options: true, {}, {type: object}, etc.
- Include example showing how tools can use additional schema keywords
- Addresses comment about recommendation being too restrictive for tools
that may want to include other keywords beyond properties/required
|
To make it easier for implementers, I do think it makes more sense to use 2020-12. Pydantic (the data parsing library we use in the Python SDK) will by default use the version 2020-12 when converting to JSON. Having worked for a long time in the FastAPI ecosystem (which leverages the OpenAPI schema), and the amount of issues that were created because of draft-07, I would suggest we actually use the latest version of the spec by default. Also, it does add a lot of work to comply to another version. |
Co-authored-by: John McBride <jpmmcbride@gmail.com>
package.json
Outdated
| }, | ||
| "devDependencies": { | ||
| "@eslint/js": "^9.8.0", | ||
| "@olaservo/ts-to-zod": "^5.0.1-fix.1", |
There was a problem hiding this comment.
Note on this - there appears to be a bug in ts-to-zod that we hit during schema conversion. I opened a PR and let the maintainer know, and in the meantime have pointed this to my own fork,
I also chatted with @jviotti and I think we could always go back to doing a much simpler replacement instead on the draft-07 JSON file, if we don't expect anything truly special to come up in the TS schema in the future. Or alternatively try this for conversion: https://github.com/sourcemeta-research/alterschema
There was a problem hiding this comment.
We are also hoping to revamp the https://github.com/sourcemeta-research/alterschema project and make it part of https://github.com/sourcemeta/jsonschema at some point. For context, schema upgrades are typically easy, but there are some complex tricky edge cases on advanced cases that are very hard to handle, which is why the project is still on the sourcemeta-research org.
That said, you are far from hitting those edge cases, as the MCP schema is relatively simple. But hopefully, we have a 100% robust upgrade tool sometime soon.
There was a problem hiding this comment.
Given all this ^^ I'm inclined to go with the simpler sed-style approach for this spec release, then make upgrading the TS -> JSON transformation a dependency for future versions. Since we now know what its supposed to look like with the full transformation, we can see that we're not really missing anything by going this route.
There was a problem hiding this comment.
@dsp-ant I went back to a simpler script for this which just swaps out the schema and definitions for $defs. The other approach ended up being a lot more brittle and complex once it was all said and done. I'm thinking we can continue to improve the tooling here beyond the spec freeze to make it more future-proof. At least this way its easier to trace what's happening.
| - 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: |
There was a problem hiding this comment.
We chatted about whether this guidance is really needed here, since technically the schema for MCP already says that it has to be an object.
However, the original GitHub discussions showed widespread confusion around this, especially since JSON Schema 2020-12 would allow boolean schemas like true for no-parameter cases, but MCP requires an object. Given this is an MCP-specific restriction, it seems worth calling out explicitly in the spec verbiage.
There was a problem hiding this comment.
@dsp-ant I left this extra explanation in, but didn't add anything explicit for other schemas (such as output schemas) because this seemed to be the main need for extra clarification.
…ontextprotocol into clarify-json-schema-version
| - `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) |
There was a problem hiding this comment.
Will this link point to /draft/ now and be edited later to point to /2025-11-24/? How are such links being handled in general?
There was a problem hiding this comment.
Good question, do you think its better not to link directly here?
There was a problem hiding this comment.
I feel like @jonathanhefner might have ideas or thoughts on this? :)
…ontextprotocol into clarify-json-schema-version
16 participants
This PR implements SEP-1613, which establishes JSON Schema 2020-12 as the default dialect for embedded schemas within MCP messages.
Summary
Clarifies JSON Schema dialect usage for embedded schemas within MCP messages by establishing 2020-12 as the default dialect and allowing explicit dialect declaration via the
$schemafield.Changes
typescript-json-schemaonly supports draft-07)Historical Context
inputSchema&outputSchemaconform to JSON Schema 2020-12 #881/SEP-834)2020-12#834 (comment) )Related Issues
Checklist