feat(json-schema): smart coercion plugin for any standard schema by dinwwwh · Pull Request #748 · middleapi/orpc

dinwwwh · 2025-07-11T01:18:48Z

Closes: https://github.com/unnoq/orpc/issues/395

Summary by CodeRabbit

New Features
- Introduced the experimental Smart Coercion Plugin for automatic, deep type coercion based on JSON Schema, supporting native JavaScript types like BigInt, Date, RegExp, URL, Set, and Map.
- Added detailed documentation for the Smart Coercion Plugin, including installation, setup, usage examples, and conversion rules.
- Added new sidebar navigation entries for the Smart Coercion Plugin and legacy Zod Smart Coercion in the documentation.
Improvements
- Enhanced JSON Schema conversion by annotating schemas with native type metadata (bigint, date, set, map, regexp, url).
- Updated playgrounds and OpenAPI handler configurations to replace the deprecated ZodSmartCoercionPlugin with the new Smart Coercion Plugin.
- Marked the ZodSmartCoercionPlugin as deprecated in favor of the new plugin.
Bug Fixes
- Expanded test coverage for coercion logic, validating handling of diverse schema constructs and native types.
Chores
- Added the new @orpc/json-schema package with source code, tests, documentation, and build configuration.
- Updated dependencies and TypeScript project references in multiple packages and playgrounds to include @orpc/json-schema.
- Added .gitignore and README files for the new package.

vercel · 2025-07-11T01:18:54Z

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
orpc	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Jul 11, 2025 2:46am

coderabbitai · 2025-07-11T01:18:56Z

Walkthrough

A new @orpc/json-schema package is introduced, providing a smart coercion plugin and a JSON Schema coercer that supports native JavaScript types and deep, schema-guided value transformations. The Zod-specific smart coercion plugin is deprecated in favor of this new plugin. All playgrounds and documentation are updated to use the new plugin, and test suites are added for smart coercion and schema conversion.

Changes

Files / Groups	Change Summary
`packages/json-schema/` (all new: src, tests, config, README, package.json)	Introduced new package with JSON Schema coercion logic, smart coercion plugin, type definitions, tests, documentation, config, and manifest.
`packages/zod/src/converter.ts`, `zod4/converter.ts`, `zod4/converter.*.test.ts`, `converter.test.ts`, `tests/shared.ts`	Added `"x-native-type"` to JSON Schema outputs for native types; updated tests and types accordingly.
`packages/zod/package.json`, `tsconfig.json`	Added dependency and project reference to `@orpc/json-schema`.
`packages/zod/src/zod4/coercer.ts`	Deprecated Zod-specific smart coercion plugin via JSDoc.
`packages/openapi/src/schema-converter.ts`	Made schema converter array property readonly for immutability.
`apps/content/.vitepress/config.ts`, `docs/openapi/plugins/smart-coercion.md`	Added documentation and sidebar entry for the new Smart Coercion Plugin.
`playgrounds/*/package.json`	Added `@orpc/json-schema` as a devDependency in all playgrounds.
`playgrounds/*/src/...`	Switched from ZodSmartCoercionPlugin to new SmartCoercionPlugin using JSON Schema, updated plugin instantiation.

Sequence Diagram(s)

sequenceDiagram
    participant Client
    participant SmartCoercionPlugin
    participant SchemaConverter
    participant JsonSchemaCoercer
    participant Handler

    Client->>SmartCoercionPlugin: Send input with schema
    SmartCoercionPlugin->>SchemaConverter: Convert schema to JSON Schema
    SchemaConverter-->>SmartCoercionPlugin: Return JSON Schema
    SmartCoercionPlugin->>JsonSchemaCoercer: Coerce input using JSON Schema
    JsonSchemaCoercer-->>SmartCoercionPlugin: Return coerced input
    SmartCoercionPlugin->>Handler: Pass coerced input
    Handler-->>Client: Return response

Assessment against linked issues

