feat!: migrate to @openapi-spec types and target OpenAPI 3.2 with a version option (#1998)

Replaces `json-schema-typed` and `@hey-api/spec-types` with
`@openapi-spec/types`, so `JsonSchema` is the OpenAPI 3.2 Schema Object
and `@orpc/openapi` re-exports the `OpenAPIV3_0`, `OpenAPIV3_1`, and
`OpenAPIV3_2` namespaces. `OpenAPIGenerator` now builds OpenAPI 3.2
documents and takes a `version` option that downgrades to 3.1 or 3.0
through `@openapi-spec/downgrader`, with the return type following the
requested version.

## Breaking changes

- `generate()` emits `3.2.0` by default (was `3.1.2`). Pass `version:
'3.1.2'` to keep 3.1 documents. `base` no longer accepts `openapi`.
- `OpenAPIDocument` requires a version argument;
`OpenAPIDocument<OpenAPIVersion>` is the union of every supported
document. `OpenAPIOperationObject` is replaced by
`OpenAPIV3_2.OperationObject`.
- `JsonSchemaKeywords` is derived from the 3.2 Schema Object, so legacy
keywords such as `additionalItems` are no longer part of it.

## Behavior

- Any `3.0.x`, `3.1.x`, or `3.2.x` `version` is accepted. The minor
version selects the conversion and the document carries the exact
requested value.
- Everything authored (`base`, `openapi({ spec })`, converter output)
stays OpenAPI 3.2 and is downgraded with the rest of the document, so
`type: ['string', 'null']` becomes `nullable: true` in 3.0 output.
- Downgrading runs before serialization: the serializer output is not
made of plain objects and the downgrader would pass it through
untouched.
- QUERY operations still require 3.2 and throw when an older version is
requested.

## Docs

- The specification page documents `version` in its own section, and the
v1 migration guide notes the new default.

## Testing

- Version tests compare whole output documents for `3.2.0`, `3.2.7`,
`3.1.2`, `3.1.0`, `3.0.4`, and `3.0.0`, with type tests for the
version-dependent return type.
- Root type check, lint, the docs JSDoc backlink checker, and both
package builds pass.

Author: dinwwwh

apps/content/docs/migrations/from-v1.mdx

@@ -1020,10 +1020,11 @@ const spec = await generator.generate(router, {
 
 </CodeGroup>
 
-Two smaller changes in the same area:
+Three smaller changes in the same area:
 
 - The `oo` helper (`oo.spec`) was removed. To customize the operation object, attach [`openapi({ spec })` metadata](/docs/openapi/specification#customizing-the-operation-object) directly on the procedure or router.
 - The `shouldHoistDef` option was replaced by [`customComponentName`](/docs/openapi/specification#hoisting-defs). Root `$defs` are now always hoisted into `components.schemas`; this option only renames them.
+- Documents are generated as OpenAPI 3.2.0 by default. Pass [`version: '3.1.1'`](/docs/openapi/specification#openapi-version) to keep old behavior.
 
 ### `OpenAPIReferencePlugin` renamed and reshaped
 

apps/content/docs/openapi/specification.mdx

@@ -1,6 +1,6 @@
 ---
 title: "OpenAPI Specification"
-description: "Learn how to configure openapi metadata and generate OpenAPI 3.1 documents from your oRPC contracts and routers with OpenAPIGenerator."
+description: "Learn how to configure openapi metadata and generate OpenAPI 3.2, 3.1, or 3.0 documents from your oRPC contracts and routers with OpenAPIGenerator."
 ---
 
 ## Metadata
@@ -38,7 +38,7 @@ For routing metadata, you can learn more in [OpenAPI Routing](/docs/openapi/rout
 
 ### Customizing the Operation Object
 
-Use `spec` to customize the generated operation object. If `spec` is an object, it replaces the generated operation object entirely. If `spec` is a callback, it receives the final operation object and returns an extended version.
+Use `spec` to customize the generated operation object. If `spec` is an object, it replaces the generated operation object entirely. If `spec` is a callback, it receives the final operation object and returns an extended version. The operation object always follows OpenAPI 3.2, whatever [version](#openapi-version) you generate.
 
 ```ts
 const getPlanet = oc
@@ -131,7 +131,7 @@ In this example, the final `tags` is `undefined`, so no tags are applied to `exa
 
 ## OpenAPI Generator
 
-`OpenAPIGenerator` accepts either a [contract](/docs/contract/router) or a [router](/docs/router) and generates an OpenAPI 3.1 document by default. OpenAPI 3.2 is partially supported.
+`OpenAPIGenerator` turns a [contract](/docs/contract/router) or a [router](/docs/router) into an OpenAPI document.
 
 ```ts
 import { OpenAPIGenerator } from '@orpc/openapi'
@@ -141,6 +141,7 @@ const generator = new OpenAPIGenerator({
 })
 
 const spec = await generator.generate(router, {
+  version: '3.2.0',
   base: {
     info: {
       title: 'Planet API',
@@ -153,18 +154,24 @@ const spec = await generator.generate(router, {
 })
 ```
 
-### QUERY method
+`base` provides the OpenAPI 3.2 document fields to start from, such as `info`, `servers`, or `components`. The `openapi` field comes from `version`.
 
-If your router contains a procedure that uses the `QUERY` method, explicitly set the OpenAPI version to `3.2.0`, because OpenAPI 3.1 does not support `QUERY`.
+### OpenAPI Version
+
+`version` selects the OpenAPI version, `3.2.0` by default. Any `3.0.x`, `3.1.x`, or `3.2.x` value works.
 
 ```ts
 const spec = await generator.generate(router, {
-  base: {
-    openapi: '3.2.0',
-  },
+  version: '3.0.4',
 })
 ```
 
+The document is always built as OpenAPI 3.2, so `base`, [`openapi({ spec })`](#customizing-the-operation-object), and every JSON schema follow 3.2. Older versions come from downgrading the whole document with [`@openapi-spec/downgrader`](https://github.com/middleapi/openapi-spec/blob/main/packages/downgrader/README.md), which converts what the older version can still express and removes the rest.
+
+:::warning
+`QUERY` operations require OpenAPI 3.2. Generating an older version from a router with a `QUERY` procedure throws.
+:::
+
 ### Json Schema Converters
 
 `OpenAPIGenerator` relies on JSON Schema converters to translate your input, output, and error schemas into JSON Schemas. oRPC provides dedicated converters through the [Zod](/docs/integrations/zod), [Valibot](/docs/integrations/valibot), and [ArkType](/docs/integrations/arktype) integrations:

eslint.config.js

@@ -39,10 +39,8 @@ export default antfu({
     'no-restricted-imports': ['error', {
       patterns: [{
         group: [
-          '/json-schema-typed',
-          '/openapi-types',
+          '/@openapi-spec/types',
           '/@standard-schema/spec',
-          '/@hey-api/spec-types',
           '/compression',
         ],
         message: 'Please import from @orpc/* instead',

packages/json-schema/package.json

@@ -45,12 +45,12 @@
     "type:check": "tsc -b"
   },
   "dependencies": {
+    "@openapi-spec/types": "~0.1.0",
     "@orpc/client": "workspace:*",
     "@orpc/contract": "workspace:*",
     "@orpc/server": "workspace:*",
     "@orpc/shared": "workspace:*",
-    "@standard-schema/spec": "^1.1.0",
-    "json-schema-typed": "^8.0.2"
+    "@standard-schema/spec": "^1.1.0"
   },
   "devDependencies": {
     "zod": "^4.5.4"

packages/json-schema/src/coercer.ts

@@ -161,7 +161,7 @@ export class JsonSchemaCoercer {
                 : []
 
             const itemSchema: JsonSchema | undefined = Array.isArray(schema.items)
-              ? schema.additionalItems
+              ? schema.additionalItems as JsonSchema | undefined
               : schema.items as JsonSchema | undefined
 
             let shouldUseCoercedItems = false

packages/json-schema/src/composition-utils.test.ts

@@ -1548,15 +1548,16 @@ describe('combineJsonSchemasWithComposition', () => {
       {
         allOf: [{ $ref: '#/$defs/toString' }, { $ref: '#/$defs/valueOf' }],
         $defs: {
-          toString: { type: 'string' },
-          constructor: { type: 'boolean' },
+          // Object.prototype member names get a method contextual type, `satisfies` keeps `type` literal
+          toString: { type: 'string' } satisfies JsonSchema,
+          constructor: { type: 'boolean' } satisfies JsonSchema,
         },
       },
       {
         $ref: '#/$defs/toString',
         $defs: {
-          toString: { type: 'number' },
-          constructor: { type: 'boolean' },
+          toString: { type: 'number' } satisfies JsonSchema,
+          constructor: { type: 'boolean' } satisfies JsonSchema,
         },
       },
     ])).toEqual({
@@ -1581,7 +1582,7 @@ describe('combineJsonSchemasWithComposition', () => {
   it('never lets two renames in the same branch land on the same target', () => {
     // A skips the taken A2..A11 and lands on A12, which A1 would otherwise take as its own first choice
     const taken = Object.fromEntries(
-      ['A', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10', 'A11'].map(name => [name, { type: 'string' }]),
+      ['A', 'A1', 'A2', 'A3', 'A4', 'A5', 'A6', 'A7', 'A8', 'A9', 'A10', 'A11'].map((name): [string, JsonSchema] => [name, { type: 'string' }]),
     )
 
     expect(combineJsonSchemasWithComposition('anyOf', [

packages/json-schema/src/types.ts

@@ -1,13 +1,54 @@
 // eslint-disable-next-line no-restricted-imports
-import type * as Draft2020 from 'json-schema-typed/draft-2020-12'
+import type { OpenAPIV3_2 } from '@openapi-spec/types'
 
 /**
  * A JSON Schema (draft 2020-12) representation used across oRPC's JSON schema tooling.
  *
+ * @remarks
+ * It is also the OpenAPI 3.2 Schema Object, so converted schemas embed into OpenAPI documents as-is.
+ *
  * @see {@link https://orpc.dev/docs/integrations/standard-schema | Standard Schema Integration}
  */
-export type JsonSchema<Value = any> = Draft2020.JSONSchema<Value>
-export type JsonSchemaKeywords = typeof Draft2020.keywords[number]
+export type JsonSchema<Value = any> = OpenAPIV3_2.SchemaObject<Value>
+
+/**
+ * The declared JSON Schema keywords, the index signature is filtered out.
+ */
+export type JsonSchemaKeywords = keyof {
+  [K in keyof OpenAPIV3_2.SchemaObjectFields as string extends K ? never : K]: unknown
+}
+
+export enum JsonSchemaType {
+  Array = 'array',
+  Boolean = 'boolean',
+  Integer = 'integer',
+  Null = 'null',
+  Number = 'number',
+  Object = 'object',
+  String = 'string',
+}
+
+export enum JsonSchemaFormat {
+  Date = 'date',
+  DateTime = 'date-time',
+  Duration = 'duration',
+  Email = 'email',
+  Hostname = 'hostname',
+  IDNEmail = 'idn-email',
+  IDNHostname = 'idn-hostname',
+  IPv4 = 'ipv4',
+  IPv6 = 'ipv6',
+  IRI = 'iri',
+  IRIReference = 'iri-reference',
+  JSONPointer = 'json-pointer',
+  RegEx = 'regex',
+  RelativeJSONPointer = 'relative-json-pointer',
+  Time = 'time',
+  URI = 'uri',
+  URIReference = 'uri-reference',
+  URITemplate = 'uri-template',
+  UUID = 'uuid',
+}
 
 export enum JsonSchemaXNativeType {
   BigInt = 'bigint',
@@ -17,6 +58,3 @@ export enum JsonSchemaXNativeType {
   Set = 'set',
   Map = 'map',
 }
-
-// eslint-disable-next-line no-restricted-imports
-export { Format as JsonSchemaFormat, TypeName as JsonSchemaType } from 'json-schema-typed/draft-2020-12'

packages/openapi/package.json

@@ -115,7 +115,8 @@
     }
   },
   "dependencies": {
-    "@hey-api/spec-types": "0.0.0-next-20260408030107",
+    "@openapi-spec/downgrader": "~0.1.0",
+    "@openapi-spec/types": "~0.1.0",
     "@orpc/client": "workspace:*",
     "@orpc/contract": "workspace:*",
     "@orpc/json-schema": "workspace:*",

packages/openapi/src/meta.ts

@@ -2,7 +2,7 @@ import type { AnyProcedureContract, AnySchema, ErrorMap, MetaPlugin } from '@orp
 import type { Lazy } from '@orpc/server'
 import type { Value } from '@orpc/shared'
 import type { StandardBodyHint } from '@standard-server/core'
-import type { OpenAPIOperationObject } from './types'
+import type { OpenAPIV3_2 } from './types'
 import { mergeHttpPath } from '@orpc/shared'
 
 export interface OpenAPIMeta {
@@ -289,6 +289,9 @@ export interface OpenAPIMeta {
    * Pass a plain object to replace entire operation object, or a function that receives the current
    * operation object and returns the modified version.
    *
+   * The operation object always follows OpenAPI 3.2, `OpenAPIGenerator` downgrades it with the
+   * rest of the document when an older version is requested.
+   *
    * **Merging**: When defined multiple times:
    *
    * - Two functions are chained: the most recent function receives the result of the previous one.
@@ -297,7 +300,7 @@ export interface OpenAPIMeta {
    *
    * Explicitly setting `undefined` resets the spec instead of merging.
    */
-  spec?: Value<OpenAPIOperationObject, [current: OpenAPIOperationObject]>
+  spec?: Value<OpenAPIV3_2.OperationObject, [current: OpenAPIV3_2.OperationObject]>
 
   /**
    * Prefix for the path. Useful when you want to apply a common path prefix across multiple procedures.

packages/openapi/src/openapi-generator-components.test.ts

@@ -1,14 +1,14 @@
 import type { JsonSchema } from '@orpc/json-schema'
-import type { OpenAPIDocument } from './types'
+import type { OpenAPIV3_2 } from './types'
 import { OpenAPIComponentRegistry } from './openapi-generator-components'
 
 describe('openAPIComponentRegistry', () => {
   function createRegistry(options: {
     schemas?: Record<string, any>
     customComponentName?: (defName: string, defSchema: JsonSchema) => string | undefined
   } = {}) {
-    const doc: OpenAPIDocument = {
-      openapi: '3.1.2',
+    const doc: OpenAPIV3_2.OpenAPIObject = {
+      openapi: '3.2.0',
       info: { title: 'API Reference', version: '0.0.0' },
       ...(options.schemas ? { components: { schemas: options.schemas } } : {}),
     }