feat(zod): shallow merge JSON schema registries & dedicated converter integration docs (#1696)

## Summary

- Extracts the JSON Schema converter sections from the OpenAPI
Specification page into dedicated integration docs: **Standard Schema**,
**Zod**, **Valibot**, and **ArkType**, all added to the sidebar. The
spec page keeps a short `Json Schema Converters` section that links out,
so existing anchors still work.
- `ZodToJsonSchemaConverter` now shallow merges `JSON_SCHEMA_REGISTRY`
with `JSON_SCHEMA_INPUT_REGISTRY`/`JSON_SCHEMA_OUTPUT_REGISTRY`
(direction-specific keys win) instead of ignoring the general registry
when a direction entry exists.

```ts
JSON_SCHEMA_REGISTRY.add(user, { description: 'A user' })
JSON_SCHEMA_INPUT_REGISTRY.add(user, { examples: [{ name: 'John', age: '20' }] })

// input schema now includes both the shared description and the input examples
```

## Outcome

- Each schema library has its own integration page, including the new
Zod registries feature and the Standard JSON Schema fallback behavior.
- Shared registry metadata no longer needs to be duplicated into both
direction-specific registries.

Author: dinwwwh

apps/content/.vitepress/config.ts

@@ -186,15 +186,19 @@ export default withMermaid(defineConfig({
           text: 'Integrations',
           collapsed: true,
           items: [
+            { text: 'ArkType', link: '/docs/integrations/arktype' },
             { text: 'Effect', link: '/docs/integrations/effect' },
             { text: 'Evlog', link: '/docs/integrations/evlog' },
             { text: 'NestJS', link: '/docs/integrations/nest' },
             { text: 'Next.js', link: '/docs/integrations/next' },
             { text: 'OpenTelemetry', link: '/docs/integrations/opentelemetry' },
             { text: 'Pinia Colada', link: '/docs/integrations/pinia-colada' },
             { text: 'Pino', link: '/docs/integrations/pino' },
+            { text: 'Standard Schema', link: '/docs/integrations/standard-schema' },
             { text: 'Tanstack Query', link: '/docs/integrations/tanstack-query' },
             { text: 'tRPC', link: '/docs/integrations/trpc' },
+            { text: 'Valibot', link: '/docs/integrations/valibot' },
+            { text: 'Zod', link: '/docs/integrations/zod' },
           ],
         },
         {

apps/content/docs/integrations/arktype.md

@@ -0,0 +1,59 @@
+# ArkType Integration
+
+[ArkType](https://arktype.io/) implements [Standard Schema](/docs/integrations/standard-schema), so you can use it directly in your procedures without any extra setup. On top of that, `@orpc/arktype` provides a dedicated JSON Schema converter.
+
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/arktype@beta arktype
+```
+
+```sh [yarn]
+yarn add @orpc/arktype@beta arktype
+```
+
+```sh [pnpm]
+pnpm add @orpc/arktype@beta arktype
+```
+
+```sh [bun]
+bun add @orpc/arktype@beta arktype
+```
+
+```sh [deno]
+deno add npm:@orpc/arktype@beta npm:arktype
+```
+
+:::
+
+## JSON Schema Converter
+
+`ArkTypeToJsonSchemaConverter` wraps [ArkType's built-in toJsonSchema](https://arktype.io/docs/type-api#tojsonschema) and adds support for additional types such as `bigint` and `Date`. Use it with tools such as the [OpenAPI Generator](/docs/openapi/specification#openapi-generator) and [Smart Coercion](/docs/plugins/smart-coercion). It accepts the same options as ArkType's `toJsonSchema`, see the [source code](https://github.com/middleapi/orpc/blob/main/packages/arktype/src/converter.ts) and ArkType's [JSON Schema configuration docs](https://arktype.io/docs/configuration#tojsonschema) for implementation details.
+
+```ts
+import { OpenAPIGenerator } from '@orpc/openapi'
+import { ArkTypeToJsonSchemaConverter } from '@orpc/arktype'
+
+const generator = new OpenAPIGenerator({
+  converters: [new ArkTypeToJsonSchemaConverter()],
+})
+```
+
+### Reusable Types
+
+A common pattern is defining reusable or recursive types using scopes. The converter preserves them in `$defs`, which `OpenAPIGenerator` can then [hoist](/docs/openapi/specification#hoisting-defs) into `components.schemas`.
+
+```ts
+import { scope } from 'arktype'
+
+const types = scope({
+  Planet: {
+    name: 'string',
+    neighbors: 'Planet[]',
+  },
+})
+
+const PlanetSchema = types.export().Planet
+```

apps/content/docs/integrations/standard-schema.md

@@ -0,0 +1,44 @@
+# Standard Schema Integration
+
+oRPC natively supports any library that implements the [Standard Schema](https://standardschema.dev/) specification, such as [Zod](/docs/integrations/zod), [Valibot](/docs/integrations/valibot), [ArkType](/docs/integrations/arktype), and [many more](https://standardschema.dev/schema#what-schema-libraries-implement-the-spec). Use them directly in `.input`, `.output`, and `.errors` without any extra setup.
+
+```ts
+import * as z from 'zod'
+import * as v from 'valibot'
+
+const example = os
+  .input(z.object({ name: z.string() }))
+  .output(v.object({ name: v.string() }))
+```
+
+## Standard JSON Schema
+
+[Standard JSON Schema](https://standardschema.dev/json-schema) is a companion specification that lets a schema library expose JSON Schema conversion in a standard way. Tools that rely on JSON Schema converters, such as the [OpenAPI Generator](/docs/openapi/specification#openapi-generator) and [Smart Coercion](/docs/plugins/smart-coercion), automatically fall back to Standard JSON Schema conversion when no configured converter matches a schema. So if your library also implements Standard JSON Schema, these tools work out of the box without a dedicated converter. Otherwise, the schema is treated as unknown and converted to an empty JSON schema.
+
+### Building Your Own Converter
+
+If your library does not implement Standard JSON Schema, or you want more control over the conversion, you can build your own converter by implementing the `JsonSchemaConverter` interface and passing it to the `converters` option. The first converter whose `condition` matches handles the schema:
+
+```ts
+import type { AnySchema } from '@orpc/contract'
+import type {
+  JsonSchema,
+  JsonSchemaConverter,
+  JsonSchemaConverterDirection
+} from '@orpc/json-schema'
+import { toJsonSchema } from '@valibot/to-json-schema'
+
+class MyCustomConverter implements JsonSchemaConverter {
+  condition(schema: AnySchema | undefined, _direction: JsonSchemaConverterDirection): boolean {
+    return schema?.['~standard'].vendor === 'valibot'
+  }
+
+  convert(
+    schema: AnySchema | undefined,
+    direction: JsonSchemaConverterDirection
+  ): [jsonSchema: JsonSchema, optional: boolean] {
+    // In most cases, treating the schema as required is acceptable.
+    return [toJsonSchema(schema as any), false] as any
+  }
+}
+```

apps/content/docs/integrations/valibot.md

@@ -0,0 +1,63 @@
+# Valibot Integration
+
+[Valibot](https://valibot.dev/) implements [Standard Schema](/docs/integrations/standard-schema), so you can use it directly in your procedures without any extra setup. On top of that, `@orpc/valibot` provides a dedicated JSON Schema converter.
+
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/valibot@beta valibot
+```
+
+```sh [yarn]
+yarn add @orpc/valibot@beta valibot
+```
+
+```sh [pnpm]
+pnpm add @orpc/valibot@beta valibot
+```
+
+```sh [bun]
+bun add @orpc/valibot@beta valibot
+```
+
+```sh [deno]
+deno add npm:@orpc/valibot@beta npm:valibot
+```
+
+:::
+
+## JSON Schema Converter
+
+`ValibotToJsonSchemaConverter` wraps [Valibot's built-in toJsonSchema](https://github.com/open-circle/valibot/blob/main/packages/to-json-schema/README.md) and adds support for additional types such as `v.bigint()`, `v.date()`, `v.set()`, and `v.map()`. Use it with tools such as the [OpenAPI Generator](/docs/openapi/specification#openapi-generator) and [Smart Coercion](/docs/plugins/smart-coercion). It accepts the same options as Valibot's `toJsonSchema`, see the [source code](https://github.com/middleapi/orpc/blob/main/packages/valibot/src/converter.ts) for implementation details.
+
+```ts
+import { OpenAPIGenerator } from '@orpc/openapi'
+import { ValibotToJsonSchemaConverter } from '@orpc/valibot'
+
+const generator = new OpenAPIGenerator({
+  converters: [new ValibotToJsonSchemaConverter()],
+})
+```
+
+### Reusable Schemas
+
+A common pattern is defining reusable or recursive schemas via definitions. The converter preserves them in `$defs`, which `OpenAPIGenerator` can then [hoist](/docs/openapi/specification#hoisting-defs) into `components.schemas`. For more on how definitions work in Valibot, see [Valibot JSON Schema Definitions](https://github.com/open-circle/valibot/blob/main/packages/to-json-schema/README.md#definitions).
+
+```ts
+import * as v from 'valibot'
+
+const PlanetSchema = v.object({
+  id: v.string(),
+  name: v.string(),
+})
+
+const generator = new OpenAPIGenerator({
+  converters: [
+    new ValibotToJsonSchemaConverter({
+      definitions: { PlanetSchema },
+    }),
+  ],
+})
+```

apps/content/docs/integrations/zod.md

@@ -0,0 +1,89 @@
+# Zod Integration
+
+[Zod](https://zod.dev/) implements [Standard Schema](/docs/integrations/standard-schema), so you can use it directly in your procedures without any extra setup. On top of that, `@orpc/zod` provides a dedicated JSON Schema converter and registries for customizing the generated JSON schemas.
+
+::: warning
+`@orpc/zod` requires Zod v4 or later.
+:::
+
+## Installation
+
+::: code-group
+
+```sh [npm]
+npm install @orpc/zod@beta zod
+```
+
+```sh [yarn]
+yarn add @orpc/zod@beta zod
+```
+
+```sh [pnpm]
+pnpm add @orpc/zod@beta zod
+```
+
+```sh [bun]
+bun add @orpc/zod@beta zod
+```
+
+```sh [deno]
+deno add npm:@orpc/zod@beta npm:zod
+```
+
+:::
+
+## JSON Schema Converter
+
+`ZodToJsonSchemaConverter` wraps [Zod's built-in toJSONSchema](https://zod.dev/json-schema?id=ztojsonschema#ztojsonschema) and adds support for additional types such as `z.bigint()`, `z.date()`, `z.set()`, and `z.map()`. Use it with tools such as the [OpenAPI Generator](/docs/openapi/specification#openapi-generator) and [Smart Coercion](/docs/plugins/smart-coercion). It accepts the same options as Zod's `toJSONSchema`, see the [source code](https://github.com/middleapi/orpc/blob/main/packages/zod/src/converter.ts) for implementation details.
+
+```ts
+import { OpenAPIGenerator } from '@orpc/openapi'
+import { ZodToJsonSchemaConverter } from '@orpc/zod'
+
+const generator = new OpenAPIGenerator({
+  converters: [new ZodToJsonSchemaConverter()],
+})
+```
+
+### Reusable Schemas
+
+A common pattern is defining reusable schemas with `id` metadata. The converter places them in `$defs`, which `OpenAPIGenerator` then [hoists](/docs/openapi/specification#hoisting-defs) into `components.schemas`. For more on `id` and `$ref` in Zod, see [Zod JSON Schema Registries](https://zod.dev/json-schema?id=registries#registries).
+
+```ts
+import * as z from 'zod'
+
+const PlanetSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+}).meta({ id: 'Planet' })
+```
+
+### Customizing Generated JSON Schemas
+
+`@orpc/zod` exposes registries for customizing the JSON schema generated for a given Zod schema. Registered entries are shallow merged over the generated JSON schema: `JSON_SCHEMA_REGISTRY` applies to both input and output, while `JSON_SCHEMA_INPUT_REGISTRY` and `JSON_SCHEMA_OUTPUT_REGISTRY` apply to a single direction and win on conflicting keys:
+
+```ts
+import {
+  JSON_SCHEMA_INPUT_REGISTRY,
+  JSON_SCHEMA_OUTPUT_REGISTRY,
+  JSON_SCHEMA_REGISTRY,
+} from '@orpc/zod'
+import * as z from 'zod'
+
+const user = z.object({
+  name: z.string(),
+  age: z.string().transform(v => Number(v)),
+})
+
+JSON_SCHEMA_REGISTRY.add(user, {
+  description: 'A user',
+})
+
+JSON_SCHEMA_INPUT_REGISTRY.add(user, {
+  examples: [{ name: 'John', age: '20' }],
+})
+
+JSON_SCHEMA_OUTPUT_REGISTRY.add(user, {
+  examples: [{ name: 'John', age: 20 }],
+})
+```