@nanobpm/urban 0.40.0 → 0.40.1

package/dist/openapi/spec.d.ts

@@ -2,7 +2,7 @@
  *  are ignored by the validator and fall back to `unknown` in the type emitter. */
 export interface OpenApiSchema {
     $ref?: string;
-    type?: string;
+    type?: string | string[];
     nullable?: boolean;
     enum?: unknown[];
     const?: unknown;
@@ -25,6 +25,21 @@ export interface OpenApiSchema {
     anyOf?: OpenApiSchema[];
     description?: string;
 }
+/**
+ * The declared JSON-Schema `type`(s) as a list, normalizing OpenAPI 3.0 (a single string) and
+ * 3.1 (a `string[]`) into one shape. Returns `[]` when no `type` keyword is present, so callers
+ * distinguish "typeless" (infer from other keywords) from "typed".
+ */
+export declare function schemaTypeList(schema: OpenApiSchema): string[];
+/** The declared non-"null" value types — what a 3.1 `type: [T, "null"]` permits as a value. */
+export declare function schemaValueTypes(schema: OpenApiSchema): string[];
+/** The first declared non-"null" value type (for single-type scalar logic), or `undefined`. */
+export declare function firstValueType(schema: OpenApiSchema): string | undefined;
+/** Whether the schema permits an explicit `null` — via OpenAPI 3.0 `nullable: true` or the 3.1
+ *  idiom `type: [..., "null"]`. */
+export declare function schemaAllowsNull(schema: OpenApiSchema): boolean;
+/** Whether the schema declares (permits) the given non-"null" value type. */
+export declare function schemaHasType(schema: OpenApiSchema, t: string): boolean;
 /**
  * Whether a schema describes an object shape. OpenAPI/JSON-Schema let the `type`
  * keyword be omitted when `properties`/`required`/`additionalProperties` already imply

package/dist/openapi/spec.js

@@ -8,9 +8,38 @@
 //
 // Scope: the ADR 0058 "supported profile" — JSON bodies, path/query parameters, a JSON
 // requestBody, response codes, and a JSON-Schema subset validator (type/required/enum/numeric &
-// string bounds/pattern/array & object shape/nullable/$ref). Exotic OpenAPI (callbacks, links,
-// XML, discriminated oneOf composition) is intentionally out of scope for this slice.
+// string bounds/pattern/array & object shape/nullable/$ref). The `type` keyword is read in both
+// OpenAPI 3.0 (a single string, `nullable: true` for null) and 3.1 (a `string[]`, e.g. the
+// `type: [T, "null"]` nullable idiom or a multi-type union) dialects. Exotic OpenAPI (callbacks,
+// links, XML, discriminated oneOf composition) is intentionally out of scope for this slice.
 import { parse as parseYaml } from "yaml";
+/**
+ * The declared JSON-Schema `type`(s) as a list, normalizing OpenAPI 3.0 (a single string) and
+ * 3.1 (a `string[]`) into one shape. Returns `[]` when no `type` keyword is present, so callers
+ * distinguish "typeless" (infer from other keywords) from "typed".
+ */
+export function schemaTypeList(schema) {
+    if (schema.type === undefined)
+        return [];
+    return Array.isArray(schema.type) ? schema.type : [schema.type];
+}
+/** The declared non-"null" value types — what a 3.1 `type: [T, "null"]` permits as a value. */
+export function schemaValueTypes(schema) {
+    return schemaTypeList(schema).filter((t) => t !== "null");
+}
+/** The first declared non-"null" value type (for single-type scalar logic), or `undefined`. */
+export function firstValueType(schema) {
+    return schemaValueTypes(schema)[0];
+}
+/** Whether the schema permits an explicit `null` — via OpenAPI 3.0 `nullable: true` or the 3.1
+ *  idiom `type: [..., "null"]`. */
+export function schemaAllowsNull(schema) {
+    return schema.nullable === true || schemaTypeList(schema).includes("null");
+}
+/** Whether the schema declares (permits) the given non-"null" value type. */
+export function schemaHasType(schema, t) {
+    return schemaValueTypes(schema).includes(t);
+}
 /**
  * Whether a schema describes an object shape. OpenAPI/JSON-Schema let the `type`
  * keyword be omitted when `properties`/`required`/`additionalProperties` already imply
@@ -19,9 +48,10 @@ import { parse as parseYaml } from "yaml";
  * the emitted type calls an object is the same body the validator shape-checks.
  */
 export function isObjectSchema(schema) {
-    if (schema.type === "object")
+    const valueTypes = schemaValueTypes(schema);
+    if (valueTypes.includes("object"))
         return true;
-    if (schema.type !== undefined)
+    if (valueTypes.length > 0)
         return false;
     return (schema.properties !== undefined ||
         schema.required !== undefined ||
@@ -494,8 +524,14 @@ function matchesType(declared, value) {
         return actual === "number" || actual === "integer";
     if (declared === "integer")
         return actual === "integer";
+    if (declared === "null")
+        return value === null;
     return actual === declared;
 }
+/** Whether `value` matches any of the declared value types (a 3.1 `type` list is a union). */
+function matchesAnyType(declared, value) {
+    return declared.some((t) => matchesType(t, value));
+}
 /** Validate `value` against `schema` (resolving local $refs against `doc`), returning every issue
  *  found (empty = valid). A pragmatic JSON-Schema subset; unknown keywords are ignored. */
 export function validateValue(doc, schemaIn, value, path = "") {
@@ -505,7 +541,7 @@ export function validateValue(doc, schemaIn, value, path = "") {
     const issues = [];
     const at = path || "(root)";
     if (value === null) {
-        if (schema.nullable === true || schema.type === "null")
+        if (schemaAllowsNull(schema))
             return issues;
         // enum/const may explicitly permit null even without `nullable`.
         if (schema.enum && schema.enum.some((e) => e === null))
@@ -514,14 +550,15 @@ export function validateValue(doc, schemaIn, value, path = "") {
             return issues;
         // Otherwise null is invalid for a typed schema, an object schema (properties/required imply
         // object), or an enum/const that doesn't list null. A truly empty schema ({}) allows anything.
+        const valueTypes = schemaValueTypes(schema);
         if (schema.enum) {
             issues.push({ path: at, message: `must be one of ${JSON.stringify(schema.enum)}` });
         }
         else if (schema.const !== undefined) {
             issues.push({ path: at, message: `must equal ${JSON.stringify(schema.const)}` });
         }
-        else if (schema.type) {
-            issues.push({ path: at, message: `expected ${schema.type}, got null` });
+        else if (valueTypes.length > 0) {
+            issues.push({ path: at, message: `expected ${valueTypes.join(",")}, got null` });
         }
         else if (isObjectSchema(schema)) {
             issues.push({ path: at, message: "expected object, got null" });
@@ -550,11 +587,15 @@ export function validateValue(doc, schemaIn, value, path = "") {
             issues.push({ path: at, message: `must match exactly one schema in oneOf (matched ${matched})` });
         }
     }
-    if (schema.type && !matchesType(schema.type, value)) {
-        issues.push({ path: at, message: `expected ${schema.type}, got ${typeOfValue(value)}` });
+    // `value` is non-null here (the null branch returned above), so match against the declared value
+    // types. Use the full `type` list — not `schemaValueTypes` — so a null-only schema (`["null"]`)
+    // still rejects non-null values instead of skipping the check on an empty value-type list.
+    const declaredTypes = schemaTypeList(schema);
+    if (declaredTypes.length > 0 && !matchesAnyType(declaredTypes, value)) {
+        issues.push({ path: at, message: `expected ${declaredTypes.join(",")}, got ${typeOfValue(value)}` });
         return issues; // the shape checks below assume the declared type held
     }
-    if (schema.type === "string" && typeof value === "string") {
+    if (schemaHasType(schema, "string") && typeof value === "string") {
         if (schema.minLength !== undefined && value.length < schema.minLength) {
             issues.push({ path: at, message: `shorter than minLength ${schema.minLength}` });
         }
@@ -578,7 +619,7 @@ export function validateValue(doc, schemaIn, value, path = "") {
             }
         }
     }
-    if ((schema.type === "number" || schema.type === "integer") && typeof value === "number") {
+    if ((schemaHasType(schema, "number") || schemaHasType(schema, "integer")) && typeof value === "number") {
         // OpenAPI 3.0 uses the boolean form (`exclusiveMinimum: true` makes `minimum` exclusive);
         // JSON Schema 2020-12 (OpenAPI 3.1) uses the numeric form (`exclusiveMinimum: <number>`).
         // Support both so specs in either dialect are validated, not silently under-checked.
@@ -603,7 +644,7 @@ export function validateValue(doc, schemaIn, value, path = "") {
             issues.push({ path: at, message: `must be < ${schema.exclusiveMaximum}` });
         }
     }
-    if (schema.type === "array" && Array.isArray(value)) {
+    if (schemaHasType(schema, "array") && Array.isArray(value)) {
         if (schema.minItems !== undefined && value.length < schema.minItems) {
             issues.push({ path: at, message: `fewer than minItems ${schema.minItems}` });
         }

package/dist/runtime/core/modules/api.js

@@ -15,7 +15,7 @@ import { errorMessage } from "../guards.js";
 import { MODULE_EXTENSION_CANDIDATES } from "../module-path.js";
 import { html, json, normalizeRoutePath } from "../router.js";
 import { resolveAppPath } from "./datasource.js";
-import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, responseSchemaForStatus, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
+import { collectOperations, isSafeOperationId, operationsWithoutId, operationsWithUnsafeId, parseSpec, resolveSchema, responseSchemaForStatus, schemaHasType, schemaValueTypes, toRouteMatcher, undeclaredPathParams, undeclaredSecuritySchemes, evaluateSecurity, validateValue, } from "../../../openapi/spec.js";
 /** The canonical, non-configurable mount prefix for an app's OpenAPI operations. Operations always
  *  live under `/app/api` so page actions, links, and any `callRoute` can name an operation path as a
  *  stable framework constant (`/app/api/<op path>`) — there is no per-app `base` knob to drift. */
@@ -146,28 +146,36 @@ function coerceParam(doc, schema, raw) {
     const s = resolveSchema(doc, schema);
     if (!s)
         return raw;
-    // Effective scalar type: the explicit `type`, else inferred from a typeless `const`/`enum` whose
-    // values are all numbers or all booleans. Without this, a typeless numeric/boolean const/enum
-    // param (whose generated type is a number/boolean literal) could never be satisfied by the wire
-    // string — every request would 400 against a type the runtime otherwise never produces.
-    let t = s.type;
-    if (t === undefined) {
+    // Which value types the schema permits coercion into: the explicit `type`(s), else inferred from a
+    // typeless `const`/`enum` whose values are all numbers or all booleans. Without the inference, a
+    // typeless numeric/boolean const/enum param (whose generated type is a number/boolean literal)
+    // could never be satisfied by the wire string — every request would 400 against a type the runtime
+    // otherwise never produces.
+    let valueTypes = schemaValueTypes(s);
+    if (valueTypes.length === 0) {
         if (typeof s.const === "number")
-            t = "number";
+            valueTypes = ["number"];
         else if (typeof s.const === "boolean")
-            t = "boolean";
+            valueTypes = ["boolean"];
         else if (Array.isArray(s.enum) && s.enum.length > 0) {
             if (s.enum.every((v) => typeof v === "number"))
-                t = "number";
+                valueTypes = ["number"];
             else if (s.enum.every((v) => typeof v === "boolean"))
-                t = "boolean";
+                valueTypes = ["boolean"];
         }
     }
-    if (t === "integer" || t === "number") {
+    // Coerce order-independently for OpenAPI 3.1 multi-type unions: a schema that *allows* number or
+    // boolean gets that coercion attempted regardless of where it sits in the `type` array (so
+    // `["string","integer"]` and `["integer","string"]` behave identically). Each attempt falls back
+    // to the raw string when it doesn't parse, preserving a value that only fits the union's `string`
+    // arm. Number is tried before boolean so a numeric-looking value in a `number|boolean` union
+    // becomes a number (`"true"`/`"false"` aren't numeric, so they still reach the boolean arm).
+    if (valueTypes.includes("integer") || valueTypes.includes("number")) {
         const n = Number(raw);
-        return raw.trim() !== "" && !Number.isNaN(n) ? n : raw;
+        if (raw.trim() !== "" && !Number.isNaN(n))
+            return n;
     }
-    if (t === "boolean") {
+    if (valueTypes.includes("boolean")) {
         if (raw === "true")
             return true;
         if (raw === "false")
@@ -438,7 +446,7 @@ export function mountApi(ctx, app) {
                         continue;
                     const values = Array.isArray(val) ? val : [val];
                     const ps = resolveSchema(d, p.schema);
-                    if (ps?.type === "array") {
+                    if (ps && schemaHasType(ps, "array")) {
                         // Repeated keys (?tag=a&tag=b) form the array; coerce + validate each item, then the
                         // whole array against the schema's array constraints (minItems, items, ...). The coerced
                         // array is what the delegate receives.

package/dist/toolkit/derivers/api.js

@@ -8,7 +8,7 @@
 // the shared `openapi/spec.ts`, so types and runtime never drift.
 import { GENERATED_DIR } from "../artifact.js";
 import { DEFAULT_OPERATIONS_DIR, normalizeApiDir } from "../api-dir.js";
-import { collectOperations, assertUniqueOperationIds, isObjectSchema, refName, } from "../../openapi/spec.js";
+import { collectOperations, assertUniqueOperationIds, isObjectSchema, refName, schemaAllowsNull, schemaTypeList, schemaValueTypes, } from "../../openapi/spec.js";
 /** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
 export const API_BINDINGS_DTS = "api-io.d.ts";
 export const API_BINDINGS_TS = "operations.ts";
@@ -35,7 +35,7 @@ export function schemaToTs(schema, depth = 0) {
         const name = refName(schema.$ref);
         return name ? typeStem(name) : "unknown";
     }
-    const nullable = schema.nullable === true;
+    const nullable = schemaAllowsNull(schema);
     const wrap = (t) => (nullable ? `${t} | null` : t);
     if (Array.isArray(schema.enum) && schema.enum.length > 0) {
         return wrap(schema.enum.map((v) => JSON.stringify(v)).join(" | "));
@@ -51,7 +51,13 @@ export function schemaToTs(schema, depth = 0) {
     if (Array.isArray(schema.allOf) && schema.allOf.length > 0) {
         return wrap(schema.allOf.map((s) => schemaToTs(s, depth + 1)).join(" & "));
     }
-    switch (schema.type) {
+    // Value types, normalized from OpenAPI 3.0 (single string) or 3.1 (array, e.g. `[T, "null"]` or a
+    // multi-type union). `null` is stripped here and re-applied by `wrap` via `schemaAllowsNull`.
+    const valueTypes = schemaValueTypes(schema);
+    if (valueTypes.length > 1) {
+        return wrap(valueTypes.map((t) => tsForScalarType(t, schema, depth)).join(" | "));
+    }
+    switch (valueTypes[0]) {
         case "string":
             return wrap("string");
         case "integer":
@@ -59,20 +65,40 @@ export function schemaToTs(schema, depth = 0) {
             return wrap("number");
         case "boolean":
             return wrap("boolean");
-        case "null":
-            return "null";
         case "array":
             return wrap(`Array<${schemaToTs(schema.items, depth + 1)}>`);
         case "object":
             return wrap(objectToTs(schema, depth));
         default:
-            // No `type`: infer object-ness from object-only keywords (shared with the runtime
-            // validator via isObjectSchema so types and validation agree); otherwise unknown.
+            // No value type. A schema whose only declared type is "null" is exactly `null`; otherwise
+            // infer object-ness from object-only keywords (shared with the runtime validator via
+            // isObjectSchema so types and validation agree), else fall back to unknown.
+            if (schemaTypeList(schema).length > 0 && schemaValueTypes(schema).length === 0)
+                return "null";
             if (isObjectSchema(schema))
                 return wrap(objectToTs(schema, depth));
             return "unknown";
     }
 }
+/** The TS expression for a single (non-"null") JSON-Schema value type. Nullability is applied by
+ *  the caller's `wrap`, so this never emits `| null`. */
+function tsForScalarType(t, schema, depth) {
+    switch (t) {
+        case "string":
+            return "string";
+        case "integer":
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return `Array<${schemaToTs(schema.items, depth + 1)}>`;
+        case "object":
+            return objectToTs(schema, depth);
+        default:
+            return "unknown";
+    }
+}
 function objectToTs(schema, depth) {
     const props = schema.properties ?? {};
     const required = new Set(schema.required ?? []);

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.40.0",
+	"version": "0.40.1",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",
@@ -66,7 +66,7 @@
 		"@nanobpm/nano-sdk": "^1.2.3",
 		"@nanobpm/workflow": "^0.8.0",
 		"bpmn-auto-layout": "^2.0.0-alpha.2",
-		"create-urban-app": "^0.12.0",
+		"create-urban-app": "^0.13.0",
 		"yaml": "^2.9.0"
 	},
 	"devDependencies": {

package/src/openapi/spec.test.ts

@@ -208,6 +208,53 @@ test("isObjectSchema treats typeless property/required/additionalProperties sche
   assert.equal(isObjectSchema({}), false); // no shape keywords → not an object
 });
 
+test("isObjectSchema understands OpenAPI 3.1 nullable type-arrays", () => {
+  assert.equal(isObjectSchema({ type: ["object", "null"] }), true); // nullable object is an object
+  assert.equal(isObjectSchema({ type: ["string", "null"] }), false); // nullable scalar is not
+});
+
+test("validateValue accepts OpenAPI 3.1 nullable type-arrays (type: [T, null])", () => {
+  // The 3.1 idiom `type: [T, "null"]` must be treated exactly like 3.0 `nullable: true`: the value
+  // type is accepted, an explicit null is accepted, and a wrong type is still rejected.
+  const nullableStr: OpenApiSchema = { type: ["string", "null"] };
+  assert.deepEqual(validateValue(doc, nullableStr, "hi"), []);
+  assert.deepEqual(validateValue(doc, nullableStr, null), []);
+  assert.equal(validateValue(doc, nullableStr, 42).length, 1);
+
+  const nullableInt: OpenApiSchema = { type: ["integer", "null"] };
+  assert.deepEqual(validateValue(doc, nullableInt, 7), []);
+  assert.deepEqual(validateValue(doc, nullableInt, null), []);
+  assert.equal(validateValue(doc, nullableInt, "no").length, 1);
+});
+
+test("validateValue keeps bounds + multi-type unions under 3.1 type-arrays", () => {
+  // String bounds still apply to the string arm of a nullable string.
+  const bounded: OpenApiSchema = { type: ["string", "null"], minLength: 2 };
+  assert.deepEqual(validateValue(doc, bounded, "ok"), []);
+  assert.deepEqual(validateValue(doc, bounded, null), []);
+  assert.equal(validateValue(doc, bounded, "x").length, 1); // shorter than minLength
+
+  // A genuine multi-type union (no null) accepts any listed type, rejects others.
+  const strOrNum: OpenApiSchema = { type: ["string", "number"] };
+  assert.deepEqual(validateValue(doc, strOrNum, "a"), []);
+  assert.deepEqual(validateValue(doc, strOrNum, 1), []);
+  assert.equal(validateValue(doc, strOrNum, true).length, 1);
+  assert.equal(validateValue(doc, strOrNum, null).length, 1); // null not permitted without "null"
+});
+
+test("validateValue rejects non-null values for a null-only schema (type: [null] / type: null)", () => {
+  // A schema whose only declared type is "null" must accept null and reject everything else — the
+  // value-type list is empty, so the type check must fall back to the full `type` list.
+  const nullOnlyArr: OpenApiSchema = { type: ["null"] };
+  assert.deepEqual(validateValue(doc, nullOnlyArr, null), []);
+  assert.equal(validateValue(doc, nullOnlyArr, "x").length, 1);
+  assert.equal(validateValue(doc, nullOnlyArr, 0).length, 1);
+
+  const nullOnlyStr: OpenApiSchema = { type: "null" };
+  assert.deepEqual(validateValue(doc, nullOnlyStr, null), []);
+  assert.equal(validateValue(doc, nullOnlyStr, "x").length, 1);
+});
+
 test("validateValue shape-checks typeless object schemas (no type/runtime drift)", () => {
   // A schema with properties/required but no explicit `type: "object"` is emitted as an object
   // by schemaToTs, so the validator must shape-check it too — otherwise invalid bodies pass.

package/src/openapi/spec.ts

@@ -8,8 +8,10 @@
 //
 // Scope: the ADR 0058 "supported profile" — JSON bodies, path/query parameters, a JSON
 // requestBody, response codes, and a JSON-Schema subset validator (type/required/enum/numeric &
-// string bounds/pattern/array & object shape/nullable/$ref). Exotic OpenAPI (callbacks, links,
-// XML, discriminated oneOf composition) is intentionally out of scope for this slice.
+// string bounds/pattern/array & object shape/nullable/$ref). The `type` keyword is read in both
+// OpenAPI 3.0 (a single string, `nullable: true` for null) and 3.1 (a `string[]`, e.g. the
+// `type: [T, "null"]` nullable idiom or a multi-type union) dialects. Exotic OpenAPI (callbacks,
+// links, XML, discriminated oneOf composition) is intentionally out of scope for this slice.
 
 import { parse as parseYaml } from "yaml";
 
@@ -17,7 +19,11 @@ import { parse as parseYaml } from "yaml";
  *  are ignored by the validator and fall back to `unknown` in the type emitter. */
 export interface OpenApiSchema {
   $ref?: string;
-  type?: string;
+  // OpenAPI 3.0 uses a single `type` string; JSON Schema 2020-12 (OpenAPI 3.1) also permits an
+  // array of types, most commonly the nullable idiom `type: [T, "null"]`. Both dialects are read
+  // via the `schemaTypeList`/`schemaValueTypes`/`schemaAllowsNull`/`schemaHasType` helpers so the
+  // type emitter and the runtime validator treat a 3.1 type-array the same way.
+  type?: string | string[];
   nullable?: boolean;
   enum?: unknown[];
   const?: unknown;
@@ -46,6 +52,37 @@ export interface OpenApiSchema {
   description?: string;
 }
 
+/**
+ * The declared JSON-Schema `type`(s) as a list, normalizing OpenAPI 3.0 (a single string) and
+ * 3.1 (a `string[]`) into one shape. Returns `[]` when no `type` keyword is present, so callers
+ * distinguish "typeless" (infer from other keywords) from "typed".
+ */
+export function schemaTypeList(schema: OpenApiSchema): string[] {
+  if (schema.type === undefined) return [];
+  return Array.isArray(schema.type) ? schema.type : [schema.type];
+}
+
+/** The declared non-"null" value types — what a 3.1 `type: [T, "null"]` permits as a value. */
+export function schemaValueTypes(schema: OpenApiSchema): string[] {
+  return schemaTypeList(schema).filter((t) => t !== "null");
+}
+
+/** The first declared non-"null" value type (for single-type scalar logic), or `undefined`. */
+export function firstValueType(schema: OpenApiSchema): string | undefined {
+  return schemaValueTypes(schema)[0];
+}
+
+/** Whether the schema permits an explicit `null` — via OpenAPI 3.0 `nullable: true` or the 3.1
+ *  idiom `type: [..., "null"]`. */
+export function schemaAllowsNull(schema: OpenApiSchema): boolean {
+  return schema.nullable === true || schemaTypeList(schema).includes("null");
+}
+
+/** Whether the schema declares (permits) the given non-"null" value type. */
+export function schemaHasType(schema: OpenApiSchema, t: string): boolean {
+  return schemaValueTypes(schema).includes(t);
+}
+
 /**
  * Whether a schema describes an object shape. OpenAPI/JSON-Schema let the `type`
  * keyword be omitted when `properties`/`required`/`additionalProperties` already imply
@@ -54,8 +91,9 @@ export interface OpenApiSchema {
  * the emitted type calls an object is the same body the validator shape-checks.
  */
 export function isObjectSchema(schema: OpenApiSchema): boolean {
-  if (schema.type === "object") return true;
-  if (schema.type !== undefined) return false;
+  const valueTypes = schemaValueTypes(schema);
+  if (valueTypes.includes("object")) return true;
+  if (valueTypes.length > 0) return false;
   return (
     schema.properties !== undefined ||
     schema.required !== undefined ||
@@ -650,9 +688,15 @@ function matchesType(declared: string, value: unknown): boolean {
   const actual = typeOfValue(value);
   if (declared === "number") return actual === "number" || actual === "integer";
   if (declared === "integer") return actual === "integer";
+  if (declared === "null") return value === null;
   return actual === declared;
 }
 
+/** Whether `value` matches any of the declared value types (a 3.1 `type` list is a union). */
+function matchesAnyType(declared: string[], value: unknown): boolean {
+  return declared.some((t) => matchesType(t, value));
+}
+
 /** Validate `value` against `schema` (resolving local $refs against `doc`), returning every issue
  *  found (empty = valid). A pragmatic JSON-Schema subset; unknown keywords are ignored. */
 export function validateValue(
@@ -667,18 +711,19 @@ export function validateValue(
   const at = path || "(root)";
 
   if (value === null) {
-    if (schema.nullable === true || schema.type === "null") return issues;
+    if (schemaAllowsNull(schema)) return issues;
     // enum/const may explicitly permit null even without `nullable`.
     if (schema.enum && schema.enum.some((e) => e === null)) return issues;
     if (schema.const === null) return issues;
     // Otherwise null is invalid for a typed schema, an object schema (properties/required imply
     // object), or an enum/const that doesn't list null. A truly empty schema ({}) allows anything.
+    const valueTypes = schemaValueTypes(schema);
     if (schema.enum) {
       issues.push({ path: at, message: `must be one of ${JSON.stringify(schema.enum)}` });
     } else if (schema.const !== undefined) {
       issues.push({ path: at, message: `must equal ${JSON.stringify(schema.const)}` });
-    } else if (schema.type) {
-      issues.push({ path: at, message: `expected ${schema.type}, got null` });
+    } else if (valueTypes.length > 0) {
+      issues.push({ path: at, message: `expected ${valueTypes.join(",")}, got null` });
     } else if (isObjectSchema(schema)) {
       issues.push({ path: at, message: "expected object, got null" });
     }
@@ -708,12 +753,16 @@ export function validateValue(
     }
   }
 
-  if (schema.type && !matchesType(schema.type, value)) {
-    issues.push({ path: at, message: `expected ${schema.type}, got ${typeOfValue(value)}` });
+  // `value` is non-null here (the null branch returned above), so match against the declared value
+  // types. Use the full `type` list — not `schemaValueTypes` — so a null-only schema (`["null"]`)
+  // still rejects non-null values instead of skipping the check on an empty value-type list.
+  const declaredTypes = schemaTypeList(schema);
+  if (declaredTypes.length > 0 && !matchesAnyType(declaredTypes, value)) {
+    issues.push({ path: at, message: `expected ${declaredTypes.join(",")}, got ${typeOfValue(value)}` });
     return issues; // the shape checks below assume the declared type held
   }
 
-  if (schema.type === "string" && typeof value === "string") {
+  if (schemaHasType(schema, "string") && typeof value === "string") {
     if (schema.minLength !== undefined && value.length < schema.minLength) {
       issues.push({ path: at, message: `shorter than minLength ${schema.minLength}` });
     }
@@ -737,7 +786,7 @@ export function validateValue(
     }
   }
 
-  if ((schema.type === "number" || schema.type === "integer") && typeof value === "number") {
+  if ((schemaHasType(schema, "number") || schemaHasType(schema, "integer")) && typeof value === "number") {
     // OpenAPI 3.0 uses the boolean form (`exclusiveMinimum: true` makes `minimum` exclusive);
     // JSON Schema 2020-12 (OpenAPI 3.1) uses the numeric form (`exclusiveMinimum: <number>`).
     // Support both so specs in either dialect are validated, not silently under-checked.
@@ -763,7 +812,7 @@ export function validateValue(
     }
   }
 
-  if (schema.type === "array" && Array.isArray(value)) {
+  if (schemaHasType(schema, "array") && Array.isArray(value)) {
     if (schema.minItems !== undefined && value.length < schema.minItems) {
       issues.push({ path: at, message: `fewer than minItems ${schema.minItems}` });
     }

package/src/runtime/core/modules/api.test.ts

@@ -457,6 +457,87 @@ test("params/query are coerced to their schema type before reaching the delegate
   assert.deepEqual(got, { params: { id: 42 }, query: { verbose: true, tags: ["x", "y"] } });
 });
 
+test("3.1 nullable-typed params still coerce (type: [T, null]) and array-typed repeats still group", async () => {
+  // A param declared with the OpenAPI 3.1 nullable idiom must coerce on its value type exactly like
+  // the 3.0 single-type form — otherwise a `type: ["integer","null"]` query would reach the delegate
+  // as a raw string (and an array-typed nullable would reject repeats).
+  const spec = JSON.stringify({
+    openapi: "3.1.0",
+    paths: {
+      "/things/{id}": {
+        get: {
+          operationId: "getThing",
+          parameters: [
+            { name: "id", in: "path", required: true, schema: { type: ["integer", "null"] } },
+            { name: "tags", in: "query", schema: { type: ["array", "null"], items: { type: "string" } } },
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: { params: Record<string, unknown>; query: Record<string, unknown> } | undefined;
+  const { router } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/operations/getThing": {
+        default: (i: { params: Record<string, unknown>; query: Record<string, unknown> }) => {
+          got = { params: i.params, query: i.query };
+          return { body: { ok: true } };
+        },
+      },
+    },
+    spec,
+  );
+  const res = await router(req("GET", "/app/api/things/7", { query: "tags=x&tags=y" }));
+  assert.equal(res.status, 200);
+  assert.deepEqual(got, { params: { id: 7 }, query: { tags: ["x", "y"] } });
+});
+
+test("3.1 multi-type union params coerce order-independently (type array order doesn't matter)", async () => {
+  // A 3.1 union like `["string","integer"]` must coerce numeric-looking values to numbers regardless
+  // of where `integer`/`number` sits in the array — otherwise coercion is order-dependent and a
+  // `["string","integer"]` param would never enforce numeric bounds (it'd reach the delegate as a
+  // raw string), while `["integer","string"]` would. Non-numeric values still fall back to the
+  // string arm, and a `number|boolean` union coerces each token to its natural type.
+  const spec = JSON.stringify({
+    openapi: "3.1.0",
+    paths: {
+      "/u": {
+        get: {
+          operationId: "u",
+          parameters: [
+            { name: "a", in: "query", required: true, schema: { type: ["string", "integer"] } },
+            { name: "b", in: "query", required: true, schema: { type: ["integer", "string"] } },
+            { name: "c", in: "query", required: true, schema: { type: ["string", "integer"] } },
+            { name: "d", in: "query", required: true, schema: { type: ["number", "boolean"] } },
+            { name: "e", in: "query", required: true, schema: { type: ["number", "boolean"] } },
+          ],
+          responses: { "200": {} },
+        },
+      },
+    },
+  });
+  let got: { query: Record<string, unknown> } | undefined;
+  const { router } = build(
+    { spec: "openapi.json" },
+    {
+      "/app/operations/u": {
+        default: (i: { query: Record<string, unknown> }) => {
+          got = { query: i.query };
+          return { body: { ok: true } };
+        },
+      },
+    },
+    spec,
+  );
+  const res = await router(req("GET", "/app/api/u", { query: "a=42&b=42&c=hello&d=3.5&e=true" }));
+  assert.equal(res.status, 200);
+  // a and b both coerce to 42 despite opposite type-array order; c stays a string (only fits the
+  // union's string arm); d coerces to a number, e to a boolean.
+  assert.deepEqual(got, { query: { a: 42, b: 42, c: "hello", d: 3.5, e: true } });
+});
+
 test("a typeless numeric const/enum query param coerces (so its number-literal type is satisfiable)", async () => {
   const enumSpec = JSON.stringify({
     openapi: "3.1.0",

package/src/runtime/core/modules/api.ts

@@ -29,6 +29,8 @@ import {
   parseSpec,
   resolveSchema,
   responseSchemaForStatus,
+  schemaHasType,
+  schemaValueTypes,
   toRouteMatcher,
   undeclaredPathParams,
   undeclaredSecuritySchemes,
@@ -249,24 +251,31 @@ export function apiDocsPath(manifest: unknown): string | undefined {
 function coerceParam(doc: OpenApiDoc, schema: OpenApiSchema | undefined, raw: string): unknown {
   const s = resolveSchema(doc, schema);
   if (!s) return raw;
-  // Effective scalar type: the explicit `type`, else inferred from a typeless `const`/`enum` whose
-  // values are all numbers or all booleans. Without this, a typeless numeric/boolean const/enum
-  // param (whose generated type is a number/boolean literal) could never be satisfied by the wire
-  // string — every request would 400 against a type the runtime otherwise never produces.
-  let t = s.type;
-  if (t === undefined) {
-    if (typeof s.const === "number") t = "number";
-    else if (typeof s.const === "boolean") t = "boolean";
+  // Which value types the schema permits coercion into: the explicit `type`(s), else inferred from a
+  // typeless `const`/`enum` whose values are all numbers or all booleans. Without the inference, a
+  // typeless numeric/boolean const/enum param (whose generated type is a number/boolean literal)
+  // could never be satisfied by the wire string — every request would 400 against a type the runtime
+  // otherwise never produces.
+  let valueTypes = schemaValueTypes(s);
+  if (valueTypes.length === 0) {
+    if (typeof s.const === "number") valueTypes = ["number"];
+    else if (typeof s.const === "boolean") valueTypes = ["boolean"];
     else if (Array.isArray(s.enum) && s.enum.length > 0) {
-      if (s.enum.every((v) => typeof v === "number")) t = "number";
-      else if (s.enum.every((v) => typeof v === "boolean")) t = "boolean";
+      if (s.enum.every((v) => typeof v === "number")) valueTypes = ["number"];
+      else if (s.enum.every((v) => typeof v === "boolean")) valueTypes = ["boolean"];
     }
   }
-  if (t === "integer" || t === "number") {
+  // Coerce order-independently for OpenAPI 3.1 multi-type unions: a schema that *allows* number or
+  // boolean gets that coercion attempted regardless of where it sits in the `type` array (so
+  // `["string","integer"]` and `["integer","string"]` behave identically). Each attempt falls back
+  // to the raw string when it doesn't parse, preserving a value that only fits the union's `string`
+  // arm. Number is tried before boolean so a numeric-looking value in a `number|boolean` union
+  // becomes a number (`"true"`/`"false"` aren't numeric, so they still reach the boolean arm).
+  if (valueTypes.includes("integer") || valueTypes.includes("number")) {
     const n = Number(raw);
-    return raw.trim() !== "" && !Number.isNaN(n) ? n : raw;
+    if (raw.trim() !== "" && !Number.isNaN(n)) return n;
   }
-  if (t === "boolean") {
+  if (valueTypes.includes("boolean")) {
     if (raw === "true") return true;
     if (raw === "false") return false;
   }
@@ -571,7 +580,7 @@ export function mountApi(ctx: RuntimeContext, app: AppApi): ApiHandle {
           if (!p.schema) continue;
           const values = Array.isArray(val) ? val : [val];
           const ps = resolveSchema(d, p.schema);
-          if (ps?.type === "array") {
+          if (ps && schemaHasType(ps, "array")) {
             // Repeated keys (?tag=a&tag=b) form the array; coerce + validate each item, then the
             // whole array against the schema's array constraints (minItems, items, ...). The coerced
             // array is what the delegate receives.

package/src/toolkit/derivers/api.test.ts

@@ -38,6 +38,26 @@ test("schemaToTs renders primitives, enums, arrays, refs, and unknown fallback",
   assert.equal(schemaToTs(undefined), "unknown");
 });
 
+test("schemaToTs renders OpenAPI 3.1 nullable type-arrays as `T | null`", () => {
+  // The 3.1 idiom `type: [T, "null"]` must emit the same `T | null` as 3.0 `nullable: true`,
+  // not degrade to `unknown` (the bug this fixes).
+  assert.equal(schemaToTs({ type: ["string", "null"] }), "string | null");
+  assert.equal(schemaToTs({ type: ["integer", "null"] }), "number | null");
+  assert.equal(schemaToTs({ type: ["boolean", "null"] }), "boolean | null");
+  assert.equal(schemaToTs({ type: ["array", "null"], items: { type: "string" } }), "Array<string> | null");
+  // 3.0 nullable stays equivalent.
+  assert.equal(schemaToTs({ type: "string", nullable: true }), "string | null");
+  // A bare `type: ["null"]` is exactly `null`.
+  assert.equal(schemaToTs({ type: ["null"] }), "null");
+  // A genuine multi-type union renders as a union (plus `| null` when null is present).
+  assert.equal(schemaToTs({ type: ["string", "number"] }), "string | number");
+  assert.equal(schemaToTs({ type: ["string", "number", "null"] }), "string | number | null");
+});
+
+test("schemaToTs renders a 3.1 nullable object type-array as `{...} | null`", () => {
+  assert.match(schemaToTs({ type: ["object", "null"], properties: { a: { type: "string" } } }), /\| null$/);
+});
+
 test("emitApiBindings emits component types + per-op request/response + the id map", () => {
   const out = emitApiBindings(doc);
   assert.match(out, /export type Invoice = \{/);

package/src/toolkit/derivers/api.ts

@@ -18,6 +18,9 @@ import {
   type OpenApiSchema,
   type OperationInfo,
   refName,
+  schemaAllowsNull,
+  schemaTypeList,
+  schemaValueTypes,
 } from "../../openapi/spec.ts";
 
 /** Filenames of the emitted artifacts (siblings of worker-io.d.ts in nano-generated/). */
@@ -49,7 +52,7 @@ export function schemaToTs(schema: OpenApiSchema | undefined, depth = 0): string
     const name = refName(schema.$ref);
     return name ? typeStem(name) : "unknown";
   }
-  const nullable = schema.nullable === true;
+  const nullable = schemaAllowsNull(schema);
   const wrap = (t: string) => (nullable ? `${t} | null` : t);
 
   if (Array.isArray(schema.enum) && schema.enum.length > 0) {
@@ -67,7 +70,13 @@ export function schemaToTs(schema: OpenApiSchema | undefined, depth = 0): string
     return wrap(schema.allOf.map((s) => schemaToTs(s, depth + 1)).join(" & "));
   }
 
-  switch (schema.type) {
+  // Value types, normalized from OpenAPI 3.0 (single string) or 3.1 (array, e.g. `[T, "null"]` or a
+  // multi-type union). `null` is stripped here and re-applied by `wrap` via `schemaAllowsNull`.
+  const valueTypes = schemaValueTypes(schema);
+  if (valueTypes.length > 1) {
+    return wrap(valueTypes.map((t) => tsForScalarType(t, schema, depth)).join(" | "));
+  }
+  switch (valueTypes[0]) {
     case "string":
       return wrap("string");
     case "integer":
@@ -75,20 +84,40 @@ export function schemaToTs(schema: OpenApiSchema | undefined, depth = 0): string
       return wrap("number");
     case "boolean":
       return wrap("boolean");
-    case "null":
-      return "null";
     case "array":
       return wrap(`Array<${schemaToTs(schema.items, depth + 1)}>`);
     case "object":
       return wrap(objectToTs(schema, depth));
     default:
-      // No `type`: infer object-ness from object-only keywords (shared with the runtime
-      // validator via isObjectSchema so types and validation agree); otherwise unknown.
+      // No value type. A schema whose only declared type is "null" is exactly `null`; otherwise
+      // infer object-ness from object-only keywords (shared with the runtime validator via
+      // isObjectSchema so types and validation agree), else fall back to unknown.
+      if (schemaTypeList(schema).length > 0 && schemaValueTypes(schema).length === 0) return "null";
       if (isObjectSchema(schema)) return wrap(objectToTs(schema, depth));
       return "unknown";
   }
 }
 
+/** The TS expression for a single (non-"null") JSON-Schema value type. Nullability is applied by
+ *  the caller's `wrap`, so this never emits `| null`. */
+function tsForScalarType(t: string, schema: OpenApiSchema, depth: number): string {
+  switch (t) {
+    case "string":
+      return "string";
+    case "integer":
+    case "number":
+      return "number";
+    case "boolean":
+      return "boolean";
+    case "array":
+      return `Array<${schemaToTs(schema.items, depth + 1)}>`;
+    case "object":
+      return objectToTs(schema, depth);
+    default:
+      return "unknown";
+  }
+}
+
 function objectToTs(schema: OpenApiSchema, depth: number): string {
   const props = schema.properties ?? {};
   const required = new Set(schema.required ?? []);