fix(validators): honor declared 2019-09/draft-07/06 JSON Schema dialects

The default validator rejected any schema declaring a non-2020-12
$schema, so tools from servers emitting zod-to-json-schema output
failed pre-wire with InvalidParams before a request was ever sent —
its default target stamps draft-07 (e.g. the Filesystem reference
server), and its 2019-09/openAi targets stamp 2019-09.

Dispatch on the declared dialect instead, via a classifier shared by
both providers: no $schema or 2020-12 keeps the 2020-12 engine,
2019-09 validates with Ajv2019 (native 2019-09 on the cfworker
provider), draft-07/06 validate with a draft-07 engine (Ajv classic
on Node, draft '7' on cfworker), and unknown dialects still throw the
typed error, now listing the supported dialects. Caller-supplied
engines and explicit { draft } continue to bypass the dispatch.

The 2025-era outputSchema wrapper's $ref rewriter learns the same
vocabulary: draft-07 'dependencies' is a name-to-subschema map, and a
fragment-only $id does not establish a new resolution base, so wrapped
draft-07 schemas project correctly instead of failing to compile. The
known classic-Ajv deviation on $ref sibling keywords (evaluated,
stricter than draft-07's ignore rule, matching v1's default engine) is
documented and pinned by a test.

Author: felixweinberger

.changeset/validator-dialect-dispatch.md

@@ -0,0 +1,6 @@
+---
+'@modelcontextprotocol/server': patch
+'@modelcontextprotocol/client': patch
+---
+
+The default validator now honors declared 2019-09 and draft-07/06 dialects instead of rejecting them: a schema stamped `"$schema": "http://json-schema.org/draft-07/schema#"` (zod-to-json-schema's default output) validates with draft-07 semantics, and a 2019-09 stamp (zod-to-json-schema's `2019-09`/`openAi` targets) with 2019-09 semantics, on both the Ajv and Cloudflare Workers providers. Schemas with no `$schema` still validate as 2020-12, and unknown dialects still produce the typed error (now listing the supported dialects: 2020-12, 2019-09, draft-07, draft-06).

docs/migration/upgrade-to-v2.md

@@ -707,10 +707,9 @@ the host side and register the result with `fromJsonSchema()`: zod-4 input via z
 own `z.toJSONSchema(z.object(shape), { io: 'input', target: 'draft-2020-12' })` (the
 conversion is runtime-structural, so a zod ≥4.2 in the host handles schemas built by a
 different zod-4 copy), zod-3 input via the
