SEP-834 Support full JSON Schema `2020-12`

[jpmcb]

Preamble

Title: Support full JSON Schema 2020-12
Co-author: John McBride - @jpmcb
Co-author: Ola Hungerford - @olaservo (adopted from #655 per #881 (comment))
Status: proposal
PR: #881

Abstract

There's a major discrepancy with how 2025-06-18 handles structuredContent in relation to outputSchema being defined as JSON Schema.

Because structuredContent must be an object, the types that can be returned by servers and validated by clients (like type: array which is fully supported by JSON Schema but throws errors in Inspector, the Typescript-SDK, etc) is dramatically narrow.

Further, which draft of JSON Schema clients and servers use is not well defined leading to general drift among client, SDK, and server implementations. For example, JSON Schema specs in one client that uses JSON Schema draft-07 will be very different from another that uses 2020-12.

Related:

• outputSchema does not fully support JSON Schema inspector#552
• Tool inputSchema and outputSchema do not support JSON Schema typescript-sdk#685
• Support JSON Schema allOf, oneOf, etc. inspector#496

This SEP loosens JSON schema usage across clients and servers as well as defines using JSON Schema 2020-12

Motivation

In 5.1 Data Types: Tool, the spec states:

outputSchema: Optional JSON Schema defining expected output structure

JSON Schema may be of type object, array, string, null, etc. etc. If it's valid JSON, then JSON Schema can validate it.

But the spec then goes on, in 5.2.6 Structured Content, to state:

Structured content is returned as a JSON object in the structuredContent field of a result.

This represents a dramatic discrepency and severly limits what type of content can be returned by a server and validated in the structured content.

Consider the following valid JSON Schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "properties": {
      "id": {
        "type": "string",
        "description": "A unique UUID"
      }
    },
    "required": ["id"],
    "additionalProperties": false
  }
}

which defines an array of objects where the objects must have an id property. This is pretty typical, especially in "list" type of operations.

Now, suppose a server responds with the following JSON as structured content:

[
  { "id": "abc123" },
  { "id": "xyz987" }
]

The spec would consider this structured content invalid and non-verifiable by the output schema.

---

Originally, the MCP specification didn't explicitly state which JSON Schema version to use for tool inputSchema/outputSchema and elicitation requestedSchema, causing compatibility issues between implementations. Different clients and servers assume different versions, leading to validation failures and runtime errors. See: https://github.com/orgs/modelcontextprotocol/discussions/366 (discussion includes links to related issues)

