typespec-http-zod 0.22.0 → 0.23.0

package/dist/src/api.js

@@ -1282,7 +1282,32 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
         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}>` : "";
+        /**
+         * **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}>` : "";
         return `\n${declared}\nexport const ${d.identifier}${annotation} = ${d.source};\n`;
     });
     /**
@@ -1319,7 +1344,9 @@ function renderSchemas(registry, externals, routeDeclarations, runtimeModule) {
      * 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.
+     * pairs the contract against raw `z.input`, not against this. They differ on a second axis for
+     * the same reason: a defaulted property is present here, because a default has fired by the time
+     * a value arrives, and optional in the contract type, because a caller may omit it.
      *
      * 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.
@@ -1795,8 +1822,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 +1863,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}";

package/dist/src/lib.d.ts

@@ -119,6 +119,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 +144,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 +182,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

@@ -76,6 +76,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,41 @@ 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})`;
+    return optional ? `${base}.optional()` : 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.23.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",