SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP by olaservo · Pull Request #655 · modelcontextprotocol/modelcontextprotocol

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo · 2025-06-05T15:01:09Z

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 $schema field.

Changes

Updates specification documentation to specify JSON Schema 2020-12 as default
Adds guidance on explicit $schema field usage for alternative dialects
Clarifies schema validation requirements for tools with no parameters
Updates generated JSON schema files to declare 2020-12 as their meta-schema (patching in the schema generation script since typescript-json-schema only supports draft-07)

Historical Context

Original PR: June 5, 2025
Community Discussion: Multiple SDK maintainers and community members provided feedback leading to consensus on 2020-12
Closed: September 2025 (planned to be incorporated into SEP-834: Tools inputSchema & outputSchema conform to JSON Schema 2020-12 #881/SEP-834)
Reviewed: SEP-834 was discussed at the core maintainers meeting on 2025/09/17 (see comment here: SEP-834 Support full JSON Schema 2020-12 #834 (comment) )
Reopened: October 6, 2025 as standalone SEP-1613

Related Issues

Implements: SEP-1613
Related: SEP-834 (broader JSON Schema 2020-12 feature support)
Related: Discussion What AI applications would be like after using MCP? #366 (original compatibility issues)

Checklist

I have read the MCP Documentation
My code follows the repository's style guidelines
Documentation update
I have added or updated documentation as needed
Formal SEP created: SEP-1613: Establish JSON Schema 2020-12 as Default Dialect for MCP #1613

jba · 2025-06-05T16:06:41Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?
I think it should be the latter.

jviotti · 2025-06-05T16:13:42Z

Awesome! I made a couple little suggestions, but looks pretty good otherwise 💪🏻

jviotti · 2025-06-05T16:15:11Z

This is a good point from @jba though (maybe as a separate PR?)

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)?I think it should be the latter

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>

olaservo · 2025-06-05T19:42:14Z

Why is the default the older version of JSON Schema (draft7) instead of the newer one (2020-12)? I think it should be the latter.

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.

mikekistler · 2025-06-11T16:53:56Z

In case it benefits anyone else, I'll share this (AI generated) comparison of JSON Schema Draft-7 and Draft-2020-12:

Major Structural Changes

Draft-07 used a single monolithic specification document, while Draft 2020-12 split into modular specifications:

Core vocabulary
Validation vocabulary
Meta-data vocabulary
Format assertion vocabulary

Key New Features in Draft 2020-12

Vocabulary System: Introduced a formal vocabulary system allowing custom vocabularies and better extensibility. You can now define which vocabularies your schema uses via $vocabulary.

New Keywords:

unevaluatedProperties and unevaluatedItems - Handle properties/items not covered by other schema keywords
dependentSchemas and dependentRequired - Replace and expand on Draft-07's dependencies
maxContains and minContains - Provide bounds for contains validation
prefixItems - Validates array items by position (replaces positional array validation pattern)

Enhanced Conditionals: if/then/else logic works more intuitively with the new unevaluated keywords.

Breaking Changes

Dependencies Restructure: Draft-07's dependencies keyword is split into dependentSchemas and dependentRequired with slightly different semantics.

Array Validation: The way positional array validation works changed significantly with prefixItems replacing the old tuple validation pattern.

Format Behavior: Format validation became vocabulary-dependent rather than implementation-dependent.

Backward Compatibility

Schemas using only basic Draft-07 features will generally work, but schemas using dependencies or complex array validation patterns need updates. The meta-schema identifier changed from http://json-schema.org/draft-07/schema# to https://json-schema.org/draft/2020-12/schema.

Adoption Considerations

Draft 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

Kludex · 2025-06-13T15:00:07Z

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.

olaservo · 2025-11-13T14:31:13Z

+ - 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:


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.

@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

localden

LGTM for spec release.

cliffhall · 2025-11-14T21:24:05Z

 - `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)


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?

Good question, do you think its better not to link directly here?

I feel like @jonathanhefner might have ideas or thoughts on this? :)

cliffhall

LGTM! 👍

…ontextprotocol into clarify-json-schema-version

…heck counts Two upstream specReferences[].url strings in modelcontextprotocol/conformance point at files that no longer exist (verified curl 404): - SEP-986 cites SEP/SEP-986.md in the modelcontextprotocol repo; that path was removed when the SEP was merged into the spec. Now linking to the spec page itself at specification/draft/server/tools. - SEP-990-Enterprise-Managed-OAuth cites enterprise-oauth.mdx in ext-auth; the actual file is enterprise-managed-authorization.mdx. Now linking to the correct file. Added a SPEC_URL_OVERRIDES map in scripts/conformance-audit-report.ts so we keep tracking these locally until upstream's source is fixed. Each entry documents why and which upstream file holds the stale string. Drop entries as upstream fixes its references. Also: spell out the check-count column. 14P / 2F / 28I becomes 14 pass / 2 fail / 28 info — one column wider per row but no decoder ring needed when scanning the By SEP table. Snapshot regenerated. All URLs in the report now return 200 (one stays at 301: github.com/modelcontextprotocol/modelcontextprotocol/pull/655 redirects to the renamed modelcontextprotocol/modelcontextprotocol repo, harmless).

olaservo added 3 commits June 5, 2025 07:37

Add first pass at JSON schema version clarification
5015b6f

Add updated schemas
de40ca5

Merge branch 'main' into clarify-json-schema-version
8aaede2

olaservo requested review from bhosmer-ant, dsp-ant, ihrpr and tadasant June 5, 2025 15:21

jviotti reviewed Jun 5, 2025
View reviewed changes

Comment threaddocs/specification/draft/basic/index.mdx Outdated

jviotti reviewed Jun 5, 2025
View reviewed changes

Comment threaddocs/specification/draft/basic/index.mdx Outdated

olaservoand others added 2 commits June 5, 2025 09:15

Update docs/specification/draft/basic/index.mdx
29dc3d6
Co-authored-by: Juan Cruz Viotti <jv@jviotti.com>

Fix formatting
220eb46

olaservo requested a review from evalstate June 5, 2025 16:20

olaservo added 2 commits June 5, 2025 09:23

Use boolean set to true to indicate that a tool has no parameters
2747ccf

Merge branch 'main' into clarify-json-schema-version
d2e2f1d

jokemanfire mentioned this pull request Jun 11, 2025
MCP Tools writen by rust sdk can not use by LangGraph's MultiServerMCPClient modelcontextprotocol/rust-sdk#251
Closed

eiriktsarpalis reviewed Jun 12, 2025
View reviewed changes

Comment threaddocs/specification/draft/basic/index.mdx Outdated

dsp-ant moved this to In Review in Standards Track Jun 13, 2025

dsp-ant added this to Standards Track Jun 13, 2025

olaservo added 3 commits June 13, 2025 07:46

Merge branch 'main' into clarify-json-schema-version
3332e6e

Fix formatting
609cac1

Fix warning indent
b3593b0

bhosmer-ant modified the milestone: DRAFT 2025-06-XX Jun 16, 2025

olaservo commented Nov 13, 2025
View reviewed changes

olaservo added 11 commits November 14, 2025 05:24

Test ts-to-zod update in ci
5ecd51d

Merge branch 'main' ofhttps://github.com/modelcontextprotocol/modelc…
0c9f98e
…ontextprotocol into clarify-json-schema-version

Fix docstring
c1621d0

Merge branch 'main' into clarify-json-schema-version
9f9b3a1

Temporarily add even hackier version for posterity
5c4a992

De-zoddify
69adf1b

Go back to simple version
f870566

Merge branch 'main' into clarify-json-schema-version
45bc08f

Regenerate schema md
7ff1511

Remove accidentally generated file
49637ea

Clean up more zodded
eee9af6

localden previously approved these changes Nov 14, 2025
View reviewed changes

cliffhall reviewed Nov 14, 2025
View reviewed changes

cliffhall previously approved these changes Nov 14, 2025
View reviewed changes

olaservo added 2 commits November 14, 2025 15:57

Merge branch 'main' ofhttps://github.com/modelcontextprotocol/modelc…
7866033
…ontextprotocol into clarify-json-schema-version

Regenerate schemas
0aae433

olaservo dismissed stale reviews from cliffhall and localden via 0aae433November 14, 2025 23:00

Merge branch 'main' into clarify-json-schema-version
e9d025d

localden approved these changes Nov 14, 2025
View reviewed changes

localden merged commit 8ad0ac7 into modelcontextprotocol:mainNov 14, 2025
2 checks passed

felixweinberger mentioned this pull request Nov 18, 2025
SEP-1613: use.catchall() on inputSchema/outputSchema to support JSON Schema 2020-12 modelcontextprotocol/typescript-sdk#1135
Merged
9 tasks

pcarleton mentioned this pull request Jan 13, 2026
Consider adding client test for JSON Schema 2020-12 preservation (SEP-1613) modelcontextprotocol/conformance#101
Closed

github-actionsBot mentioned this pull request Jan 29, 2026
[in-review] SEP-834: SEP-834 Support full JSON Schema 2020-12joshrotenberg/tower-mcp#253
Closed
6 tasks

mwotton mentioned this pull request Feb 16, 2026
schema_for_type uses AddNullable which is non-compliant with JSON Schema 2020-12 modelcontextprotocol/rust-sdk#663
Closed

github-actionsBot mentioned this pull request Mar 9, 2026
[in-review] SEP-834: Support full JSON Schema 2020-12joshrotenberg/tower-mcp#697
Closed
3 tasks

claudeBot mentioned this pull request Jul 2, 2026
Add SEP-1613 (JSON Schema 2020-12 default dialect) requirement-traceability YAML modelcontextprotocol/conformance#391
Closed

lucarlig mentioned this pull request Aug 18, 2026
fix: update harness for latest dataplane contextforge-org/contextforge-dev-tools#4
Merged