chore: [JS] Add instructions to always use zod@v4 (#299)

Author: davidkna-sap

docs-js/foundation-models/openai/chat-completion.mdx

@@ -203,19 +203,19 @@ const response = await client.run({
 console.log(response.getContent());
 ```
 
-You can also define JSON schema using [Zod](https://zod.dev/) schema as shown below:
+You can also define JSON schema using [Zod](https://zod.dev/) schema.
+We recommend using Zod v4 for full compatibility with this package.
+If you're upgrading from an earlier version, refer to the [Zod v4 migration guide](https://zod.dev/v4/changelog) and pay attention to breaking changes like the switch from `describe('...')` to `meta({ description: '...' })`.
 
 ```ts
 import * as z from 'zod';
 import { toJsonSchema } from '@langchain/core/utils/json_schema';
 import { AzureOpenAiResponseFormatJsonSchema } from '@sap-ai-sdk/foundation-models';
 
-const countryCapitalSchema = z
-  .object({
-    population: z.number(),
-    capital: z.string()
-  })
-  .strict();
+const countryCapitalSchema = z.strictObject({
+  population: z.number(),
+  capital: z.string()
+});
 
 const response_format: AzureOpenAiResponseFormatJsonSchema = {
   type: 'json_schema',

docs-js/langchain/openai.mdx

@@ -191,6 +191,8 @@ For a usage example, refer to the [getting started with agents tutorial](../tuto
 
 It is often useful to have a model return output that matches a specific schema.
 This schema can be defined using either a [Zod](https://zod.dev/) schema or an OpenAI-style JSON schema.
+We recommend using Zod v4 for full compatibility with this package.
+If you're upgrading from an earlier version, refer to the [Zod v4 migration guide](https://zod.dev/v4/changelog) and pay attention to breaking changes like the switch from `describe('...')` to `meta({ description: '...' })`.
 For more details on structured output, refer to the [official LangChain documentation on structured output](https://docs.langchain.com/oss/javascript/langchain/models#structured-outputs).
 Below is an example using `json_schema` response type and passing in a Zod schema.
 
@@ -201,9 +203,11 @@ import { AzureOpenAiChatClient } from '@sap-ai-sdk/langchain';
 const llm = new AzureOpenAiChatClient({ modelName: 'gpt-4o' });
 
 const joke = z.object({
-  setup: z.string().describe('The setup of the joke'),
-  punchline: z.string().describe('The punchline to the joke'),
-  rating: z.number().describe('How funny the joke is, from 1 to 10')
+  setup: z.string().meta({ description: 'The setup of the joke' }),
+  punchline: z.string().meta({ description: 'The punchline to the joke' }),
+  rating: z
+    .number()
+    .meta({ description: 'How funny the joke is, from 1 to 10' })
 });
 
 const structuredLlm = llm.withStructuredOutput(joke, {

docs-js/orchestration/chat-completion.mdx

@@ -404,19 +404,24 @@ const templating: TemplatingModuleConfig = {
 };
 ```
 
+:::info
+
+We recommend using Zod v4 for full compatibility with this package.
+If you're upgrading from an earlier version, refer to the [Zod v4 migration guide](https://zod.dev/v4/changelog) and pay attention to breaking changes like the switch from `describe('...')` to `meta({ description: '...' })`
+
+:::
+
 You can also define JSON schema using [Zod](https://zod.dev/) schema as shown below:
 
 ```ts
-import * as z from 'zod/v4';
+import * as z from 'zod';
 import { toJsonSchema } from '@langchain/core/utils/json_schema';
 import { ResponseFormatJsonSchema } from '@sap-ai-sdk/orchestration';
 
-const countryCapitalSchema = z
-  .object({
-    country_name: z.string(),
-    capital: z.string()
-  })
-  .strict();
+const countryCapitalSchema = z.strictObject({
+  country_name: z.string(),
+  capital: z.string()
+});
 
 const response_format: ResponseFormatJsonSchema = {
   type: 'json_schema',