-[`zod-to-json-schema`](https://www.npmjs.com/package/zod-to-json-schema) package. Strip
-the `$schema` member from the converted output before passing it to `fromJsonSchema()`
-— `zod-to-json-schema` stamps a draft-07 `$schema` by default, and the default
-validator [accepts 2020-12 only](#json-schema-2020-12-posture-sep-1613-sep-2106).
+[`zod-to-json-schema`](https://www.npmjs.com/package/zod-to-json-schema) package. Its
+default draft-07 `$schema` stamp is fine as-is — the default validator
+[honors declared draft-07/06 dialects](#json-schema-2020-12-posture-sep-1613-sep-2106).
 
 How a too-old zod surfaces depends on which entry point your code imports. With
 main-entry `import { z } from 'zod'` on a zod-3 range, the project **typechecks cleanly
@@ -1455,23 +1454,29 @@ classes — import it from one package consistently within a process.
 
 #### JSON Schema 2020-12 posture (SEP-1613, SEP-2106)
 
-The default validator supports **JSON Schema 2020-12 only**. On Node it is now `Ajv2020`
-instead of draft-07 `Ajv`; the Cloudflare Workers default was already 2020-12. Schemas
-declaring a different `$schema` are rejected with `Error("…unsupported dialect…")`.
+The default validator dispatches on the schema's declared `$schema`: absent or 2020-12
+validates as **JSON Schema 2020-12** — on Node via `Ajv2020` instead of v1's draft-07
+`Ajv` (the Cloudflare Workers default was already 2020-12) — a declared 2019-09
+`$schema` validates with 2019-09 semantics (`Ajv2019`), and a declared draft-07 or
+draft-06 `$schema` validates with draft-07 semantics. Schemas declaring any other
+`$schema` are rejected with `Error("…unsupported dialect…")`. One known draft-07 engine
+difference: the Node engine (classic Ajv, same as v1's default) evaluates keywords
+adjacent to `$ref`, stricter than draft-07's ignore-siblings rule; the browser/Workers
+engine ignores them per spec.
 
 `CallToolResult.structuredContent` is widened from `{ [k: string]: unknown }` to
 `unknown` (SEP-2106 lifts the `type:"object"` root restriction). The presence check is
 `!== undefined`, not falsy (`null` / `0` / `false` / `""` are legal values now). External
 `$ref` is not dereferenced (unchanged from v1; Ajv throws `MissingRefError` at compile,
 surfaced per-tool on `callTool`).
 
-| v1 pattern                                                         | Mechanical fix                                                                                                                                                                                         |
-| ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `result.structuredContent.<key>` / `result.structuredContent?.<k>` | narrow first: `const sc = result.structuredContent; if (typeof sc === 'object' && sc !== null && '<k>' in sc) { sc.<k> }`                                                                              |
-| `if (!result.structuredContent)`                                   | `if (result.structuredContent === undefined)`                                                                                                                                                          |
-| relying on default `Ajv` being draft-07                            | `new AjvJsonSchemaValidator(new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }))` (import `Ajv`, `addFormats`, `AjvJsonSchemaValidator` from `…/validators/ajv`) |
-| draft-07 idioms via `fromJsonSchema(schema)`                       | `fromJsonSchema(schema, new AjvJsonSchemaValidator(ajv))` — the `McpServer`/`Client` `jsonSchemaValidator` option does **not** reach `fromJsonSchema`-authored schemas                                 |
-| `outputSchema` / `inputSchema` with absolute-URI `$ref`            | inline under `$defs` and reference with `#/$defs/Name`                                                                                                                                                 |
+| v1 pattern                                                                                                   | Mechanical fix                                                                                                                                                                                         |
+| ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `result.structuredContent.<key>` / `result.structuredContent?.<k>`                                           | narrow first: `const sc = result.structuredContent; if (typeof sc === 'object' && sc !== null && '<k>' in sc) { sc.<k> }`                                                                              |
+| `if (!result.structuredContent)`                                                                             | `if (result.structuredContent === undefined)`                                                                                                                                                          |
+| draft-07 idioms **without** a declared `$schema` (a declared draft-07/06 `$schema` dispatches automatically) | `new AjvJsonSchemaValidator(new Ajv({ strict: false, validateFormats: true, validateSchema: false, allErrors: true }))` (import `Ajv`, `addFormats`, `AjvJsonSchemaValidator` from `…/validators/ajv`) |
+| undeclared draft-07 idioms via `fromJsonSchema(schema)`                                                      | `fromJsonSchema(schema, new AjvJsonSchemaValidator(ajv))` — the `McpServer`/`Client` `jsonSchemaValidator` option does **not** reach `fromJsonSchema`-authored schemas                                 |
+| `outputSchema` / `inputSchema` with absolute-URI `$ref`                                                      | inline under `$defs` and reference with `#/$defs/Name`                                                                                                                                                 |
 
 A tool may now register an `outputSchema` whose root is `type:"array"`, `type:"string"`,
 etc.; toward 2025-era clients the codec wraps it in a `{result:…}` envelope, and toward

packages/core-internal/src/validators/ajvProvider.ts

@@ -3,21 +3,13 @@
  */
 
 import { Ajv as Draft7Ajv } from 'ajv';
+import { Ajv2019 } from 'ajv/dist/2019.js';
 import { Ajv2020 } from 'ajv/dist/2020.js';
 import _addFormats from 'ajv-formats';
 
+import { declaredDialect } from './dialects';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types';
 
-/**
- * Canonical 2020-12 `$schema` URIs (http + https variants, trailing-`#` stripped). When a schema
- * declares anything else, the default provider throws a plain `Error` with a clear message rather
- * than letting the engine crash on an opaque internal error or silently mis-validate.
- */
-const DRAFT_2020_12_URIS: ReadonlySet<string> = new Set([
-    'https://json-schema.org/draft/2020-12/schema',
-    'http://json-schema.org/draft/2020-12/schema'
-]);
-
 /** Structural subset of the AJV interface used by {@link AjvJsonSchemaValidator}. */
 interface AjvLike {
     compile: (schema: unknown) => AjvValidateFunction;
@@ -35,8 +27,8 @@ interface AjvValidateFunction {
 /** `ajv-formats` default export, normalised through the CJS/ESM interop wrapper. */
 const addFormats = _addFormats as unknown as typeof _addFormats.default;
 
-function createDefaultAjvInstance(): AjvLike {
-    const ajv = new Ajv2020({
+function createDefaultAjvInstance(engineClass: typeof Ajv2020 | typeof Ajv2019 | typeof Draft7Ajv): AjvLike {
+    const ajv = new engineClass({
         strict: false,
         validateFormats: true,
         validateSchema: false,
@@ -50,8 +42,13 @@ function createDefaultAjvInstance(): AjvLike {
  * AJV-backed JSON Schema validator. See `@modelcontextprotocol/{client,server}/validators/ajv`
  * for the customisation entry point (re-exports `Ajv` and `addFormats` from the bundled copy).
  *
- * Default validates as **JSON Schema 2020-12** (SEP-1613). Schemas declaring a different
- * `$schema` are rejected with a plain `Error`; pass a pre-configured Ajv instance to validate
+ * Default dispatches on the schema's declared dialect: no `$schema` or 2020-12 → `Ajv2020`
+ * (SEP-1613); 2019-09 → `Ajv2019`; draft-07 or draft-06 → the classic draft-07 `Ajv` class
+ * (draft-07's changes over draft-06 are additive, so one engine covers both). Known draft-07 deviation: classic Ajv
+ * evaluates keywords adjacent to `$ref` (stricter than draft-07's ignore-siblings rule, matching
+ * v1's default engine), while the cfworker provider ignores them per spec.
+ * Schemas declaring any other `$schema` are
+ * rejected with a plain `Error`; pass a pre-configured Ajv instance to validate
  * other dialects. The SDK bundles ajv internally but does not re-export `Ajv2020` (its type
  * graph tips downstream declaration bundling — see #2339). To construct a custom 2020-12
  * instance, add `ajv` to your own dependencies (matching the SDK's pinned version) and
@@ -80,15 +77,20 @@ function createDefaultAjvInstance(): AjvLike {
  */
 export class AjvJsonSchemaValidator implements jsonSchemaValidator {
     private _ajv: AjvLike | undefined;
-    /** True iff the constructor received a caller-supplied engine; the `$schema` check is skipped. */
+    /** Lazy classic (draft-07) engine, built on the first draft-07/draft-06-declared schema. */
+    private _ajvDraft7: AjvLike | undefined;
+    /** Lazy 2019-09 engine, built on the first 2019-09-declared schema. */
+    private _ajv2019: AjvLike | undefined;
+    /** True iff the constructor received a caller-supplied engine; the `$schema` dispatch is skipped. */
     private readonly _userAjv: boolean;
 
     /**
      * @param ajv - Optional pre-configured AJV-compatible instance. When supplied, this instance is
      * used for **every** schema regardless of its declared `$schema` (the caller owns dialect
-     * choice). When omitted, the provider constructs a single `Ajv2020` instance with
+     * choice). When omitted, the provider constructs per-dialect engines (`Ajv2020`, `Ajv2019`,
+     * and the classic draft-07 `Ajv` for draft-07/06-declared schemas) with
      * `strict: false`, `validateFormats: true`, `validateSchema: false`, `allErrors: true`, and
-     * `ajv-formats` registered — **lazily, on the first {@linkcode getValidator} call**, so
+     * `ajv-formats` registered — **lazily, on the first {@linkcode getValidator} call needing each**, so
      * constructing the provider (e.g. as the default validator of a `Client`/`Server` that never
      * validates a JSON Schema) does not pay the ajv + ajv-formats instantiation cost. The parameter
      * is typed structurally so consumers who don't pass an instance need not have `ajv` installed.
@@ -98,29 +100,36 @@ export class AjvJsonSchemaValidator implements jsonSchemaValidator {
         this._ajv = ajv;
     }
 
-    /** The underlying engine — the default instance is created on first use. */
+    /** The underlying 2020-12 engine — the default instance is created on first use. */
     private get ajv(): AjvLike {
-        return (this._ajv ??= createDefaultAjvInstance());
+        return (this._ajv ??= createDefaultAjvInstance(Ajv2020));
     }
 
-    getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
-        // Caller supplied a specific engine — do not second-guess by `$schema`
-        // (bring-your-own-validator means bring-your-own-dialect).
-        if (
-            !this._userAjv &&
-            '$schema' in schema &&
-            typeof schema.$schema === 'string' &&
-            !DRAFT_2020_12_URIS.has(schema.$schema.replace(/#$/, ''))
-        ) {
-            const declared = schema.$schema.slice(0, 200);
-            throw new Error(
-                `JSON Schema declares an unsupported dialect ("$schema": "${declared}"). ` +
-                    `The default validator supports JSON Schema 2020-12 only; pass a pre-configured ` +
-                    `Ajv instance to AjvJsonSchemaValidator(ajv) to validate other dialects.`
-            );
+    /**
+     * Pick the engine for a schema's declared dialect. A caller-supplied engine is used for
+     * every schema — do not second-guess by `$schema` (bring-your-own-validator means
+     * bring-your-own-dialect). Otherwise: no `$schema` or 2020-12 → `Ajv2020`; 2019-09 →
+     * `Ajv2019`; draft-07 or draft-06 → classic `Ajv`; anything else → `Error`.
+     */
+    private _engineFor(schema: JsonSchemaType): AjvLike {
+        if (this._userAjv) {
+            return this.ajv;
+        }
+        const dialect = declaredDialect(
+            schema,
+            'pass a pre-configured Ajv instance to AjvJsonSchemaValidator(ajv) to validate other dialects.'
+        );
+        if (dialect === '2020-12') {
+            return this.ajv;
+        }
+        if (dialect === '2019-09') {
+            return (this._ajv2019 ??= createDefaultAjvInstance(Ajv2019));
         }
+        return (this._ajvDraft7 ??= createDefaultAjvInstance(Draft7Ajv));
+    }
 
-        const engine = this.ajv;
+    getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
+        const engine = this._engineFor(schema);
         const ajvValidator =
             '$id' in schema && typeof schema.$id === 'string'
                 ? (engine.getSchema(schema.$id) ?? engine.compile(schema))

packages/core-internal/src/validators/cfWorkerProvider.ts

@@ -10,28 +10,21 @@
 
 import { Validator } from '@cfworker/json-schema';
 
+import { declaredDialect } from './dialects';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types';
 
 /**
  * JSON Schema draft version supported by `@cfworker/json-schema`.
  */
 export type CfWorkerSchemaDraft = '4' | '7' | '2019-09' | '2020-12';
 
-/**
- * Canonical 2020-12 `$schema` URIs (http + https variants, trailing-`#` stripped). When a schema
- * declares anything else and no `{draft}` is forced, the provider throws a plain `Error`.
- */
-const DRAFT_2020_12_URIS: ReadonlySet<string> = new Set([
-    'https://json-schema.org/draft/2020-12/schema',
-    'http://json-schema.org/draft/2020-12/schema'
-]);
-
 /**
  * `@cfworker/json-schema`-backed JSON Schema validator. See
  * `@modelcontextprotocol/{client,server}/validators/cf-worker` for the customisation entry point.
  *
- * Default validates as **JSON Schema 2020-12** (SEP-1613). Schemas declaring a different
- * `$schema` are rejected with a plain `Error`. Passing an explicit `draft` to the constructor
+ * Default dispatches on the schema's declared dialect: no `$schema` or 2020-12 → `'2020-12'`
+ * (SEP-1613); 2019-09 → `'2019-09'`; draft-07 or draft-06 → `'7'`. Schemas declaring any other `$schema` are rejected
+ * with a plain `Error`. Passing an explicit `draft` to the constructor
  * overrides this — that draft is used for every schema regardless of `$schema`.
  *
  * @example Use with default configuration (2020-12, shortcircuit on)
@@ -58,14 +51,24 @@ export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
      * @param options - Configuration options
      * @param options.shortcircuit - If `true`, stop validation after first error (default: `true`)
      * @param options.draft - JSON Schema draft version to force for every schema. When set, the
-     * `$schema` check is skipped. When omitted, the provider validates as 2020-12 and rejects
-     * schemas declaring a different `$schema`.
+     * `$schema` dispatch is skipped. When omitted, the provider dispatches on each schema's
+     * declared `$schema` (2020-12, 2019-09, draft-07, draft-06; absent means 2020-12) and rejects others.
      */
     constructor(options?: { shortcircuit?: boolean; draft?: CfWorkerSchemaDraft }) {
         this.shortcircuit = options?.shortcircuit ?? true;
         this.draft = options?.draft;
     }
 
+    /**
+     * Pick the engine draft for a schema's declared dialect (a caller-forced `{draft}` bypasses
+     * this — do not second-guess by `$schema`). No `$schema` or 2020-12 → `'2020-12'`; 2019-09 →
+     * `'2019-09'`; draft-07 or draft-06 → `'7'`; anything else → `Error`.
+     */
+    private _draftFor(schema: JsonSchemaType): CfWorkerSchemaDraft {
+        const dialect = declaredDialect(schema, 'pass an explicit { draft } to CfWorkerJsonSchemaValidator to validate other dialects.');
+        return dialect === 'draft-7' ? '7' : dialect;
+    }
+
     /**
      * Create a validator for the given JSON Schema
      *
@@ -75,22 +78,7 @@ export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
      * @returns A validator function that validates input data
      */
     getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
-        // Caller forced a draft — use it for everything; do not second-guess by `$schema`.
-        if (
-            this.draft === undefined &&
-            '$schema' in schema &&
-            typeof schema.$schema === 'string' &&
-            !DRAFT_2020_12_URIS.has(schema.$schema.replace(/#$/, ''))
-        ) {
-            const declared = schema.$schema.slice(0, 200);
-            throw new Error(
-                `JSON Schema declares an unsupported dialect ("$schema": "${declared}"). ` +
-                    `The default validator supports JSON Schema 2020-12 only; pass an explicit ` +
-                    `{ draft } to CfWorkerJsonSchemaValidator to validate other dialects.`
-            );
-        }
-
-        const draft = this.draft ?? '2020-12';
+        const draft = this.draft ?? this._draftFor(schema);
         // Cast to the cfworker Schema type - our JsonSchemaType is structurally compatible
         const validator = new Validator(schema as ConstructorParameters<typeof Validator>[0], draft, this.shortcircuit);