typespec-http-zod 0.22.0 → 0.24.0

package/README.md

@@ -148,6 +148,8 @@ carries the whole id, so `op readWidget` in `namespace Widgets` becomes `Widgets
 - [Reference](docs/reference.md): every option, every diagnostic, and the known limits.
 - [Oracles](docs/oracles.md): every artefact this emitter produces, and what compares it to the
   thing it has to agree with.
+- [Releasing](docs/releasing.md): why this package publishes first, and how to rehearse a
+  two-package release against a local registry.
 
 ## Licence
 

package/dist/src/api.d.ts

@@ -373,6 +373,8 @@ export interface ResolvedServiceOptions {
     readonly contractsOutputDir: string | undefined;
     readonly contractsPackage: string | undefined;
     readonly sealObjectSchemas: boolean;
+    /** Whether every emitted validator is wrapped in `z.compile()`. See the option's own docblock. */
+    readonly compileSchemas: boolean;
     readonly keyVocabularies: readonly string[];
     readonly runtimeModule: string;
     /** The command that regenerates, for the banner. `undefined` keeps the generic line. */

package/dist/src/api.js

@@ -680,7 +680,9 @@ function multipartSchemaOf(body, registry) {
                     : registry.expressionFor(type);
         // `multi` is `HttpPart<T>[]` - the same part repeated, which arrives as an array.
         const value = part.multi === true ? `z.array(${inner})` : inner;
-        return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.optional()` : value},`;
+        // `.exactOptional()` for the same reason as a model property: `parseBody` yields present keys
+        // only, so an absent part is an absent key rather than an explicit `undefined`.
+        return `\t${objectKey(part.name ?? "")}: ${part.optional === true ? `${value}.exactOptional()` : value},`;
     });
     const shape = entries.length === 0 ? "z.object({})" : `z.object({\n${entries.join("\n")}\n})`;
     /**
@@ -1266,7 +1268,26 @@ function renderExternalImports(externals, ...bodies) {
  * validate a request or a response against, and every oracle that graded those validators had to read
  * a server to find them. See {@link nameRouteSchemas}.
  */
-function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
+/**
+ * **`z.compile(...)` around a validator, when `compile-schemas` asks for it.**
+ *
+ * Zod walks the schema once and emits a flat, loop-free function through `new Function`, falling back
+ * to the ordinary parser for anything it cannot handle. Measured on zod 4.5.2 before this was written:
+ * `z.toJSONSchema` output is byte-identical, `_zod.def` is unchanged and still readable, and verdicts
+ * AND parsed output match for every construct this emitter writes - including `z.preprocess`,
+ * `.exactOptional()` and a `z.lazy()` cycle. So the two oracles that read a schema rather than run it
+ * are unaffected, and the wrapper is transparent.
+ *
+ * **A cyclic declaration is wrapped too, and that was worth checking rather than assuming.** The
+ * emitted form names the const being defined from inside its own `z.lazy()` body, and this repository
+ * has already shipped a break of exactly that shape - `.strict()` reads `shape` eagerly and throws
+ * `Cannot access 'X' before initialization` during module initialisation. Measured on the emitted
+ * shape: `z.compile()` does not force the lazy body, and the declaration parses.
+ */
+function compiled(expression, on) {
+    return on ? `z.compile(${expression})` : expression;
+}
+function renderSchemas(registry, externals, routeDeclarations, runtimeModule, compileSchemas) {
     const declarations = registry.declarations().map((d) => {
         /**
          * **A declaration on a CYCLE cannot take its type from `z.infer`, because that is the loop.**
@@ -1277,13 +1298,53 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
          * with no cycle emits byte-identical output to before.
          */
         if (d.structural === undefined) {
-            return `\nexport const ${d.identifier} = ${d.source};\nexport type ${d.typeName} = Exact<z.infer<typeof ${d.identifier}>>;\n`;
+            return `\nexport const ${d.identifier} = ${compiled(d.source, compileSchemas)};\nexport type ${d.typeName} = z.infer<typeof ${d.identifier}>;\n`;
         }
         const declared = d.structural.startsWith("{")
             ? `export interface ${d.typeName} ${d.structural}`
             : `export type ${d.typeName} = ${d.structural};`;
-        const annotation = d.annotated === true ? `: z.ZodType<${d.typeName}>` : "";
-        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${d.source};\n`;
+        /**
+         * **BOTH of Zod's type parameters, and naming only the first left the second as `unknown`.**
+         *
+         * `z.ZodType<T>` is `ZodType<Output = T, Input = unknown>`, so a schema annotated with one
+         * parameter reports `z.input<typeof x>` as `unknown` - and every schema that REFERENCES it
+         * inherits that. Measured: `Identical<Declared<z.input<typeof nodeSchema>>, Contracts.Node>`
+         * failed on `branch?: unknown | undefined` against `branch?: Branch | undefined`, in a fixture
+         * whose two artefacts agree about every property. The wire assertion pairs `z.input` because
+         * that is what a caller supplies, so an unannotated input parameter takes the whole cyclic
+         * corner of the emitter out of that comparison.
+         *
+         * **One structural type serves both positions, and for a defaulted property on a cycle it is
+         * the INPUT shape that both get.** A default is the only construct where a schema's input and
+         * output types differ, and a cyclic declaration has exactly one type written out to name - the
+         * loop is what stops `z.infer` being usable at all. Claiming the input shape in the output
+         * position is the PERMISSIVE direction: every value that arrives still satisfies it, a reader
+         * simply learns less than it could about a defaulted property. Claiming the output shape in
+         * the input position is the restrictive one, and it is the defect this release exists to
+         * remove - a caller told to supply what the document says they may omit.
+         *
+         * So the limitation is confined to this: a model on a cycle carrying a defaulted optional
+         * property exports a type from `schemas.gen.ts` that is weaker than what arrives, by exactly
+         * that property. `typespec-hono` derives its handler input from `z.infer` of the schema rather
+         * than from this type, so no handler signature is affected.
+         */
+        const annotation = d.annotated === true ? `: z.ZodType<${d.typeName}, ${d.typeName}>` : "";
+        /**
+         * **A deferred declaration is NEVER compiled, and this was measured rather than reasoned.**
+         *
+         * `z.lazy()` is on Zod's own list of constructs the compiler cannot handle, and here the body
+         * forward-references a `const` declared further down the module. Wrapping it emitted output that
+         * loaded fine and then threw `Cannot read properties of undefined (reading '_zod')` on the first
+         * parse - the walk captures the reference while it is still in the temporal dead zone, so the
+         * failure surfaces at request time rather than at import.
+         *
+         * **Keyed on `annotated`, the fact the registry already holds** - it is set exactly when the
+         * declaration is deferred, which is exactly when `z.lazy()` is written - rather than on the
+         * shape of the emitted text. A model on a cycle whose back edge sits on a GETTER is a different
+         * case and is compiled like any other: measured, it parses, because a getter is not resolved
+         * until something reads it.
+         */
+        return `\n${declared}\nexport const ${d.identifier}${annotation} = ${compiled(d.source, compileSchemas && d.annotated !== true)};\n`;
     });
     /**
      * **Written only when something in the file names it**, like the `ResponseArm` import below and for
@@ -1302,37 +1363,24 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
      * rendered content for the same reason.
      */
     /**
-     * **`Exact` narrows an inferred optional to what the wire can carry.**
-     *
-     * `z.infer` of `.optional()` gives `p?: T | undefined`, which under `exactOptionalPropertyTypes`
-     * admits an explicitly-undefined property. **JSON has no `undefined`**, and the document says the
-     * same thing by leaving the property out of `required`, so the inferred type is wider than the
-     * wire and a consumer reading a payload had to strip it at the boundary.
+     * **`Exact<>` lived here until `0.24.0`, and `z.exactOptional()` replaced it.**
      *
-     * **It does NOT match the contract type, and this docblock used to claim it did.** The
-     * contract types in `requests.gen.ts` keep `?: T | undefined` on purpose: they are the floor a
-     * PRODUCER supplies, and `{ p: undefined }` serialises identically to omitting `p`, so refusing
-     * it would cost every producer a conditional spread and buy the wire nothing. Measured when this
-     * was "fixed" to agree: `(ctx, input) => ok(input)` - return what you were given - stopped
-     * compiling.
+     * It was a mapped type over `z.infer` that stripped `| undefined` off every optional property,
+     * because `.optional()` infers `p?: T | undefined` and **JSON has no `undefined`** - the document
+     * says "absent or a value" by leaving the property out of `required`, so the inferred type was
+     * wider than both the document and the wire.
      *
-     * So the two surfaces differ on this axis deliberately, exactly as they differ on openness: this
-     * one is the narrow view of what ARRIVES, the contract type is the permissive floor for what you
-     * may SEND. A reader comparing them will find them unequal and should - the emitted assertion
-     * pairs the contract against raw `z.infer`, not against this.
+     * The reasoning was right and it was applied to only one of the two artefacts. The VALIDATOR went
+     * on accepting `{ p: undefined }`, so one program published a type refusing a value beside a
+     * validator admitting it, compared by nothing. Emitting `.exactOptional()` makes `z.infer` produce
+     * `p?: T` directly - at every depth, which a shallow mapped type never reached - so the narrowing
+     * happens once, in the schema, and this helper has nothing left to do.
      *
-     * Derived from the same schema rather than hand-written beside it, so there is still one source of
-     * truth: a mapped type cannot drift from the thing it maps.
-     *
-     * Emitted only where a declaration names it, like the imports beside it.
+     * The contract types in `requests.gen.ts` still keep `?: T | undefined` on purpose: they are the
+     * floor a PRODUCER supplies, and `{ p: undefined }` serialises identically to omitting `p`, so
+     * refusing it there would cost every producer a conditional spread and buy the wire nothing.
+     * Narrowing THAT surface was tried in `0.19.0` and reverted - it broke `(ctx, input) => ok(input)`.
      */
