fix(core): tolerate legacy tuple schemas

Author: mattzcarey

.changeset/sep-2106-json-schema-2020-12.md

@@ -17,5 +17,7 @@ Implement SEP-2106: tool `inputSchema`/`outputSchema` conform to JSON Schema 202
   descriptive error instead of silently skipping output validation.
 - The default Node validator now uses `Ajv2020`, so the 2020-12 dialect is honored by default (previously `new Ajv()` ran draft-07 semantics and silently ignored keywords such as `prefixItems`). Both built-in validators now default to the `2020-12` dialect
   (`MCP_DEFAULT_SCHEMA_DIALECT`).
+- For compatibility with existing draft-07 tuple schemas, built-in validators using the default 2020-12 dialect normalize legacy `items: [...]` plus `additionalItems` syntax to the equivalent 2020-12 `prefixItems`/`items` form before compiling. New schemas should prefer
+  `prefixItems` directly.
 - New opt-in `resolveExternalSchemaRefs(schema, options)` helper (the SEP's optional external-`$ref` mode): fetches and inlines non-local `$ref`s ahead of time into a self-contained schema. Disabled by default, enforces a host allowlist (and rejects loopback/link-local/private
   targets otherwise), `https`-only by default, with fetch timeout / response-size / document-count limits, dereference logging, and fail-closed on unresolved references.

docs/migration.md