(original context before merged with this SEP: #655)

Specification

• 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.
• Loosens inputSchema to be an object with type: object and any additional property to support JSON schema Draft 2020-12 and more powerful validation compositions (like anyOf, oneOf, etc.)
• Loosens outputSchema to fully support JSON Schema 2020-12 since MCP servers may return any valid JSON.
  • Loosens structuredContent to support any JSON validated by outputSchema's JSON Schema.

PR: #881

Backward Compatibility

No breaking changes.

Existing schemas without $schema will default to 2020-12. Servers can optionally add $schema to use other dialects.

Object schemas will continue to work as expected while the loosened specification can accept other valid JSON schema (like arrays of objects, etc.)

Rationale

The expectation is that any 2020-12 JSON Schema should be valid for fields that expect JSON schema. This includes outputSchema and structuredContent to be authentically validated by outputSchema, not just expected to always be an object: this is far too strict and narrows how tools can respond in ways that backends may not conform to. Further, 2020-12 has been widely adopted by the industry as the current standard but servers can define the schema they expect via the $schema metadata field.

Reference Implementation

TODO

Security Implications

There are no security implications.

[jpmcb]

Related discussion in the original RFC I'd like to surface: #371 (comment)

Thinking about this, given that outputSchema is any arbitrary json schema (which makes sense), should this be of type any rather than an object,i.e. should we omit the type=object? It would make sense for eg if the tool just returns an int or even an array. This as is will prevent an array of objects from being returned for eg. even though you could describe it in json schema.

@sambhav

on balance I think the sticking with the top-level-object restriction in the rest of the protocol (and standard practice more generally) is worth the extra trouble of wrapping top-level primitives/arrays

@bhosmer-ant

---

In my opinion, keeping an object top level primitive opinion in the specification makes for a really challenging end-developer experience and will narrow the capabilities of downstream clients: are we to expect that clients can't use generic JSON Schema libraries and, instead, have to stick with a custom solution that expects objects throughout?

[bhosmer-ant]

@jpmcb Hi John - not sure what you mean by "can't use generic JSON Schema libraries", the usual ones should work fine, this just constrains what gets fed through them. The motivation for the object restriction was to observe what seems to be a convention on the part of many libraries and frameworks in this space (that transferred data will always be objects). The extra burden - tools wanting to return non-object data need to wrap it in an object - seems pretty minor compared to being in a position where an intake pipeline would need to be customized to accept non-object data.

That said, if you're thinking of concrete examples where this will cause real pain of a kind we hadn't anticipated, can you elaborate?

[jpmcb]

Arrays of objects are probably the most likely use case.

Let's take some weather data I've been working with that gets returned by an API in a MCP server as an example. The idea is that this is the aggregate over a number of hours of weather forecasts.

MCP client <--> MCP server <--> Weather API

Say I want to feed back this array of data to an MCP client as a structured array of objects:

[
  { hour: 0, precip: 0.82, cloud_cover: 0.99 ... },
  { hour: 1, precip: 0.82, cloud_cover: 0.99 ... },

  // etc. etc.

  { hour: 6, precip: 0.82, cloud_cover: 0.99 ... },
  { hour: 7, precip: 0.82, cloud_cover: 0.99 ... },
]

This is clean, easy to understand, and conforms to the API usage that the MCP server has.

I can't do that out of the box if it's forced to be an object.

Wrapping it in an object seems like an unnecessary conformity with 1 key in the object:

{
  results: [
    { hour: 0, precip: 0.82, cloud_cover: 0.99 ... },
    { hour: 0, precip: 0.82, cloud_cover: 0.99 ... },

    // etc. etc.

    { hour: 6, precip: 0.82, cloud_cover: 0.99 ... },
    { hour: 7, precip: 0.82, cloud_cover: 0.99 ... },
  ]
}

results is basically meaningless since it could just as easily be destructured to a single array of objects. Good API design would dictate that we remove `results and not have an unnecessary top level object.

You can find this all over the place:

• GItHub's events APIs return a list of event objects
• Accuweather's apis return a list of locations when searched

---

tools wanting to return non-object data need to wrap it in an object

Why the restriction? It seems like an unnecessary piece of abstraction when JSON schema already supports valid JSON. My point being, outputSchema cannot really be "JSON schema" if it doesn't even support arrays.

This overall leads to poor server developer experience because I can't take advantage of the full breadth and depth of outputSchema being JSON schema because structuredContent is restricted to an object.

[bhosmer-ant]

@jpmcb fair point about API endpoints that return lists being easy to find. Since the main motivation for the restriction was reducing client burden, I think it's worth taking the temperature of client implementors w.r.t. how well-grounded this consideration is (started a thread about this on Discord). And yeah, definitely worth considering relaxing the restriction if it turns out not to be useful from their POV.

[dsp-ant]

Thanks for bringing this up. I think it's a reasonable request and @bhosmer-ant appraoch to asking client implementors seems worth it. @jpmcb would you be up to creating a SEP (you can just change this issue with the more formal template).

[jpmcb]

@dsp-ant - I've already cut an RFC here: #881 before the SEP process was in place.

I can go back and transform it into a SEP if you'd like but this RFC is ready to go in.

[JMLX42]

Further, which draft of JSON Schema clients and servers use is not well defined leading to general drift among client, SDK, and server implementations. For example, JSON Schema specs in one client that uses JSON Schema draft-07 will be very different from another that uses 2020-12.

Implementor here. I'm the developer of rmcp-openapi, which uses the rmcp Rust crate (the official Rust MCP SDK) to create an MCP <=> OpenAPI bridge.

To workaround the discrepancies with what the MCP schema expects, I had to implement the following quirks:

• https://gitlab.com/lx-industries/rmcp-openapi/-/blob/2ba2be02c7b433a4cedd573770fc35c35b87582c/crates/rmcp-openapi/src/tool_generator.rs#L1050
• https://gitlab.com/lx-industries/rmcp-openapi/-/blob/2ba2be02c7b433a4cedd573770fc35c35b87582c/crates/rmcp-openapi/src/tool_generator.rs#L1050
• https://gitlab.com/lx-industries/rmcp-openapi/-/blob/2ba2be02c7b433a4cedd573770fc35c35b87582c/crates/rmcp-openapi/src/tool_generator.rs#L1162

To make things simpler for implementors, IMHO the best solution is to use what OpenAPI does to leverage the existing ecosystem. Which is 2020-12 based on the OpenAPI specification:

In order to properly handle Schema Objects, OAS 3.1 inherits the parsing requirements of JSON Schema Specification Draft 2020-12, with appropriate modifications regarding base URIs as specified in Relative References In URIs.