Objective	Addressed	Explanation
Implement ArkType coercer (#395)	❌	No ArkType coercer or ArkType-specific logic is present; only Zod and JSON Schema coercion are implemented.
Deprecate Zod-specific smart coercion in favor of generic plugin (#395)	✅
Update documentation and playgrounds to use new smart coercion plugin (#395)	✅

Assessment against linked issues: Out-of-scope changes

Code Change	Explanation
Added `.gitignore` and README to `packages/json-schema`	These are standard package setup files unrelated to the feature objectives.
Made `CompositeSchemaConverter.converters` readonly in `packages/openapi/src/schema-converter.ts`	This is an internal type safety improvement unrelated to coercion features.
Removed blank line in Nest integration docs (`apps/content/docs/openapi/integrations/implement-contract-in-nest.md`)	Minor formatting change unrelated to coercion or plugin features.

Possibly related PRs

unnoq/orpc#462: Introduces a new "Smart Coercion" plugin based on JSON Schema coercion and replaces the legacy "Zod Smart Coercion" plugin with it; related by domain but distinct in implementation and target Zod version.

Poem

In a warren of code, a new path is shown,
With schemas and types, smart coercion has grown.
Zod’s plugin retired, JSON Schema takes stage,
Now rabbits can hop through each native type cage!
So let’s nibble some carrots and celebrate here—
For smart, schema-driven coercion is finally here! 🥕✨

✨ Finishing Touches

📝 Generate Docstrings

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

Review comments: Directly reply to a review comment made by CodeRabbit. Example:
- I pushed a fix in commit <commit_id>, please review it.
- Explain this complex logic.
- Open a follow-up GitHub issue for this discussion.
Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query. Examples:
- @coderabbitai explain this code block.
- @coderabbitai modularize this function.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read src/utils.ts and explain its main purpose.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.
- @coderabbitai help me debug CodeRabbit configuration file.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments.

CodeRabbit Commands (Invoked using PR comments)

@coderabbitai pause to pause the reviews on a PR.
@coderabbitai resume to resume the paused reviews.
@coderabbitai review to trigger an incremental review. This is useful when automatic reviews are disabled for the repository.
@coderabbitai full review to do a full review from scratch and review all the files again.
@coderabbitai summary to regenerate the summary of the PR.
@coderabbitai generate docstrings to generate docstrings for this PR.
@coderabbitai generate sequence diagram to generate a sequence diagram of the changes in this PR.
@coderabbitai resolve resolve all the CodeRabbit review comments.
@coderabbitai configuration to show the current CodeRabbit configuration for the repository.
@coderabbitai help to get help.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

CodeRabbit Configuration File (`.coderabbit.yaml`)

You can programmatically configure CodeRabbit by adding a .coderabbit.yaml file to the root of your repository.
Please see the configuration documentation for more information.
If your editor has YAML language server enabled, you can add the path at the top of this file to enable auto-completion and validation: # yaml-language-server: $schema=https://coderabbit.ai/integrations/schema.v2.json

Documentation and Community

Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

gemini-code-assist

Summary of Changes

Hello @unnoq, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a powerful new 'smart coercion' feature to oRPC, enabling automatic and safe type conversion of incoming data based on its defined JSON Schema. This significantly improves developer experience by reducing the need for manual data transformation, and is implemented through a new dedicated @orpc/json-schema package, along with necessary updates to existing schema converters.

Highlights

New Core Package: Introduced a new @orpc/json-schema package, which provides a generic experimental_JsonSchemaCoercer for intelligent type conversion based on JSON Schema definitions, and an experimental_SmartCoercionPlugin to integrate this functionality into the oRPC client request pipeline.
Enhanced Schema Generation: Updated the @orpc/zod package's JSON Schema converter to emit custom x-native-type metadata for native JavaScript types (like BigInt, Date, RegExp, URL, Set, and Map). This metadata is crucial for the new smart coercion logic to correctly identify and transform these types.
Plugin Deprecation and Migration: The existing experimental_ZodSmartCoercionPlugin in @orpc/zod has been deprecated in favor of the new, more versatile experimental_SmartCoercionPlugin from @orpc/json-schema. Playgrounds have been updated to reflect this migration.
Comprehensive Documentation and Testing: Added detailed documentation for the new Smart Coercion Plugin, explaining its purpose, usage, and conversion rules. Extensive unit tests have also been included to ensure the robustness and correctness of the coercion logic across various data types and schema structures.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point in your pull request via creating an issue comment (i.e. comment on the pull request page) using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in issue comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist is currently in preview and may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments to provide feedback.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces a new @orpc/json-schema package with a generic smart coercion plugin. The date coercion implementation in coercer.ts has a potential timezone issue, and x-native-type metadata is missing in zod/src/converter.ts for bigint, date, set, and map.

coderabbitai

Actionable comments posted: 4

♻️ Duplicate comments (3)

playgrounds/solid-start/package.json (1)

10-14: Same runtime / dev-only concern as commented in Nuxt playground.
See previous note; ensure @orpc/json-schema is available in production builds.

playgrounds/astro/package.json (1)

12-18: Same runtime / dev-only concern as commented in Nuxt playground.
Verify whether @orpc/json-schema should move from devDependencies to dependencies.

playgrounds/svelte-kit/package.json (1)

14-18: Same runtime / dev-only concern as commented in Nuxt playground.
Confirm correct placement of @orpc/json-schema.

🧹 Nitpick comments (11)

playgrounds/solid-start/src/routes/api/[...rest].ts (1)
20-24: Plugin configuration follows the correct pattern.

The new plugin is properly configured with the ZodToJsonSchemaConverter to maintain compatibility with existing Zod schemas while leveraging the more flexible JSON Schema coercion system.

Consider adding a comment about the experimental nature of the plugin:
+    // Using experimental JSON Schema-based coercion plugin
     new SmartCoercionPlugin({
       schemaConverters: [
         new ZodToJsonSchemaConverter(),
       ],
     }),
packages/json-schema/README.md (2)
49-61: Improve readability by varying sentence beginnings.

The package descriptions all start with similar patterns, making them repetitive. Consider varying the sentence structures for better readability.
- [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
- [@orpc/server](https://www.npmjs.com/package/@orpc/server): Build your API or implement API contract.
- [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
- [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
+ [@orpc/contract](https://www.npmjs.com/package/@orpc/contract): Build your API contract.
+ [@orpc/server](https://www.npmjs.com/package/@orpc/server): Create your API or implement API contract.
+ [@orpc/client](https://www.npmjs.com/package/@orpc/client): Consume your API on the client with type-safety.
+ [@orpc/openapi](https://www.npmjs.com/package/@orpc/openapi): Generate OpenAPI specs and handle OpenAPI requests.
70-70: Add alt text for accessibility.

The sponsors image is missing alt text, which is important for accessibility.
-    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg'/>
+    <img src='https://cdn.jsdelivr.net/gh/unnoq/unnoq/sponsors.svg' alt='Sponsors'/>
packages/json-schema/src/smart-coercion-plugin.test.ts (1)
5-37: LGTM: Basic functionality tests are correct.

The test structure properly simulates the plugin's interceptor behavior and covers fundamental coercion scenarios.

Consider expanding test coverage to include:

Error handling scenarios (invalid inputs, malformed schemas)

Complex schema types (nested objects, arrays, unions)

Native type coercion (Date, BigInt, URL, etc.)

Edge cases (null, undefined, empty values)

Example additional test:
expect(await coerce(z.object({ date: z.date() }), { date: '2023-01-01' })).toEqual({ date: new Date('2023-01-01') })
apps/content/docs/openapi/plugins/smart-coercion.md (1)
82-82: Simplify the wording for better readability.

The phrase "with the exception of" can be replaced with a more concise alternative.

Apply this diff to improve readability:
-The built-in [JSON Schema Converters](/docs/openapi/openapi-specification#generating-specifications) handle these cases (with the exception of some experimental converters).
+The built-in [JSON Schema Converters](/docs/openapi/openapi-specification#generating-specifications) handle these cases (except for some experimental converters).
packages/json-schema/src/coercer.test.ts (4)
7-12: Fix typo in test description.

The test description contains a grammatical error.
-  it('do no thing with boolean/any schema', () => {
+  it('does nothing with boolean/any schema', () => {
33-37: Address the TODO comment for multiple types test.

There's an unfinished test case for coercing with multiple types including 'null'.

Would you like me to help implement this test case or open an issue to track this?

52-52: Use regex literal instead of RegExp constructor.

Static analysis correctly identifies that a regex literal would be cleaner here.
-    expect(coercer.coerce({ 'type': 'string', 'x-native-type': 'regexp' } as any, '/abc/i')).toEqual(new RegExp('abc', 'i'))
+    expect(coercer.coerce({ 'type': 'string', 'x-native-type': 'regexp' } as any, '/abc/i')).toEqual(/abc/i)
258-280: Add type cast for consistency.

For consistency with other tests, add the as any type cast to the schema.
       },
       required: ['a'],
-    }
+    } as any
packages/json-schema/src/coercer.ts (2)
121-123: Remove unnecessary type assertion.

The type assertion as JsonSchema | undefined is redundant here.
            const itemSchema: JsonSchema | undefined = Array.isArray(schema.items)
              ? schema.additionalItems
-              : schema.items as JsonSchema | undefined
+              : schema.items
169-170: Consider caching compiled regex patterns for better performance.

Creating RegExp objects on every coercion call could impact performance when processing many objects with the same schema.

Consider caching the compiled regex patterns at the schema level or in a WeakMap to avoid repeated compilation of the same patterns.

📜 Review details

Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between bb23f2f and b68f5cf.

⛔ Files ignored due to path filters (1)

pnpm-lock.yaml is excluded by !**/pnpm-lock.yaml

📒 Files selected for processing (37)

apps/content/.vitepress/config.ts (1 hunks)
apps/content/docs/openapi/plugins/smart-coercion.md (1 hunks)
packages/json-schema/.gitignore (1 hunks)
packages/json-schema/README.md (1 hunks)
packages/json-schema/package.json (1 hunks)
packages/json-schema/src/coercer.test.ts (1 hunks)
packages/json-schema/src/coercer.ts (1 hunks)
packages/json-schema/src/index.ts (1 hunks)
packages/json-schema/src/smart-coercion-plugin.test.ts (1 hunks)
packages/json-schema/src/smart-coercion-plugin.ts (1 hunks)
packages/json-schema/src/types.ts (1 hunks)
packages/json-schema/tsconfig.json (1 hunks)
packages/openapi/src/schema-converter.ts (1 hunks)
packages/zod/package.json (1 hunks)
packages/zod/src/converter.test.ts (9 hunks)
packages/zod/src/converter.ts (8 hunks)
packages/zod/src/zod4/coercer.ts (1 hunks)
packages/zod/src/zod4/converter.native.test.ts (1 hunks)
packages/zod/src/zod4/converter.number.test.ts (1 hunks)
packages/zod/src/zod4/converter.structure.test.ts (2 hunks)
packages/zod/src/zod4/converter.ts (4 hunks)
packages/zod/tests/shared.ts (1 hunks)
packages/zod/tsconfig.json (1 hunks)
playgrounds/astro/package.json (1 hunks)
playgrounds/astro/src/pages/api/[...rest].ts (2 hunks)
playgrounds/contract-first/package.json (1 hunks)
playgrounds/contract-first/src/main.ts (2 hunks)
playgrounds/next/package.json (1 hunks)
playgrounds/next/src/app/api/[[...rest]]/route.ts (2 hunks)
playgrounds/nuxt/package.json (1 hunks)
playgrounds/nuxt/server/routes/api/[...].ts (2 hunks)
playgrounds/solid-start/package.json (1 hunks)
playgrounds/solid-start/src/routes/api/[...rest].ts (2 hunks)
playgrounds/svelte-kit/package.json (1 hunks)
playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts (2 hunks)
playgrounds/tanstack-start/package.json (1 hunks)
playgrounds/tanstack-start/src/routes/api/$.ts (2 hunks)

🧰 Additional context used

🧬 Code Graph Analysis (11)

packages/zod/tests/shared.ts (1)

packages/openapi/src/schema.ts (1)

JSONSchema (6-6)

playgrounds/solid-start/src/routes/api/[...rest].ts (1)

packages/zod/src/converter.ts (1)

ZodToJsonSchemaConverter (77-695)

playgrounds/tanstack-start/src/routes/api/$.ts (1)

packages/zod/src/converter.ts (1)

ZodToJsonSchemaConverter (77-695)

playgrounds/next/src/app/api/[[...rest]]/route.ts (1)

packages/zod/src/converter.ts (1)

ZodToJsonSchemaConverter (77-695)

playgrounds/astro/src/pages/api/[...rest].ts (1)

packages/zod/src/converter.ts (1)

ZodToJsonSchemaConverter (77-695)

playgrounds/svelte-kit/src/routes/api/[...rest]/+server.ts (1)

packages/zod/src/converter.ts (1)

ZodToJsonSchemaConverter (77-695)

playgrounds/nuxt/server/routes/api/[...].ts (1)

packages/zod/src/converter.ts (1)

ZodToJsonSchemaConverter (77-695)

packages/json-schema/src/smart-coercion-plugin.ts (8)

packages/openapi/src/schema-converter.ts (3)

ConditionalSchemaConverter (34-36)

SchemaConverter (30-32)

CompositeSchemaConverter (38-54)

packages/server/src/context.ts (1)

Context (1-1)

packages/server/src/adapters/standard/plugin.ts (1)

StandardHandlerPlugin (5-8)

packages/contract/src/schema.ts (1)

AnySchema (7-7)

packages/json-schema/src/types.ts (1)

JsonSchema (6-9)

packages/shared/src/array.ts (1)

toArray (1-3)

packages/server/src/adapters/standard/handler.ts (1)

StandardHandlerOptions (27-48)

packages/json-schema/src/coercer.ts (11)

schema (15-336)

value (338-346)

value (348-356)

value (358-370)

value (372-374)

value (376-384)

value (386-395)

value (397-399)

value (401-403)

value (405-413)

value (415-421)

packages/zod/src/zod4/converter.ts (2)

packages/openapi/src/schema.ts (1)

JSONSchemaFormat (5-5)

packages/json-schema/src/coercer.ts (1)

schema (15-336)

packages/zod/src/converter.test.ts (2)

packages/openapi/src/schema.ts (1)

JSONSchema (6-6)

packages/zod/src/schemas/url.ts (1)

url (6-20)

packages/json-schema/src/coercer.test.ts (1)

packages/json-schema/src/coercer.ts (1)

schema (15-336)

🪛 LanguageTool

packages/json-schema/README.md

[style] ~51-~51: Three successive sentences begin with the same word. Consider rewording the sentence or use a thesaurus to find a synonym.
Context: ... your API or implement API contract. - [@orpc/client](https://www.npmjs.com/package/@...