@@ -983,6 +983,9 @@ const server = new McpServer(
 If you import from one of these subpaths in your own code, the corresponding peer dep (`ajv` + `ajv-formats`, or `@cfworker/json-schema`) needs to be installed in your `package.json`. The runtime shim continues to vendor a copy for the default code path, so you can use the
 subpath in some files and rely on the default in others. For AJV customization, use the re-exported `Ajv2020` class; a plain `Ajv` instance uses draft-07 semantics and will not validate JSON Schema 2020-12 keywords such as `prefixItems` the same way as MCP's default validator.
 
+For compatibility with existing draft-07 tuple schemas, the built-in validators using the default 2020-12 dialect normalize legacy `items: [...]` plus `additionalItems` syntax to the equivalent 2020-12 `prefixItems`/`items` form before compiling. New schemas should use
+`prefixItems` directly.
+
 To replace validation wholesale rather than customizing the built-in classes, implement the `jsonSchemaValidator` interface and pass your own implementation through the option above.
 
 ### Tool schemas conform to JSON Schema 2020-12; `structuredContent` may be any JSON value (SEP-2106)

packages/core/src/validators/ajvProvider.ts

@@ -7,6 +7,7 @@ import { Ajv2020 } from 'ajv/dist/2020.js';
 import _addFormats from 'ajv-formats';
 
 import { assertSchemaSafeToCompile } from './schemaBounds';
+import { normalizeLegacyTupleSchema } from './schemaCompatibility';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types';
 
 /** Structural subset of the AJV interface used by {@link AjvJsonSchemaValidator}. */
@@ -67,6 +68,7 @@ function createDefaultAjvInstance(): Ajv {
  */
 export class AjvJsonSchemaValidator implements jsonSchemaValidator {
     private _ajv: AjvLike;
+    private _normalizeLegacyTuples: boolean;
 
     /**
      * @param ajv - Optional pre-configured AJV-compatible instance. If omitted, a default instance is
@@ -76,16 +78,18 @@ export class AjvJsonSchemaValidator implements jsonSchemaValidator {
      */
     constructor(ajv?: AjvLike) {
         this._ajv = ajv ?? createDefaultAjvInstance();
+        this._normalizeLegacyTuples = ajv === undefined || ajv instanceof Ajv2020;
     }
 
     getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
         // SEP-2106: reject non-local $refs (SSRF) and over-budget schemas (composition DoS) before compiling.
         assertSchemaSafeToCompile(schema);
+        const normalizedSchema = this._normalizeLegacyTuples ? normalizeLegacyTupleSchema(schema) : schema;
 
         const ajvValidator =
-            '$id' in schema && typeof schema.$id === 'string'
-                ? (this._ajv.getSchema(schema.$id) ?? this._ajv.compile(schema))
-                : this._ajv.compile(schema);
+            '$id' in normalizedSchema && typeof normalizedSchema.$id === 'string'
+                ? (this._ajv.getSchema(normalizedSchema.$id) ?? this._ajv.compile(normalizedSchema))
+                : this._ajv.compile(normalizedSchema);
 
         return (input: unknown): JsonSchemaValidatorResult<T> => {
             const valid = ajvValidator(input);

packages/core/src/validators/cfWorkerProvider.ts

@@ -11,6 +11,7 @@
 import { Validator } from '@cfworker/json-schema';
 
 import { assertSchemaSafeToCompile } from './schemaBounds';
+import { normalizeLegacyTupleSchema } from './schemaCompatibility';
 import type { JsonSchemaType, JsonSchemaValidator, jsonSchemaValidator, JsonSchemaValidatorResult } from './types';
 import { MCP_DEFAULT_SCHEMA_DIALECT } from './types';
 
@@ -64,9 +65,10 @@ export class CfWorkerJsonSchemaValidator implements jsonSchemaValidator {
     getValidator<T>(schema: JsonSchemaType): JsonSchemaValidator<T> {
         // SEP-2106: reject non-local $refs (SSRF) and over-budget schemas (composition DoS) before compiling.
         assertSchemaSafeToCompile(schema);
+        const normalizedSchema = this.draft === MCP_DEFAULT_SCHEMA_DIALECT ? normalizeLegacyTupleSchema(schema) : schema;
 
         // Cast to the cfworker Schema type - our JsonSchemaType is structurally compatible
-        const validator = new Validator(schema as ConstructorParameters<typeof Validator>[0], this.draft, this.shortcircuit);
+        const validator = new Validator(normalizedSchema as ConstructorParameters<typeof Validator>[0], this.draft, this.shortcircuit);
 
         return (input: unknown): JsonSchemaValidatorResult<T> => {
             const result = validator.validate(input);

packages/core/src/validators/schemaCompatibility.ts

@@ -0,0 +1,84 @@
+import type { JsonSchemaType } from './types';
+
+const DATA_VALUE_KEYWORDS = new Set(['const', 'default', 'enum', 'examples']);
+const SCHEMA_MAP_KEYWORDS = new Set(['$defs', 'definitions', 'dependencies', 'dependentSchemas', 'patternProperties', 'properties']);
+const SCHEMA_ARRAY_KEYWORDS = new Set(['allOf', 'anyOf', 'oneOf', 'prefixItems']);
+const SCHEMA_VALUE_KEYWORDS = new Set([
+    'additionalProperties',
+    'contains',
+    'else',
+    'if',
+    'items',
+    'not',
+    'propertyNames',
+    'then',
+    'unevaluatedItems',
+    'unevaluatedProperties'
+]);
+
+function isJsonObject(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function normalizeSchemaObject(schema: Record<string, unknown>): Record<string, unknown> {
+    const tupleItems = Array.isArray(schema.items) ? schema.items : undefined;
+    const normalized: Record<string, unknown> = {};
+
+    for (const [key, value] of Object.entries(schema)) {
+        if ((key === 'items' || key === 'additionalItems') && tupleItems !== undefined) {
+            continue;
+        }
+
+        if (DATA_VALUE_KEYWORDS.has(key)) {
+            normalized[key] = value;
+        } else if (SCHEMA_MAP_KEYWORDS.has(key) && isJsonObject(value)) {
+            normalized[key] = Object.fromEntries(
+                Object.entries(value).map(([childKey, childValue]) => [childKey, normalizeSchema(childValue)])
+            );
+        } else if (SCHEMA_ARRAY_KEYWORDS.has(key) && Array.isArray(value)) {
+            normalized[key] = value.map(child => normalizeSchema(child));
+        } else if (SCHEMA_VALUE_KEYWORDS.has(key)) {
+            normalized[key] = normalizeSchema(value);
+        } else {
+            normalized[key] = value;
+        }
+    }
+
+    if (tupleItems !== undefined) {
+        if (!('prefixItems' in normalized)) {
+            normalized.prefixItems = tupleItems.map(item => normalizeSchema(item));
+        }
+
+        if ('additionalItems' in schema && schema.additionalItems !== true) {
+            normalized.items = normalizeSchema(schema.additionalItems);
+        }
+    }
+
+    return normalized;
+}
+
+function normalizeSchema(schema: unknown): unknown {
+    if (schema === true || schema === false) {
+        return schema;
+    }
+
+    if (Array.isArray(schema)) {
+        return schema.map(item => normalizeSchema(item));
+    }
+
+    if (!isJsonObject(schema)) {
+        return schema;
+    }
+
+    return normalizeSchemaObject(schema);
+}
+
+/**
+ * JSON Schema 2020-12 replaced draft-07 tuple syntax (`items: [...]` plus
+ * `additionalItems`) with `prefixItems` plus `items`. Normalize the legacy
+ * tuple form before handing schemas to 2020-12 validators so older advertised
+ * tool schemas remain callable.
+ */
+export function normalizeLegacyTupleSchema(schema: JsonSchemaType): JsonSchemaType {
+    return normalizeSchema(schema) as JsonSchemaType;
+}

packages/core/test/validators/validators.test.ts

@@ -407,6 +407,37 @@ describe('JSON Schema Validators', () => {
                 // draft-07 would (incorrectly) accept this because it ignores prefixItems.
                 expect(validator([1, 'a']).valid).toBe(false);
             });
+
+            it('normalizes draft-07 tuple items arrays on the default dialect', () => {
+                const schema = {
+                    type: 'object',
+                    properties: {
+                        value: {
+                            type: 'array',
+                            items: [{ type: 'string' }, { type: 'number' }]
+                        }
+                    },
+                    required: ['value']
+                } as unknown as JsonSchemaType;
+                const validator = provider.getValidator(schema);
+
+                expect(validator({ value: ['a', 1] }).valid).toBe(true);
+                expect(validator({ value: [1, 'a'] }).valid).toBe(false);
+                expect(validator({ value: ['a', 1, true] }).valid).toBe(true);
+            });
+
+            it('normalizes draft-07 additionalItems false to a closed tuple', () => {
+                const schema = {
+                    type: 'array',
+                    items: [{ type: 'string' }, { type: 'number' }],
+                    additionalItems: false
+                } as unknown as JsonSchemaType;
+                const validator = provider.getValidator(schema);
+
+                expect(validator(['a', 1]).valid).toBe(true);
+                expect(validator([1, 'a']).valid).toBe(false);
+                expect(validator(['a', 1, true]).valid).toBe(false);
+            });
         });
 
         describe('Complex real-world schemas', () => {