fix: default Zod v4 JSON Schema target to draft-2020-12 - #2653

Summary

mapMiniTarget in src/server/zod-json-schema-compat.ts defaults to 'draft-7' when no target is supplied. Neither call site in src/server/mcp.ts passes one (lines 151 and 165 pass only strictUnions/pipeStrategy), and target is never exposed through registerTool. So every tool schema generated from a Zod v4 schema advertises:

"$schema": "http://json-schema.org/draft-07/schema#"

This change makes the default 'draft-2020-12', and updates the unrecognised-target fallback on the last line to match — it also returned 'draft-7', so the two now agree:

 function mapMiniTarget(t: CommonOpts['target'] | undefined): 'draft-7' | 'draft-2020-12' {
-    if (!t) return 'draft-7';
+    if (!t) return 'draft-2020-12';
     if (t === 'jsonSchema7' || t === 'draft-7') return 'draft-7';
     if (t === 'jsonSchema2019-09' || t === 'draft-2020-12') return 'draft-2020-12';
-    return 'draft-7'; // fallback
+    return 'draft-2020-12'; // fallback
 }

The fallback is unreachable through the CommonOpts type — all four accepted values are handled by the two explicit branches — but it is reachable from JavaScript callers passing an off-type value, where silently downgrading the dialect is the same surprise this PR is fixing.

Why 2020-12 is the right default

1. The spec says so. src/spec.types.ts, on Tool.outputSchema:

   Defaults to JSON Schema 2020-12 when no explicit $schema is provided.

   The SDK currently contradicts the spec types vendored in the same tree.

2. Zod already defaults to it. Zod v4's toJSONSchema default target is draft-2020-12 — verified on zod 4.4.3:

   z4mini.toJSONSchema(s)                              -> "https://json-schema.org/draft/2020-12/schema"
   z4mini.toJSONSchema(s, {target:'draft-7'})          -> "http://json-schema.org/draft-07/schema#"
   

   The compat layer was overriding Zod's own default to an older dialect.

3. v2 already made this call. On main, packages/core-internal/src/util/standardSchema.ts:170:

   export const JSON_SCHEMA_CONVERSION_TARGET = 'draft-2020-12';

   This aligns v1.x with a decision already taken for v2.

Real-world impact

This surfaced as a client compatibility break. Claude Desktop began rejecting draft-07 outputSchema documents outright:

Tool 'count' has an invalid outputSchema: JSON Schema declares an unsupported dialect
("$schema": "http://json-schema.org/draft-07/schema#"). The default validator supports
JSON Schema 2020-12 only

The failure happens at tool registration, so every tool on an affected server becomes unusable, and the server process is never contacted. mongodb-mcp-server is one instance (mongodb-js/mongodb-mcp-server#1427, anthropics/claude-code#86142), but because draft-07 comes from this SDK's default rather than from server code, any SDK-based server on Zod v4 declaring outputSchema is affected, and no server-side option exists to opt out.

To be clear: that client is too strict — draft-07 is valid JSON Schema, and the v2 SDK's own validator accepts draft-07, draft-06, 2019-09 and 2020-12. This PR isn't a workaround for that bug; it's aligning the default with the spec, Zod, and v2. It happens to also unblock affected users.

Scope and compatibility

• Explicit targets are unchanged. target: 'draft-7' and 'jsonSchema7' still produce draft-07; the mapping is untouched.
• Zod v3 is unchanged and still emits draft-07. The v3 branch delegates to zod-to-json-schema, whose targets are jsonSchema7 / jsonSchema2019-09 / openApi3 — there is no 2020-12 target available. A test documents this v3/v4 asymmetry so it reads as intentional.
• Behavior change note: consumers who relied on the implicit draft-07 default for Zod v4 schemas will now see 2020-12. For the 2019-09→2020-12 delta involved, clients validating draft-07 documents generally accept 2020-12; and per the spec text above, 2020-12 is what clients should assume when $schema is absent.

If you'd prefer a narrower change, the alternative is passing target: 'draft-2020-12' only at the outputSchema call site (src/server/mcp.ts:165), leaving inputSchema on draft-07. I went with the shared default since the asymmetry seemed harder to justify than the alignment. Happy to switch.

Testing

New file test/server/zod-json-schema-compat.test.ts (6 tests):

• Zod v4 with no target → 2020-12 (the fix)
• explicit 'draft-7' / 'jsonSchema7' → draft-07 (opt-in preserved)
• explicit 'draft-2020-12' / 'jsonSchema2019-09' → 2020-12
• unrecognised target (cast from JS) → 2020-12 (the fallback)
• Zod v3 with no target → draft-07 (documents the vendored-converter limit)
• end-to-end tools/list over InMemoryTransport asserting both inputSchema.$schema and outputSchema.$schema are 2020-12

Full suite: 1645 tests / 53 files passing, npm run lint clean. No existing test asserted the draft-07 dialect.