-    const EXACT_HELPER = `
-/** An inferred type narrowed to what JSON can carry: an optional property is absent or a value. */
-type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } & {
-	[K in keyof T as undefined extends T[K] ? K : never]?: Exclude<T[K], undefined>;
-};
-`;
-    const usesExact = declarations.some((d) => d.includes("Exact<"));
     const usesZod = new Set([...declarations, ...routeDeclarations].join("").match(/[A-Za-z_$][\w$]*/g) ?? []).has("z");
     const parts = [generatedBanner()];
     if (usesZod)
@@ -1349,8 +1397,6 @@ type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } &
         parts.push(`import type { ResponseArm } from ${JSON.stringify(runtimeModule)};\n`);
     }
     parts.push(renderExternalImports(externals, [...declarations, ...routeDeclarations].join("")));
-    if (usesExact)
-        parts.push(EXACT_HELPER);
     parts.push(declarations.join(""));
     if (routeDeclarations.length > 0)
         parts.push(`\n${routeDeclarations.join("\n")}\n`);
@@ -1367,7 +1413,7 @@ type Exact<T> = { [K in keyof T as undefined extends T[K] ? never : K]: T[K] } &
 const isIdentifier = (expression) => /^[A-Za-z_$][\w$]*$/.test(expression);
 const schemaConst = (operationId, suffix) => `${operationId}${suffix}`;
 /** `[the name to refer to it by, the `const` line to emit]` - the line is absent when none is needed. */
