feat(compat): add ResourceReferenceSchema alias; point deprecation to specTypeSchemas/isSpecType

Author: felixweinberger

.changeset/compat-zod-schemas-subpath.md

@@ -4,6 +4,6 @@
 
 Add `@modelcontextprotocol/server/zod-schemas` subpath for v1 compatibility
 
-Re-exports the `*Schema` Zod constants (e.g. `CallToolRequestSchema`, `JSONRPCMessageSchema`) and the `getRequestSchema(method)` / `getResultSchema(method)` / `getNotificationSchema(method)` lookup helpers, so v1 code that imported schemas from `@modelcontextprotocol/sdk/types.js` can be pointed at a single subpath. These are Zod schemas; their TS type may change with internal Zod upgrades. Prefer `specTypeSchema()` for runtime validation.
+Re-exports the `*Schema` Zod constants (e.g. `CallToolRequestSchema`, `JSONRPCMessageSchema`) and the `getRequestSchema(method)` / `getResultSchema(method)` / `getNotificationSchema(method)` lookup helpers, so v1 code that imported schemas from `@modelcontextprotocol/sdk/types.js` can be pointed at a single subpath. These are Zod schemas; their TS type may change with internal Zod upgrades. Prefer `specTypeSchemas` / `isSpecType` (#1887) for runtime validation.
 
-The `@modelcontextprotocol/sdk` meta-package (#1913 in this series) re-exports this subpath at `sdk/types.js`, so v1 imports work unchanged once both PRs land.
+The `@modelcontextprotocol/sdk` meta-package (#1913 in this series) re-exports this subpath at `sdk/types.js`, so v1 imports work unchanged once both PRs land. The `specTypeSchemas` / `isSpecType` references in the deprecation guidance are added by #1887.

docs/migration-SKILL.md

@@ -98,7 +98,7 @@ Notes:
 | `StreamableHTTPError`                    | REMOVED (use `SdkError` with `SdkErrorCode.ClientHttp*`) |
 | `WebSocketClientTransport`               | REMOVED (use `StreamableHTTPClientTransport` or `StdioClientTransport`) |
 
-All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names. **Zod schemas** (e.g., `CallToolResultSchema`, `ListToolsResultSchema`) are not exported from the package root; for runtime validation prefer type guard functions like `isCallToolResult` or `specTypeSchema()`. For v1 compatibility the schemas are available from the `@modelcontextprotocol/server/zod-schemas` subpath.
+All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names. **Zod schemas** (e.g., `CallToolResultSchema`, `ListToolsResultSchema`) are not exported from the package root; for runtime validation prefer type guard functions like `isCallToolResult`, or the `isSpecType` / `specTypeSchemas` Records. For v1 compatibility the schemas are available from the `@modelcontextprotocol/server/zod-schemas` subpath.
 
 ### Error class changes
 

docs/migration.md

@@ -544,7 +544,7 @@ The following deprecated type aliases have been removed from `@modelcontextproto
 | `IsomorphicHeaders`                      | Use Web Standard `Headers`                       |
 | `AuthInfo` (from `server/auth/types.js`) | `AuthInfo` (now re-exported by `@modelcontextprotocol/client` and `@modelcontextprotocol/server`) |
 
-All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names — import them from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`. **Zod schemas** (e.g., `CallToolRequestSchema`) are not re-exported from the package roots; for runtime validation prefer `specTypeSchema()` or, for v1 source compatibility, import them from `@modelcontextprotocol/server/zod-schemas`.
+All other **type** symbols from `@modelcontextprotocol/sdk/types.js` retain their original names — import them from `@modelcontextprotocol/client` or `@modelcontextprotocol/server`. **Zod schemas** (e.g., `CallToolRequestSchema`) are not re-exported from the package roots; for runtime validation prefer the `isSpecType` / `specTypeSchemas` Records, or for v1 source compatibility import them from `@modelcontextprotocol/server/zod-schemas`.
 
 > **Note on `isJSONRPCResponse`:** v1's `isJSONRPCResponse` was a deprecated alias that only checked for *result* responses (it was equivalent to `isJSONRPCResultResponse`). v2 removes the deprecated alias and introduces a **new** `isJSONRPCResponse` with corrected semantics — it checks for *any* response (either result or error). If you are migrating v1 code that used `isJSONRPCResponse`, rename it to `isJSONRPCResultResponse` to preserve the original behavior. Use the new `isJSONRPCResponse` only when you want to match both result and error responses.
 

packages/server/src/zodSchemas.ts

@@ -1,17 +1,18 @@
 /**
  * v1-compat re-export of all protocol Zod schemas.
  *
- * Prefer {@linkcode specTypeSchema} for runtime validation. These are Zod
- * schemas; their TS type may change with internal Zod upgrades.
+ * Prefer `specTypeSchemas` / `isSpecType` (from `@modelcontextprotocol/server`)
+ * for runtime validation. These are Zod schemas; their TS type may change with
+ * internal Zod upgrades.
  *
- * @deprecated Use `specTypeSchema()` for runtime validation.
+ * @deprecated Use `specTypeSchemas` / `isSpecType` for runtime validation.
  * @packageDocumentation
  */
 
-/** @deprecated Use `specTypeSchema()` for runtime validation. */
+/** @deprecated Use `specTypeSchemas` / `isSpecType` for runtime validation. */
 export * from '@modelcontextprotocol/core/schemas';
 
-/** @deprecated Use `specTypeSchema()` for runtime validation. */
+/** @deprecated Use `specTypeSchemas` / `isSpecType` for runtime validation. */
 export {
     IdJagTokenExchangeResponseSchema,
     OAuthClientInformationFullSchema,
@@ -30,5 +31,7 @@ export {
 } from '@modelcontextprotocol/core';
 export {
     /** @deprecated Use {@linkcode JSONRPCErrorResponseSchema}. */
-    JSONRPCErrorResponseSchema as JSONRPCErrorSchema
+    JSONRPCErrorResponseSchema as JSONRPCErrorSchema,
+    /** @deprecated Use {@linkcode ResourceTemplateReferenceSchema}. */
+    ResourceTemplateReferenceSchema as ResourceReferenceSchema
 } from '@modelcontextprotocol/core/schemas';