-function namedSchema(operationId, suffix, expression) {
+function namedSchema(operationId, suffix, expression, compileSchemas) {
     if (expression === undefined)
         return { name: undefined, declaration: undefined };
     if (isIdentifier(expression))
@@ -1384,7 +1430,7 @@ function namedSchema(operationId, suffix, expression) {
      * Exporting also gives an application the request shape by name, which is what the per-operation
      * type aliases will be built from.
      */
-    return { name, declaration: `export const ${name} = ${expression};` };
+    return { name, declaration: `export const ${name} = ${compiled(expression, compileSchemas)};` };
 }
 /**
  * Which `verb path` slots carry more than one operation.
@@ -1426,13 +1472,13 @@ function sharedSlots(routes) {
  * Declaring them here dissolves all three: the library mints the names AND emits them, and a server
  * emitter imports what it is told rather than agreeing about it.
  */
-function nameRouteSchemas(routes) {
+function nameRouteSchemas(routes, compileSchemas) {
     const shared = sharedSlots(routes);
     const declarations = [];
     const names = new Map();
     for (const route of routes) {
         const declare = (suffix, expression) => {
-            const resolved = namedSchema(route.operationId, suffix, expression);
+            const resolved = namedSchema(route.operationId, suffix, expression, compileSchemas);
             if (resolved.declaration !== undefined)
                 declarations.push(resolved.declaration);
             return resolved.name;
@@ -1795,8 +1841,26 @@ ${responseLookup}
  * both look right in isolation. That happened during this emitter's first run: a vocabulary in a
  * query-parameter position was inlined by one walk and referenced by the other.
  *
- * `Equals` here, not assignability - `z.infer` is the output type, and the wire type is emitted with
- * defaulted properties required for exactly that reason, so the two really are equal.
+ * **`z.input`, not `z.infer`, and the difference is the whole caller-side question.** `z.infer` is
+ * the OUTPUT type - what a handler receives, after `.default(...)` has fired. These contract types
+ * are the floor a PRODUCER supplies, and for a request the producer is the caller, who has not run
+ * the validator. `z.input` is what the validator ACCEPTS, which is what a request contract states
+ * and what the document's `required` list says. Measured on zod 4.4.3: `.default()` is the only
+ * construct this emitter emits where the two differ - `.optional()`, `.nullable()` and every
+ * constraint infer identically on both sides.
+ *
+ * Once `default-on-required-property` has removed the incoherent spelling, `z.input` and the
+ * document's `required` list agree property for property, so this assertion cross-checks that rule
+ * rather than merely restating one side of it.
+ *
+ * **One measured exception, which does not reach here.** `.refine()` with a type predicate narrows
+ * the OUTPUT only - zod types it `this & ZodType<R, core.input<this>>` - so `z.input` of a
+ * `HttpPart<File>` part is `unknown` where `z.infer` is the narrowed file shape. A multipart body's
+ * contract type is an inline object literal rather than a named declaration, so it is never in the
+ * paired set below; if that ever changes, this is the pairing that breaks first.
+ *
+ * `Equals` here, not assignability: the two describe one shape, and a property present on one side
+ * and absent from the other is exactly the drift this exists to catch.
  */
 function renderWireAssertions(schemas, types, entries, contractsPackage) {
     // The assertions pair the emitted Zod against the request TYPES, which live in the contracts
@@ -1818,7 +1882,7 @@ function renderWireAssertions(schemas, types, entries, contractsPackage) {
     }
     if (paired.length === 0)
         return undefined;
-    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<Declared<z.infer<typeof ${pair.identifier}>>, Contracts.${pair.name}>>;`);
+    const assertions = paired.map((pair) => `export type Assert${pair.name} = MustHold<Identical<Declared<z.input<typeof ${pair.identifier}>>, Contracts.${pair.name}>>;`);
     return `${generatedBanner()}
 import type { z } from "zod";
 import type * as Contracts from "${contractsPackage}";
@@ -1868,6 +1932,26 @@ type Identical<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends
  * dropped from a shape that has other keys, and kept - with its value type still mapped - from one
  * that does not.
  */
+/**
+ * \u26a0\ufe0f **An optional property is \`?: T\` here and \`?: T | undefined\` in the contract type, and that is
+ * deliberate on both sides.**
+ *
+ * The validator emits \`.exactOptional()\`, so what ARRIVES is absent or a value - JSON cannot carry an
+ * \`undefined\` and the document says exactly that by leaving the property out of \`required\`. The
+ * contract type is the floor a PRODUCER supplies, and \`{ p: undefined }\` serialises identically to
+ * omitting \`p\`, so refusing it would cost every producer a conditional spread and buy the wire
+ * nothing. Narrowing THAT surface was tried in \`0.19.0\` and reverted: it broke
+ * \`(ctx, input) => ok(input)\`.
+ *
+ * So the two disagree on exactly one axis, on purpose, and this widens the inferred side to the
+ * producer floor before comparing - the same job \`Declared\` does for openness, in the same pass
+ * rather than a second deep one. Every other kind of drift still fails: a property that changes type,
+ * appears, disappears or changes optionality is untouched by this.
+ */
+type Supplied<T, K extends keyof T> = {} extends Pick<T, K>
+	? Declared<T[K]> | undefined
+	: Declared<T[K]>;
+
 type DeclaredKeyOf<T> = keyof {
 	[K in keyof T as string extends K
 		? never
@@ -1886,7 +1970,9 @@ type Declared<T> = T extends (...args: never[]) => unknown
 			: readonly Declared<Element>[]
 		: T extends object
 			? [DeclaredKeyOf<T>] extends [never]
-				? { [K in keyof T]: Declared<T[K]> }
+				? // A shape with no declared keys is a dictionary: it has no optional property to widen,
+					// and an index signature satisfies \`{} extends Pick<T, K>\` for every value type.
+					{ [K in keyof T]: Declared<T[K]> }
 				: {
 						[K in keyof T as string extends K
 							? never
@@ -1894,7 +1980,7 @@ type Declared<T> = T extends (...args: never[]) => unknown
 								? never
 								: symbol extends K
 									? never
-									: K]: Declared<T[K]>;
+									: K]: Supplied<T, K>;
 					}
 			: T;
 
@@ -2032,6 +2118,7 @@ export async function emitHttpZod(context, wrapper = {}) {
             contractsOutputDir: perService?.["contracts-output-dir"] ?? options["contracts-output-dir"],
             contractsPackage: perService?.["contracts-package"] ?? options["contracts-package"],
             sealObjectSchemas: perService?.["seal-object-schemas"] ?? options["seal-object-schemas"] ?? false,
+            compileSchemas: perService?.["compile-schemas"] ?? options["compile-schemas"] ?? false,
             keyVocabularies: perService?.["key-vocabularies"] ?? options["key-vocabularies"] ?? [],
             runtimeModule: perService?.["runtime-module"] ?? options["runtime-module"] ?? defaultRuntimeModule,
             regenerateHint: perService?.["regenerate-hint"] ?? options["regenerate-hint"],
@@ -2088,10 +2175,10 @@ export async function emitHttpZod(context, wrapper = {}) {
          * anything is written - and it has to happen HERE rather than in a server emitter, or the
          * validators it produces never reach this package's own output.
          */
-        const { names, declarations } = nameRouteSchemas(routes);
+        const { names, declarations } = nameRouteSchemas(routes, resolved.compileSchemas);
         await emitFile(context.program, {
             path: resolvePath(outputDir, "schemas.gen.ts"),
-            content: renderSchemas(registry, externals, declarations, resolved.runtimeModule),
+            content: renderSchemas(registry, externals, declarations, resolved.runtimeModule, resolved.compileSchemas),
         });
         if (resolved.contractsOutputDir !== undefined) {
             const types = new TypeRegistry(context.program);

package/dist/src/constraints.d.ts

@@ -6,12 +6,13 @@ import { type Program, type Type } from "@typespec/compiler";
  * over: the spec author writes standard TypeSpec rather than a dialect, and `@typespec/openapi3`
  * documents them without any help from us.
  *
- * **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint -
- * it is an arbitrary predicate, which a type language has no way to say and therefore no document
- * can publish, so a validator enforcing it enforces something no caller can read. `@trimmed` was the
- * other one and is gone: `.trim()` is a transform, and transforming a value before validating it
- * makes the runtime accept inputs the published contract rejects. The spec states `@pattern`
- * instead, which openapi3 publishes.
+ * **This package ships no decorators of its own, and the two it used to have are gone.** `@refine`
+ * was an arbitrary predicate, which a type language has no way to say and therefore no document can
+ * publish, so a validator enforcing it enforced something no caller could read. `@trimmed` was the
+ * other: `.trim()` is a transform, and transforming a value before validating it makes the runtime
+ * accept inputs the published contract rejects. The spec states `@pattern` instead, which openapi3
+ * publishes. `src/tsp-index.ts` exports `$lib` and no `$decorators`, and `vocabulary.test.ts`
+ * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
 export declare function applyConstraints(program: Program, expression: string, target: Type): string;
 /**

package/dist/src/constraints.js

@@ -6,12 +6,13 @@ import { getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getM
  * over: the spec author writes standard TypeSpec rather than a dialect, and `@typespec/openapi3`
  * documents them without any help from us.
  *
- * **`@refine` is the ONE that is still ours, and it is on its way out.** It is not a constraint -
- * it is an arbitrary predicate, which a type language has no way to say and therefore no document
- * can publish, so a validator enforcing it enforces something no caller can read. `@trimmed` was the
- * other one and is gone: `.trim()` is a transform, and transforming a value before validating it
- * makes the runtime accept inputs the published contract rejects. The spec states `@pattern`
- * instead, which openapi3 publishes.
+ * **This package ships no decorators of its own, and the two it used to have are gone.** `@refine`
+ * was an arbitrary predicate, which a type language has no way to say and therefore no document can
+ * publish, so a validator enforcing it enforced something no caller could read. `@trimmed` was the
+ * other: `.trim()` is a transform, and transforming a value before validating it makes the runtime
+ * accept inputs the published contract rejects. The spec states `@pattern` instead, which openapi3
+ * publishes. `src/tsp-index.ts` exports `$lib` and no `$decorators`, and `vocabulary.test.ts`
+ * asserts that no emitted file carries a `.refine(` outside the one multipart-file carve-out.
  */
 export function applyConstraints(program, expression, target) {
     let result = expression;

package/dist/src/lib.d.ts

@@ -42,6 +42,38 @@ export interface EmitterOptions {
      * stating it outright rather than an emitter option deciding.
      */
     "seal-object-schemas"?: boolean;
+    /**
+     * Whether every emitted validator is wrapped in `z.compile()`.
+     *
+     * **A pre-compiled schema parses the same values to the same results, only faster.** Zod walks the
+     * schema once and emits a flat, loop-free function through `new Function`, then falls back to the
+     * ordinary parser for anything it cannot handle - so errors, parsed output and JSON Schema
+     * serialisation are unchanged. Measured on an emitted five-property model at zod 4.5.2:
+     * `safeParse` goes from 371 ns to 51 ns.
+     *
+     * **Off by default, because it is a trade rather than a free win.** Compilation happens at module
+     * scope, so it costs startup time in proportion to the number of schemas, and buys nothing until
+     * enough requests arrive to pay that back. Measured on two emitted modules at zod 4.5.2: 25
+     * declarations in 3.3 ms and 73 in 5.7 ms, so 0.08-0.13 ms each depending on how much the schema
+     * does.
+     *
+     * **Measured at scale rather than extrapolated:** a generated 580-operation service (58 models,
+     * 1218 declarations, 638 of them compiled) evaluates its schema module in ~93 ms uncompiled and
+     * ~132 ms compiled - so about **40 ms of extra startup**, roughly a tenth of a Cloudflare Worker's
+     * 400 ms startup budget. It boots and serves on `workerd` at that size with the fast path live. It also needs
+     * `new Function`, which a CSP or no-eval environment refuses; Zod degrades to the uncompiled
+     * schema there rather than throwing, so setting this is never unsafe, merely sometimes pointless.
+     *
+     * **On Cloudflare Workers this is the only route to a compiled schema.** `new Function` is
+     * permitted during a Worker's STARTUP phase (`allow_eval_during_startup`, the default from
+     * compatibility date 2025-06-01) and module scope is startup, so wrapping here works. Zod's own
+     * `import "zod/compile"` does not: it compiles on first PARSE, which happens inside a request,
+     * where the runtime refuses. Only the emitter owns the module scope these schemas are built in.
+     *
+     * A recursive model emits `z.lazy()`, which cannot be compiled. Zod returns it uncompiled and it
+     * goes on parsing normally, so the option is safe to set on any spec.
+     */
+    "compile-schemas"?: boolean;
     /**
      * Models whose PROPERTY NAMES are also emitted as a runtime tuple.
      *
@@ -100,6 +132,7 @@ export interface EmitterOptions {
         "contracts-output-dir"?: string;
         "contracts-package"?: string;
         "seal-object-schemas"?: boolean;
+        "compile-schemas"?: boolean;
         "key-vocabularies"?: string[];
         "runtime-module"?: string;
         "regenerate-hint"?: string;
@@ -119,6 +152,9 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
+    "default-on-required-property": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
@@ -141,13 +177,16 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "undeclared-discriminator" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
+    "default-on-required-property": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };
@@ -176,6 +215,9 @@ export declare const reportDiagnostic: <C extends "duplicate-declaration" | "dup
     "unsupported-default": {
         readonly default: import("@typespec/compiler").CallableMessage<["why"]>;
     };
+    "default-on-required-property": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "undeclared-discriminator": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "property", "variant", "property", "variant"]>;
     };

package/dist/src/lib.js

@@ -12,6 +12,7 @@ export const EmitterOptionsSchema = {
         "contracts-output-dir": { type: "string", nullable: true },
         "contracts-package": { type: "string", nullable: true },
         "seal-object-schemas": { type: "boolean", nullable: true },
+        "compile-schemas": { type: "boolean", nullable: true },
         "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
         "runtime-module": { type: "string", nullable: true },
         "regenerate-hint": { type: "string", nullable: true },
@@ -26,6 +27,7 @@ export const EmitterOptionsSchema = {
                     "contracts-output-dir": { type: "string", nullable: true },
                     "contracts-package": { type: "string", nullable: true },
                     "seal-object-schemas": { type: "boolean", nullable: true },
+                    "compile-schemas": { type: "boolean", nullable: true },
                     "key-vocabularies": { type: "array", items: { type: "string" }, nullable: true },
                     "runtime-module": { type: "string", nullable: true },
                     "regenerate-hint": { type: "string", nullable: true },
@@ -76,6 +78,42 @@ const diagnostics = {
             default: paramMessage `Cannot emit a default value of ${"why"}. Scalars, arrays and objects are emitted as literals; a default built by a scalar constructor has no literal form. Replace it with a literal value, or drop the default and let the property be optional. The property keeps its declared shape and loses only the fallback.`,
         },
     },
+    /**
+     * **A default on a REQUIRED property, where the default can never apply.**
+     *
+     * **`default` is an annotation and `required` is the assertion**, and this emitter used to
+     * implement the opposite. JSON Schema 2020-12 section 9.2 makes `default` an annotation keyword
+     * with no effect on validation, and `@typespec/openapi3` implements exactly that:
+     * `#requiredModelProperties` builds the `required` list from `metadataInfo.isOptional` alone and
+     * never consults a default, then attaches the default beside it as a plain `schema.default`. The
+     * parameter side is the same rule spelled differently, `required: !param.optional`.
+     *
+     * So `basis: string = "s1159"` publishes as REQUIRED with an annotation nothing can reach. This
+     * emitter emitted `.default("s1159")`, which makes the field optional on the way IN - a validator
+     * accepting a request the document generated beside it forbids. OAI/OpenAPI-Specification#1543 is
+     * closed COMPLETED on this exact question, with the JSON Schema editor's answer that writing a
+     * default in before validating "is **NOT** part of validation", and the OpenAPI maintainer's that
+     * a default beside `required` "risks making the `required` notion invalid and encourages clients
+     * to unnecessarily send `default` values over the wire". Swagger's own documentation lists the
+     * combination as one of the two common mistakes with the keyword.
+     *
+     * **A WARNING, and this package's first, because the spec is representable.** `unsupported-default`
+     * used to be an error on composite literals and was retired for precisely this reason: refusing a
+     * construct `@typespec/openapi3` emits makes the same spec representable by one emitter and not the
+     * other, which is the one thing a differential between the two cannot tolerate. openapi3 emits this
+     * one, so this emitter serves it - saying what the document says, and saying out loud that the
+     * annotation is dead. The fix is one character and the message names it.
+     *
+     * The predicate is the DOCUMENT's, `metadataInfo.isOptional`, so this fires exactly where openapi3
+     * writes the name into `required` - including the PATCH position, where an update body's properties
+     * are optional and a default on one of them is live rather than dead.
+     */
+    "default-on-required-property": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' is required, so its default can never apply: a required property is never absent. The OpenAPI document publishes it in 'required' and carries the default only as an annotation, and this validator does the same - a request omitting '${"name"}' is refused. Declare it optional, '${"name"}?: ... = ...', if callers may omit it.`,
+        },
+    },
     /**
      * **A discriminated union whose discriminator the document never publishes.**
      *

package/dist/src/types.js

@@ -13,9 +13,12 @@ import { discriminatedSubtypes, effectiveIndexer, inheritedAndOwnProperties, obj
  *
  * **It must agree with `zod.ts` exactly**, because the emitted assertion compares them. Every rule
  * here has a counterpart there: `utcDateTime` is a string on both sides, `?` becomes
- * `?: T | undefined` because `exactOptionalPropertyTypes` is on, and a defaulted property is
- * **required** here because `z.infer` reports the *output* type and a default has always fired by
- * then.
+ * `?: T | undefined` because `exactOptionalPropertyTypes` is on, and a property the document leaves
+ * out of `required` is optional here whether its absence is spelled `?` or covered by a default.
+ *
+ * **The assertion pairs this walk against `z.input`, the type the validator ACCEPTS**, and not
+ * against `z.infer`, which is what it produces. These types are the floor a producer supplies, and
+ * for a request the producer is a caller who has not run the validator.
  */
 /** Scalars we accept, and the TypeScript they become. Mirrors `SCALARS` in `zod.ts`. */
 const SCALARS = {
@@ -247,15 +250,30 @@ export function propertyToTs(program, property, wireName) {
     const encoded = getEncode(program, property)?.type;
     const value = typeToTs(program, encoded ?? property.type);
     /**
-     * **A defaulted property is REQUIRED here.**
+     * **A defaulted property used to be REQUIRED here, and that was the OUTPUT type's answer to a
+     * question this file does not ask.**
+     *
+     * The reasoning was: `zod.ts` emits `.default(v)`, the assertion compares against `z.infer` which
+     * is the output type, and by then the default has fired. Every step of that is true and the
+     * conclusion served the wrong reader. **These types are the floor a PRODUCER supplies**, and for
+     * a request the producer is the CALLER - who has not run the validator, and for whom the document
+     * is the only contract. The document leaves an optional defaulted property out of `required`, so
+     * a caller may omit it, and this file said they could not.
+     *
+     * Reported by a consumer building requests from a zero-dependency contracts package, carrying a
+     * named helper to relax six such properties by hand. The helper could only reach the top level; a
+     * default one level down stayed required and no caller could build the value at all. Emitting the
+     * optionality per property fixes every depth at once, because there is no depth to reach.
+     *
+     * **The two directions of the emitted set differ here on purpose**, exactly as they do on
+     * openness: `schemas.gen.ts` exports `Exact<z.infer<...>>`, the narrow view of what ARRIVES, in
+     * which a default has fired and the property is present. `wire-contract.gen.ts` pairs this walk
+     * against `z.input` for the same reason.
      *
-     * `zod.ts` emits `.default(v)`, which makes the field optional on the way *in* and guaranteed on
-     * the way *out*. The assertion this type feeds compares against `z.infer`, which is the output
-     * type - so by the time a value reaches the wire the default has fired and the field is present.
-     * Marking it optional would make a correct schema fail its own assertion.
+     * A defaulted property that reaches here is one the document publishes as optional, because
+     * `propertyToZod` reports `default-on-required-property` for the other spelling and emits no
+     * `.default(...)` for it - so the two walks agree without either one restating the rule.
      */
-    if (property.defaultValue !== undefined)
-        return `${key}: ${value};`;
     /**
      * **`?: T | undefined`, and dropping the `| undefined` was tried in `0.19.0` and reverted.**
      *

package/dist/src/zod.js

@@ -978,14 +978,6 @@ export function propertyToZod(program, property) {
     const base = nullable === undefined || encoded !== undefined
         ? applyConstraints(program, typeToZod(program, declared), property)
         : `${applyConstraints(program, typeToZod(program, declared), property)}.nullable()`;
-    /**
-     * A TypeSpec default (`basis: string = "s1159"`) becomes `.default(...)`, which in Zod also makes
-     * the field optional on the way in. Dropping it turned an optional field with a fallback into a
-     * required one - callers omitting it would start getting a 400 for a request that used to work.
-     */
-    const defaulted = defaultOf(program, property);
-    if (defaulted !== undefined)
-        return `${base}.default(${defaulted})`;
     /**
      * **Optionality is a function of the position too, not only of the `?` in the spec.**
      *
@@ -995,7 +987,59 @@ export function propertyToZod(program, property) {
      * would reject every partial update the contract invites. `metadataInfo.isOptional` is the same
      * predicate `@typespec/openapi3` uses to decide the `required` list.
      */
-    return property.optional || isOptionalAt(program, property) ? `${base}.optional()` : base;
+    const optional = property.optional || isOptionalAt(program, property);
+    /**
+     * **A default only applies where the document says the property may be absent.**
+     *
+     * `.default(v)` makes a Zod field optional on the way IN, so emitting one for a property the
+     * document publishes as `required` made this validator accept a request the document beside it
+     * refuses. `default` is an ANNOTATION under JSON Schema 2020-12 and `required` is the assertion;
+     * `@typespec/openapi3` reads the two exactly that way, building `required` from
+     * `metadataInfo.isOptional` and never consulting a default. See `default-on-required-property`
+     * in `lib.ts` for the specification chain and for why this warns rather than refuses.
+     *
+     * Reported and then rendered as an ordinary required property - the declared shape is untouched
+     * and only the dead fallback is dropped, which is the same shape `unsupported-default` already
+     * takes. `defaultOf` is deliberately NOT called on this path: it would report a second diagnostic
+     * about a value that cannot be reached either way, naming the less useful of the two problems.
+     */
+    if (!optional && property.defaultValue !== undefined) {
+        reportDiagnostic(program, {
+            code: "default-on-required-property",
+            target: property,
+            format: { name: property.name },
+        });
+        return base;
+    }
+    /**
+     * A TypeSpec default (`basis?: string = "s1159"`) becomes `.default(...)`, which in Zod also makes
+     * the field optional on the way in - matching a document that leaves the property out of
+     * `required` and annotates it with the value. `.optional()` is not added beside it: `.default()`
+     * already accepts an absent value, and the two together would make the OUTPUT optional as well,
+     * so the fallback could be skipped.
+     */
+    const defaulted = defaultOf(program, property);
+    if (defaulted !== undefined)
+        return `${base}.default(${defaulted})`;
+    /**
+     * **`.exactOptional()`, because the document says the KEY may be absent and nothing more.**
+     *
+     * `.optional()` additionally accepts an explicit `undefined`, and **JSON cannot carry one** - so
+     * for a body the validator was admitting a value no conformant request can contain, and for a
+     * parameter one no transport produces. The document says exactly "absent or a value" by leaving
+     * the property out of `required`, and this is the construct that says the same.
+     *
+     * **The emitted TYPE has said this since `0.17.0`; only the validator disagreed.** `Exact<>` was
+     * written to strip `| undefined` back off `z.infer`, with a docblock arguing precisely this - so
+     * one program published a type refusing `{ note: undefined }` beside a validator accepting it, and
+     * nothing compared them. `z.infer` of `.exactOptional()` is `note?: T` natively and at every depth,
+     * which a shallow mapped type never managed, so `Exact<>` is deleted rather than kept beside it.
+     *
+     * Measured on zod 4.5.2 before the change: `z.toJSONSchema` is byte-identical for the two, so the
+     * differential's serialisation axis is untouched, and `def.type` is still `"optional"`, so the
+     * shape describers read it unchanged.
+     */
+    return optional ? `${base}.exactOptional()` : base;
 }
 /**
  * A default value as a JS literal, or `undefined` where this emitter cannot render one.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.22.0",
+  "version": "0.24.0",
   "description": "TypeSpec emitter and library: turn an HTTP service definition into Zod validators and framework-free contract types that agree, keyword for keyword, with the OpenAPI document @typespec/openapi3 publishes from the same source.",
   "keywords": [
     "codegen",
@@ -55,13 +55,14 @@
     "@typespec/streams": "0.85.0",
     "@typespec/versioning": "0.85.0",
     "@typespec/xml": "0.85.0",
+    "ajv": "^8.20.0",
     "oxfmt": "^0.63.0",
     "oxlint": "^1.78.0",
     "typescript": "~7.0.2",
     "typespec-http-zod": "link:.",
     "vitest": "^4.1.9",
     "yaml": "^2.9.0",
-    "zod": "^4.4.3"
+    "zod": "^4.5.2"
   },
   "peerDependencies": {
     "@typespec/compiler": "^1.15.0",
@@ -69,7 +70,7 @@
     "@typespec/openapi": "^1.15.0",
     "@typespec/streams": "^0.85.0",
     "@typespec/versioning": "^0.85.0",
-    "zod": "^4.0.0"
+    "zod": "^4.5.0"
   },
   "peerDependenciesMeta": {
     "@typespec/streams": {