typespec-http-zod 0.28.0 → 0.29.0

package/dist/src/api.d.ts

@@ -48,6 +48,12 @@ export { EmitterOptionsSchema, type EmitterOptions } from "./lib.js";
  * independently.
  */
 export { jsDocComment, objectKey } from "./zod.js";
+/**
+ * And the same for a VALUE written into emitted code: a string, enum value or media type as a literal
+ * whose source is ASCII. Spec text outside ASCII is the case, and a sibling emitter spelling it with a
+ * bare `JSON.stringify` writes the character itself into a file its consumer commits.
+ */
+export { literal } from "./literal.js";
 export declare function beginBanner(hint: string | undefined): void;
 /**
  * The status a row registers: the first non-error status the operation declares.
@@ -238,6 +244,19 @@ export interface EmittedRoute {
      * `unsupported`: no segment router can split it.
      */
     readonly pathSegments: readonly EmittedPathSegment[];
+    /**
+     * **The path parameters whose validator undoes an RFC 6570 expansion**, by wire name.
+     *
+     * For these, the path validator's field is `z.preprocess(<decode>, <value schema>)`: it takes the
+     * TEXT of the segment a router extracts - `primitive.a` for `{.param}` - and hands on the value,
+     * `a`. A caller already holding the value, such as a tool call or a service-binding request, must
+     * validate it against the value schema, `pathSchema.shape[name].out`: through the decoder, the value
+     * `a` is refused as not the expansion the route declares, and a value that happens to start with
+     * the route's literal is rewritten without an error. Decided by the same rule the validator is
+     * built by: a prefix or suffix in the segment, the `.` or `;` operator, or a parameter that is not
+     * a scalar. Empty when there is none, never `undefined`.
+     */
+    readonly decodedPathParameters: readonly string[];
     /**
      * A query string written into the route itself, as the pairs it spells:
      * `/items?fixed=true{&param}` carries `[["fixed", "true"]]`. It identifies the route as much as

package/dist/src/api.js

@@ -2,6 +2,7 @@ import { emitFile, getDoc, getDocData, getEncode, getLocationContext, getSummary
 import { getAuthenticationForOperation, resolveRequestVisibility, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { reportDiagnostic } from "./lib.js";
+import { literal } from "./literal.js";
 import { SchemaRegistry, TypeRegistry } from "./registry.js";
 import { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
 import { propertyTypeToTs } from "./types.js";
@@ -53,6 +54,12 @@ export { EmitterOptionsSchema } from "./lib.js";
  * independently.
  */
 export { jsDocComment, objectKey } from "./zod.js";
+/**
+ * And the same for a VALUE written into emitted code: a string, enum value or media type as a literal
+ * whose source is ASCII. Spec text outside ASCII is the case, and a sibling emitter spelling it with a
+ * bare `JSON.stringify` writes the character itself into a file its consumer commits.
+ */
+export { literal } from "./literal.js";
 /** Named once. The emitted banner and the internal-invariant messages both quote it. */
 const PACKAGE_NAME = "typespec-http-zod";
 /**
@@ -1045,8 +1052,8 @@ function mediaTypeDecoded(declared) {
         if (value === "*/*")
             return "z.string()";
         return isMediaRange(value)
-            ? `z.templateLiteral([${JSON.stringify(mediaTypeEssenceOf(value).slice(0, -1))}, z.string()])`
-            : `z.literal(${JSON.stringify(value)})`;
+            ? `z.templateLiteral([${literal(mediaTypeEssenceOf(value).slice(0, -1))}, z.string()])`
+            : `z.literal(${literal(value)})`;
     });
     const schema = admitted.length === 1 ? (admitted[0] ?? declared) : `z.union([${admitted.join(", ")}])`;
     const ranged = values.some(isMediaRange) ? schema : declared;
@@ -1063,7 +1070,7 @@ function mediaTypeDecoded(declared) {
     const decoded = restored.length === 0
         ? essence
         : `((essence) => ${restored
-            .map((value) => `essence === ${JSON.stringify(mediaTypeEssenceOf(value))} ? ${JSON.stringify(value)} : `)
+            .map((value) => `essence === ${literal(mediaTypeEssenceOf(value))} ? ${literal(value)} : `)
             .join("")}essence)(${essence})`;
     return `z.preprocess((raw) => (typeof raw === "string" ? ${decoded} : raw), ${ranged})`;
 }
@@ -1143,7 +1150,7 @@ literalQueryNames) {
             ? `z.preprocess((raw) => (typeof raw === "string" ? [raw] : raw), ${decoded})`
             : delimiter === undefined
                 ? decoded
-                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${JSON.stringify(delimiter)}) : raw), ${decoded})`;
+                : `z.preprocess((raw) => (typeof raw === "string" ? raw.split(${literal(delimiter)}) : raw), ${decoded})`;
         /**
          * **An RFC 6570 expansion is undone OUTSIDE everything above**, because it is the first thing the
          * wire did: `array.a.b` becomes `["a", "b"]`, then the element decoder and the document's schema
@@ -1153,8 +1160,8 @@ literalQueryNames) {
         const values = recordValuesOf(program, parameter.param.type);
         let expression = boxedOrSplit;
         if (parameter.type === "path") {
-            const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
-            if (segment !== undefined && needsExpansionDecoding(segment, shape)) {
+            const segment = decodedSegmentOf(parameter, segments);
+            if (segment !== undefined) {
                 expression = `z.preprocess(${uriExpansionCall({ ...segment, name: parameter.name, shape, values })}, ${decoded})`;
             }
         }
@@ -1198,9 +1205,9 @@ literalQueryNames) {
          * validates every OTHER header and leaves this one to the negotiation.
          */
         if (parameter.type === "header" && parameter.name.toLowerCase() === "accept") {
-            const literal = parameter.param.type;
-            if (literal.kind === "String")
-                accept = { name: parameter.name, value: literal.value };
+            const declared = parameter.param.type;
+            if (declared.kind === "String")
+                accept = { name: parameter.name, value: declared.value };
         }
         else if (parameter.type === "header") {
             (byTarget["header-without-accept"] ??= []).push(entry);
@@ -1231,6 +1238,19 @@ literalQueryNames) {
     };
 }
 /** What a parameter's value decodes into once its expansion is undone. */
+/**
+ * The route segment a path parameter's validator decodes, or `undefined` where it validates the
+ * segment's text as the value. The one rule for both the validator and
+ * {@link EmittedRoute.decodedPathParameters}, so a consumer reading the route cannot disagree with
+ * the validator it describes.
+ */
+function decodedSegmentOf(parameter, segments) {
+    const segment = segments.find((candidate) => candidate.kind === "expression" && candidate.parameter === parameter.name);
+    return segment !== undefined &&
+        needsExpansionDecoding(segment, expansionShapeOf(parameter.param.type))
+        ? segment
+        : undefined;
+}
 function expansionShapeOf(type) {
     if (isArrayType(type))
         return "list";
@@ -1486,6 +1506,9 @@ export function collectRoutes(program, registry, service) {
                     .filter((parameter) => parameter.type === "path" && parameter.allowReserved)
                     .map((parameter) => parameter.name),
                 pathSegments: template.segments,
+                decodedPathParameters: operation.parameters.parameters
+                    .filter((parameter) => decodedSegmentOf(parameter, template.segments) !== undefined)
+                    .map((parameter) => parameter.name),
                 literalQuery: template.literalQuery,
                 responseContentTypes: statusCode === undefined ? [] : responseContentTypesOf(operation, statusCode),
                 requestContentTypes: [...(operation.parameters.body?.contentTypes ?? [])],
@@ -1581,9 +1604,121 @@ export function collectRoutes(program, registry, service) {
  * Tokenising has neither, needs no escaping to stay correct, and is one pass rather than one pattern
  * per name. `typespec-hono` arrived at it after the same defect went live there: a spec whose every
  * identifier carried a `$` emitted a file that imported nothing and did not compile.
+ *
+ * **Only CODE is tokenised: string, template and regular-expression literals and comments are
+ * skipped.** Spec-authored text reaches emitted source inside them - a `.describe("...")`, a
+ * `.regex(/.../)` - and a word in that text is not a reference. Measured: a parameter documented as
+ * "names uriExpansion and explodedQuery" declared both RFC 6570 decoders in a service that decodes
+ * nothing, and the file failed `noUnusedLocals` - the lint a generated file has to pass like any
+ * other. A literal is told from code by its opening character; a `/` opens a regular expression only
+ * where an expression may start, which is the rule a JavaScript scanner uses, and this emitter
+ * writes no division.
  */
 function identifiersIn(source) {
-    return new Set(source.match(/[A-Za-z_$][A-Za-z0-9_$]*/g) ?? []);
+    const found = new Set();
+    scanCode(source, 0, found, false);
+    return found;
+}
+/**
+ * Collect the identifiers of the code from `start`, returning where it stopped: at the end, or -
+ * `nested`, for a template's `${...}` - just past the brace that closes it.
+ */
+function scanCode(source, start, found, nested) {
+    const identifier = /[A-Za-z_$][A-Za-z0-9_$]*/y;
+    let previous = "";
+    let depth = 0;
+    let index = start;
+    while (index < source.length) {
+        const char = source.charAt(index);
+        const next = source.charAt(index + 1);
+        if (char === "`") {
+            index = scanTemplate(source, index, found);
+            previous = char;
+        }
+        else if (char === '"' || char === "'") {
+            index = quotedEnd(source, index, char);
+            previous = char;
+        }
+        else if (char === "/" && next === "/") {
+            const end = source.indexOf("\n", index);
+            index = end === -1 ? source.length : end;
+        }
+        else if (char === "/" && next === "*") {
+            const end = source.indexOf("*/", index + 2);
+            index = end === -1 ? source.length : end + 2;
+        }
+        else if (char === "/" && (previous === "" || "(,=:[!&|?{};".includes(previous))) {
+            index = regexEnd(source, index);
+            previous = char;
+        }
+        else if (/[A-Za-z_$]/.test(char)) {
+            identifier.lastIndex = index;
+            const [name = char] = identifier.exec(source) ?? [];
+            found.add(name);
+            index += name.length;
+            previous = "a";
+        }
+        else {
+            if (char === "}" && nested && depth === 0)
+                return index + 1;
+            if (char === "{")
+                depth += 1;
+            if (char === "}")
+                depth -= 1;
+            if (!/\s/.test(char))
+                previous = char;
+            index += 1;
+        }
+    }
+    return index;
+}
+/** Past a template literal opened at `start`, collecting the code in each `${...}` on the way. */
+function scanTemplate(source, start, found) {
+    let index = start + 1;
+    while (index < source.length) {
+        const char = source.charAt(index);
+        if (char === "\\")
+            index += 2;
+        else if (char === "`")
+            return index + 1;
+        else if (char === "$" && source.charAt(index + 1) === "{") {
+            index = scanCode(source, index + 2, found, true);
+        }
+        else
+            index += 1;
+    }
+    return index;
+}
+/** Past a quoted string opened at `start`, escapes honoured. */
+function quotedEnd(source, start, quote) {
+    for (let index = start + 1; index < source.length; index += 1) {
+        const char = source.charAt(index);
+        if (char === "\\")
+            index += 1;
+        else if (char === quote)
+            return index + 1;
+    }
+    return source.length;
+}
+/** Past a regular-expression literal opened at `start`, flags included. */
+function regexEnd(source, start) {
+    let inClass = false;
+    for (let index = start + 1; index < source.length; index += 1) {
+        const char = source.charAt(index);
+        if (char === "\\")
+            index += 1;
+        else if (char === "[")
+            inClass = true;
+        else if (char === "]")
+            inClass = false;
+        else if (char === "/" && !inClass) {
+            let end = index + 1;
+            while (/[a-z]/.test(source.charAt(end)))
+                end += 1;
+            return end;
+        }
+    }
+    return source.length;
 }
 /** Whether emitted source references `name` as an identifier rather than as part of a longer one. */
 export function referencedIn(source, name) {
@@ -1595,7 +1730,7 @@ function renderExternalImports(externals, ...bodies) {
     for (const [module, names] of externals) {
         const used = [...names].filter((name) => referencedIn(haystack, name));
         if (used.length > 0) {
-            lines.push(`import { ${used.toSorted().join(", ")} } from ${JSON.stringify(module)};\n`);
+            lines.push(`import { ${used.toSorted().join(", ")} } from ${literal(module)};\n`);
         }
     }
     return lines.join("");
@@ -1944,11 +2079,11 @@ function responseArmsOf(route, arms) {
         const schema = arms[index]?.schema ?? "undefined";
         const contentTypes = response.contentTypes.length === 0
             ? ""
-            : `, contentTypes: [${response.contentTypes.map((type) => JSON.stringify(type)).join(", ")}]`;
+            : `, contentTypes: [${response.contentTypes.map((type) => literal(type)).join(", ")}]`;
         const headers = response.headers.length === 0
             ? ""
-            : `, headers: [${response.headers.map((header) => `{ name: ${JSON.stringify(header.name)}, optional: ${header.optional} }`).join(", ")}]`;
-        return `{ status: ${JSON.stringify(response.status)}, schema: ${schema}${contentTypes}${headers} }`;
+            : `, headers: [${response.headers.map((header) => `{ name: ${literal(header.name)}, optional: ${header.optional} }`).join(", ")}]`;
+        return `{ status: ${literal(response.status)}, schema: ${schema}${contentTypes}${headers} }`;
     });
     return `[${rendered.join(", ")}]`;
 }
@@ -2528,7 +2663,7 @@ ${assertions.join("\n")}
 function renderVocabularies(vocabularies) {
     const entries = [...vocabularies.entries()]
         .toSorted(([a], [b]) => a.localeCompare(b))
-        .map(([name, values]) => `\t${name}: [${values.map((v) => JSON.stringify(v)).join(", ")}],`);
+        .map(([name, values]) => `\t${name}: [${values.map((v) => literal(v)).join(", ")}],`);
     return `${generatedBanner()}
 /**
  * The spec's vocabularies - every enum the surface reaches, and what each one contains.

package/dist/src/constraints.js

@@ -1,6 +1,7 @@
 import { getEncode, getMaxItems, getMaxLength, getMaxValue, getMinItems, getMinLength, getMinValue, getMinValueExclusive, getMaxValueExclusive, getPattern, } from "@typespec/compiler";
 import { defaultMaxSteps, isSafePattern } from "redos-detector";
 import { reportDiagnostic } from "./lib.js";
+import { escapeNonAscii } from "./literal.js";
 /**
  * Constraint decorators -> the Zod modifiers that enforce them.
  *
@@ -18,15 +19,16 @@ import { reportDiagnostic } from "./lib.js";
  */
 export function applyConstraints(program, expression, target) {
     let result = expression;
-    const minLength = getMinLength(program, target);
-    const maxLength = getMaxLength(program, target);
-    const minValue = getMinValue(program, target);
-    const maxValue = getMaxValue(program, target);
-    const minItems = getMinItems(program, target);
-    const maxItems = getMaxItems(program, target);
-    const pattern = getPattern(program, target);
-    const minExclusive = getMinValueExclusive(program, target);
-    const maxExclusive = getMaxValueExclusive(program, target);
+    const read = (get) => declaredOn(program, target, get);
+    const minLength = read(getMinLength);
+    const maxLength = read(getMaxLength);
+    const minValue = read(getMinValue);
+    const maxValue = read(getMaxValue);
+    const minItems = read(getMinItems);
+    const maxItems = read(getMaxItems);
+    const pattern = read(getPattern);
+    const minExclusive = read(getMinValueExclusive);
+    const maxExclusive = read(getMaxValueExclusive);
     /**
      * **A numeric bound says nothing about a value carried as text.** `@encode(string)` is legal on a
      * numeric property and makes the wire value a string, so the expression here is `z.string()` while
@@ -72,6 +74,30 @@ export function applyConstraints(program, expression, target) {
     }
     return result;
 }
+/**
+ * **A constraint on a scalar is read up its `extends` chain: the nearest scalar declaring it wins.**
+ *
+ * The compiler's getters read the decorators of the one type they are handed, and this read the
+ * scalar a property NAMED. So `scalar ShortWord extends Word` with `@pattern` on `Word` validated
+ * as a bare `z.string()`, and every value the pattern forbids was accepted - while the document
+ * published the pattern on `ShortWord`. `@typespec/openapi3`'s `#getSchemaForScalar` builds a
+ * derived scalar from its base's schema and then applies its own decorators over it, so a keyword
+ * the derived scalar declares REPLACES the base's rather than adding to it. Reading the nearest
+ * declaration per keyword is that rule exactly: `Overrides extends Word` with its own `@pattern`
+ * publishes only its own, and enforcing both would refuse what the document accepts.
+ *
+ * A property is not a chain: its type's constraints are applied where the type is rendered.
+ */
+function declaredOn(program, target, get) {
+    if (target.kind !== "Scalar")
+        return get(program, target);
+    for (let current = target; current !== undefined; current = current.baseScalar) {
+        const value = get(program, current);
+        if (value !== undefined)
+            return value;
+    }
+    return undefined;
+}
 /**
  * Whether the value this type puts on the wire is text because `@encode` says so. Read from the
  * property and then from its scalar, which is where an encoding declared once for a named scalar
@@ -210,7 +236,7 @@ export function patternIsProvablySafe(pattern) {
  * instead of guessing at an equivalence.
  */
 export function patternToRegex(pattern) {
-    return `/${escapeSlashes(pattern)}/${unicodeSafe(pattern) ? "u" : ""}`;
+    return `/${escapeNonAscii(escapeSlashes(pattern))}/${unicodeSafe(pattern) ? "u" : ""}`;
 }
 /**
  * **Escapes the slashes a regex literal needs escaped, and only those.**
@@ -232,7 +258,15 @@ function escapeSlashes(pattern) {
     for (let index = 0; index < pattern.length; index += 1) {
         const character = pattern[index];
         if (character === "\\") {
-            escaped += character + (pattern[index + 1] ?? "");
+            const next = pattern[index + 1] ?? "";
+            /**
+             * **An identity escape of a character outside printable ASCII loses its backslash**, because
+             * the character is about to be written as `\uXXXX` and `\\uXXXX` would be a literal
+             * backslash followed by `u`. An accented letter matches the same thing escaped or not; under
+             * the `u` flag the escape is a syntax error, and `unicodeSafe` has already sent such a
+             * pattern to the bare form.
+             */
+            escaped += /[^\x20-\x7e]/.test(next) ? next : character + next;
             index += 1;
             continue;
         }

package/dist/src/lib.d.ts

@@ -162,6 +162,12 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "unenforceable-encoded-bound": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
+    "unenforceable-property-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
+    "optional-prototype-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
@@ -172,7 +178,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "inline-cycle" | "non-unicode-pattern" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "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" | "inline-cycle" | "non-unicode-pattern" | "optional-prototype-name" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-bound" | "unenforceable-property-name" | "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"]>;
     };
@@ -206,6 +212,12 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unenforceable-encoded-bound": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
+    "unenforceable-property-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
+    "optional-prototype-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };
@@ -249,6 +261,12 @@ export declare const reportDiagnostic: <C extends "default-on-required-property"
     "unenforceable-encoded-bound": {
         readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
     };
+    "unenforceable-property-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name"]>;
+    };
+    "optional-prototype-name": {
+        readonly default: import("@typespec/compiler").CallableMessage<["name", "name", "name"]>;
+    };
     "duplicate-operation-id": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId"]>;
     };

package/dist/src/lib.js

@@ -297,6 +297,48 @@ const diagnostics = {
             default: paramMessage `The bound on '${"name"}' cannot be enforced, and is not emitted. '@encode(string)' makes the wire value text, so '@minValue'/'@maxValue' would become a check on how many CHARACTERS it has - '@minValue(10)' would refuse '"42"' - and the exclusive form has no string equivalent at all. The document is no help either: it publishes 'minimum' on a 'type: string' schema, which JSON Schema ignores, so a validator enforcing the bound would refuse what the published contract accepts. Declare the bound as a '@pattern', which the document publishes and every caller can read, or remove '@encode(string)' and let the value be a number.`,
         },
     },
+    /**
+     * **A property whose wire name is `__proto__` is published, and no Zod validator can check it.**
+     *
+     * Zod skips a declared `__proto__` key on purpose, so prototype pollution cannot reach through a
+     * parse (colinhacks/zod#6386): a value of any type, or none, is accepted for it and dropped from
+     * the result. The document publishes it like any other property, and nothing emitted can enforce
+     * it - which is the case `unenforceable-encoded-bound` reports for a bound, for the same reason:
+     * the spec is representable, so refusing it would make it emit under one emitter and not the
+     * other, and serving it silently would leave a validator looser than its contract unsaid.
+     *
+     * The key is still DECLARED, as a computed `["__proto__"]`, because a plain `__proto__:` in an
+     * object literal sets the shape's prototype instead. Measured: that dropped the property from the
+     * published JSON Schema, and under `seal-object-schemas` refused every body carrying it as an
+     * unrecognised key - the opposite of what the document says.
+     */
+    "unenforceable-property-name": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' is published as a property and cannot be validated: Zod skips a key named '__proto__' on purpose (colinhacks/zod#6386), so any value, or none, is accepted for it and dropped from the parsed result. The published schema still states it. Give it another wire name if its value has to be checked.`,
+        },
+    },
+    /**
+     * **An optional property named after an `Object.prototype` member refuses every value that
+     * leaves it out.**
+     *
+     * Zod reads a property as `input[key]`, so an absent `constructor`, `toString`, `valueOf` or any
+     * other inherited member reads as the function every object inherits, and is refused as the wrong
+     * type (colinhacks/zod#6666, open). A required one is unaffected, because a value that leaves it
+     * out is refused either way. The emitted validators are right and inherit the defect - on
+     * requests and responses alike - and the only repair in emitted code, a `z.preprocess` onto a
+     * null-prototype copy, would cost the model `.shape` and `.extend`.
+     *
+     * Reported where the property is optional, which includes the PATCH position that makes a
+     * required property optional. When Zod ships the fix, the peer floor moves to it and this retires:
+     * `test/inheritednames` pins the defect so that release is noticed.
+     */
+    "optional-prototype-name": {
+        severity: "warning",
+        messages: {
+            default: paramMessage `'${"name"}' is optional here, and the validator refuses every value that leaves it out: Zod reads an absent '${"name"}' as the member every object inherits from Object.prototype, a function, and rejects it (colinhacks/zod#6666). A value that carries '${"name"}' validates normally. Give it a wire name Object.prototype does not have, or declare it required, until Zod releases a fix.`,
+        },
+    },
     "duplicate-operation-id": {
         severity: "error",
         messages: {

package/dist/src/literal.d.ts

@@ -0,0 +1,27 @@
+/**
+ * **A value as a JavaScript literal whose source is ASCII.**
+ *
+ * `JSON.stringify` is the right spelling for spec text that becomes code - a key, an enum value, a
+ * media type, a description - because it quotes and escapes exactly as a string literal needs. It
+ * leaves every other character as it is, and no file this package generates may carry one: a
+ * consumer commits the output, and an invisible character in it has held a block comment open past
+ * its terminator in the sibling package. `test/portability.test.ts` grades every emitted file.
+ *
+ * Measured once descriptions reached the output: `@typespec/http-specs`' `payload/xml` documents its
+ * models as `"\u00a71.1 \u2014 Contains fields of primitive types."`, and the section sign and the dash went
+ * straight into `schemas.gen.ts`. Every other site had the same exposure and was ASCII only because
+ * no spec in the corpus happened to put a non-ASCII character in a key or a value.
+ *
+ * So every character outside printable ASCII is written as a `\uXXXX` escape: the same string at
+ * run time, in either quote position, and in a TypeScript literal type. An astral character is two
+ * UTF-16 units, escaped one at a time, which is how JavaScript spells it.
+ */
+export declare function literal(value: unknown): string;
+/**
+ * Every UTF-16 unit outside printable ASCII as a `\uXXXX` escape. A string literal and a regular
+ * expression read the escape alike, with or without the `u` flag: under it, an escaped surrogate pair
+ * is the one code point the pair spells.
+ */
+export declare function escapeNonAscii(source: string): string;
+/** One UTF-16 unit as `\uXXXX`. */
+export declare function unicodeEscape(unit: string): string;

package/dist/src/literal.js

@@ -0,0 +1,33 @@
+/**
+ * **A value as a JavaScript literal whose source is ASCII.**
+ *
+ * `JSON.stringify` is the right spelling for spec text that becomes code - a key, an enum value, a
+ * media type, a description - because it quotes and escapes exactly as a string literal needs. It
+ * leaves every other character as it is, and no file this package generates may carry one: a
+ * consumer commits the output, and an invisible character in it has held a block comment open past
+ * its terminator in the sibling package. `test/portability.test.ts` grades every emitted file.
+ *
+ * Measured once descriptions reached the output: `@typespec/http-specs`' `payload/xml` documents its
+ * models as `"\u00a71.1 \u2014 Contains fields of primitive types."`, and the section sign and the dash went
+ * straight into `schemas.gen.ts`. Every other site had the same exposure and was ASCII only because
+ * no spec in the corpus happened to put a non-ASCII character in a key or a value.
+ *
+ * So every character outside printable ASCII is written as a `\uXXXX` escape: the same string at
+ * run time, in either quote position, and in a TypeScript literal type. An astral character is two
+ * UTF-16 units, escaped one at a time, which is how JavaScript spells it.
+ */
+export function literal(value) {
+    return escapeNonAscii(JSON.stringify(value));
+}
+/**
+ * Every UTF-16 unit outside printable ASCII as a `\uXXXX` escape. A string literal and a regular
+ * expression read the escape alike, with or without the `u` flag: under it, an escaped surrogate pair
+ * is the one code point the pair spells.
+ */
+export function escapeNonAscii(source) {
+    return source.replace(/[^\x20-\x7e]/g, unicodeEscape);
+}
+/** One UTF-16 unit as `\uXXXX`. */
+export function unicodeEscape(unit) {
+    return `\\u${unit.charCodeAt(0).toString(16).padStart(4, "0")}`;
+}

package/dist/src/registry.js

@@ -1,8 +1,8 @@
-import { getFriendlyName, } from "@typespec/compiler";
+import { getDoc, getFriendlyName, } from "@typespec/compiler";
 import { getVisibilitySuffix, Visibility } from "@typespec/http";
 import { reportDiagnostic } from "./lib.js";
 import { propertyToTs, propertyTypeToTs, typeToTsBody, withTsRefResolver } from "./types.js";
-import { captureBackEdges, currentVisibility, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
+import { captureBackEdges, currentVisibility, described, isOptionalAt, isTransformedBy, noteBackEdge, propertyToZod, UNREPRESENTABLE, typeToZodBody, withDeferredAnnotator, withRefResolver, withSyntheticDeclarations, } from "./zod.js";
 /**
  * The name an ANONYMOUS payload model inherits from the single model it spreads.
  *
@@ -394,7 +394,17 @@ export class SchemaRegistry {
          * and the emitted `const` would read itself while initialising. `z.lazy()` defers the whole body
          * instead, which is the only place left to put the deferral once no property can hold it.
          */
-        const source = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
+        /**
+         * **The description goes on the declaration's own body, so the exported const IS the
+         * described schema.** Every reference then names that one instance, which is what keeps
+         * identity, `z.compile`'s clone (it inherits the description through its parent link) and
+         * Zod's `$ref` extraction all intact. Described at a reference instead, each use would be a
+         * fresh clone. Read from the canonical type, because an anonymous payload has its doc only on
+         * the model it was spread from, and a visibility projection carries the doc of the model it
+         * projects - as openapi3 publishes one component for both.
+         */
+        const body = rendered.deferred ? `z.lazy(() => ${rendered.value})` : rendered.value;
+        const source = described(body, getDoc(this.#program, canonicalTypeFor(type)));
         const declaration = {
             identifier,
             typeName: name,
@@ -523,7 +533,20 @@ export class SchemaRegistry {
      * drift.
      */
     #structuralBodyOf(type) {
-        return withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => typeToTsBody(this.#program, type));
+        return withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => typeToTsBody(this.#program, type));
+    }
+    /**
+     * **The TypeScript name a reference resolves to is the one {@link expressionFor} declares it
+     * under**, visibility suffix included. Resolved by the bare name, a cycle through a model a
+     * request projects typed the projection's back edges by the READ shape: `NodeCreate`'s
+     * `children` became `Node[]`, which carries a property the request never sends, and the declared
+     * validator did not satisfy its own annotation (`TS2375`).
+     */
+    #typeNameOf(candidate) {
+        const bare = declaredNameOf(this.#program, candidate);
+        if (bare === undefined)
+            return undefined;
+        return nameAt(bare, visibilityFor(this.#program, candidate, currentVisibility()));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -567,7 +590,7 @@ export class SchemaRegistry {
     #deferredAnnotationOf(property) {
         if (property.defaultValue !== undefined)
             return undefined;
-        const declared = withTsRefResolver((candidate) => declaredNameOf(this.#program, candidate), () => propertyTypeToTs(this.#program, property));
+        const declared = withTsRefResolver((candidate) => this.#typeNameOf(candidate), () => propertyTypeToTs(this.#program, property));
         const core = `z.ZodType<${declared}, ${declared}>`;
         const optional = property.optional || isOptionalAt(this.#program, property);
         return `: ${optional ? `z.ZodExactOptional<${core}>` : core}`;

package/dist/src/results.js

@@ -1,4 +1,5 @@
 import { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
+import { literal } from "./literal.js";
 /**
  * **A media type's essence: `type/subtype`, lowercased, with no parameters** (RFC 9110 section
  * 8.3.1). Two media types are the same type exactly when their essences are equal, so every
@@ -41,7 +42,7 @@ export function isMediaRange(mediaType) {
  */
 export function mediaTypeTypeOf(mediaType) {
     if (!isMediaRange(mediaType))
-        return JSON.stringify(mediaType);
+        return literal(mediaType);
     if (mediaType === "*/*")
         return "string";
     return `\`${mediaType.slice(0, -1)}\${string}\``;

package/dist/src/types.js

@@ -1,5 +1,6 @@
 import { getDiscriminatedUnion, isNeverType, resolveEncodedName, } from "@typespec/compiler";
 import { reportDiagnostic } from "./lib.js";
+import { literal } from "./literal.js";
 import { discriminatedSubtypes, effectiveIndexer, emitsDefault, encodedTypeOf, inheritedAndOwnProperties, isOptionalAt, isPayloadProperty, objectKey, refusalTarget, withDeclarationSite, } from "./zod.js";
 /**
  * TypeSpec type -> plain TypeScript type text.
@@ -102,7 +103,7 @@ function scalarToTs(program, scalar) {
 }
 function enumToTs(target) {
     const values = [...target.members.values()].map((member) => member.value ?? member.name);
-    return values.map((value) => JSON.stringify(value)).join(" | ");
+    return values.map((value) => literal(value)).join(" | ");
 }
 function unionToTs(program, union) {
     /**
@@ -115,7 +116,7 @@ function unionToTs(program, union) {
     if (discriminated !== undefined && discriminated.defaultVariant === undefined) {
         const { envelope, discriminatorPropertyName, envelopePropertyName } = discriminated.options;
         const arms = [...discriminated.variants.entries()].map(([name, variant]) => {
-            const tag = `${objectKey(discriminatorPropertyName)}: ${JSON.stringify(name)};`;
+            const tag = `${objectKey(discriminatorPropertyName)}: ${literal(name)};`;
             const inner = typeToTs(program, variant);
             // No injection: with no envelope the variant declares the discriminator itself, or the union
             // is refused in `zod.ts`. Nothing is added that the document does not publish.
@@ -369,13 +370,13 @@ export function typeToTsBody(program, type) {
         case "Union":
             return unionToTs(program, type);
         case "String":
-            return JSON.stringify(type.value);
+            return literal(type.value);
         case "Number":
             return String(type.value);
         case "Boolean":
             return String(type.value);
         case "EnumMember":
-            return JSON.stringify(type.value ?? type.name);
+            return literal(type.value ?? type.name);
         // A named union variant is a referable type - `DogKind.Golden`. See the note in `zod.ts`.
         case "UnionVariant":
             return typeToTs(program, type.type);

package/dist/src/uri-template.d.ts

@@ -1,15 +1,3 @@
-/**
- * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
- *
- * **`HttpOperation.uriTemplate`, never `HttpOperation.path`.** `path` drops every operator, so
- * `array{.param*}`, `array{;param}` and `array{/param}` all become `array{param}`, and a route mounted
- * from it answers 404 to the URL its own contract declares. Measured on `@typespec/http-specs`
- * `routes`: 30 of its mock server's URIs, plus the query-continuation six.
- *
- * `parseUriTemplate` is copied from `@typespec/http` 1.16.0 (`dist/src/uri-template.js`, MIT), which
- * implements it but does not export it, so the template is split exactly as the library that built
- * it splits it.
- */
 /**
  * One `/`-delimited segment of a route, as a server has to mount it.
  *

package/dist/src/uri-template.js

@@ -1,3 +1,4 @@
+import { literal } from "./literal.js";
 /**
  * RFC 6570 URI templates, read for what a server has to mount and what it has to decode.
  *
@@ -128,7 +129,7 @@ export function needsExpansionDecoding(segment, shape) {
  * {@link URI_EXPANSION_SOURCE}, declared once in `schemas.gen.ts` when something calls it.
  */
 export function uriExpansionCall(spec) {
-    return `(raw, ctx) => uriExpansion(raw, ctx, { prefix: ${JSON.stringify(spec.prefix)}, suffix: ${JSON.stringify(spec.suffix)}, operator: ${JSON.stringify(spec.operator)}, name: ${JSON.stringify(spec.name)}, explode: ${spec.explode}, shape: ${JSON.stringify(spec.shape)}, values: ${JSON.stringify(spec.values)} })`;
+    return `(raw, ctx) => uriExpansion(raw, ctx, { prefix: ${literal(spec.prefix)}, suffix: ${literal(spec.suffix)}, operator: ${literal(spec.operator)}, name: ${literal(spec.name)}, explode: ${spec.explode}, shape: ${literal(spec.shape)}, values: ${literal(spec.values)} })`;
 }
 /**
  * **RFC 6570 section 3.2, run backwards.** A router hands over the text of the segment an expression
@@ -209,7 +210,7 @@ function uriExpansion(
  * gatherer itself is {@link EXPLODED_QUERY_SOURCE}.
  */
 export function explodedQueryCall(spec) {
-    return `(raw) => explodedQuery(raw, { name: ${JSON.stringify(spec.name)}, others: ${JSON.stringify(spec.others)}, keys: ${JSON.stringify(spec.keys ?? null)}, numbers: ${JSON.stringify(spec.numbers)}, booleans: ${JSON.stringify(spec.booleans)}, values: ${JSON.stringify(spec.values)} })`;
+    return `(raw) => explodedQuery(raw, { name: ${literal(spec.name)}, others: ${literal(spec.others)}, keys: ${literal(spec.keys ?? null)}, numbers: ${literal(spec.numbers)}, booleans: ${literal(spec.booleans)}, values: ${literal(spec.values)} })`;
 }
 /**
  * **`{?param*}` over a record or a model expands to the object's own keys**, `?a=1&b=2` and

package/dist/src/zod.d.ts

@@ -75,6 +75,40 @@ export declare function withDeclarationSite<T>(site: Type | undefined, run: () =
  * walked, which does.
  */
 export declare function refusalTarget(type: Type): Type;
+/**
+ * **A doc becomes `.describe()`, which is the one place Zod keeps a description.**
+ *
+ * `@typespec/openapi3` writes every `getDoc` as a JSON Schema `description`, and nothing carried it
+ * into the validators: a surface publishing its input schema FROM them - an MCP server's
+ * `tools/list` - gave a model calling a tool bare patterns and enums with no word on what a field is
+ * for. Measured on one consumer: a tool refused 369 calls and accepted 98, most refusals coming from
+ * the client checking that published schema before it called.
+ *
+ * `.describe()` records the text in `z.globalRegistry`, which is a `globalThis` singleton shared by
+ * every copy of Zod in a process, and both `z.toJSONSchema` and Zod's Standard Schema converter read
+ * it by default. It returns a clone and changes nothing a parse decides.
+ *
+ * **It is always the OUTERMOST call at a position, and never on a bare reference.** Inside
+ * `.nullable()` the text lands in `anyOf[0]` rather than on the property; on an identifier inside
+ * `z.array()` or a union it would clone a declaration that other code finds by identity. So it is
+ * applied where a declaration's body, a property's value or a scalar's schema is finished, and
+ * nowhere else.
+ *
+ * Gated on `undefined` rather than on truthiness, as openapi3's `applyConstraint` is: an empty
+ * `@doc("")` is published as `""`, and so is it here.
+ */
+export declare function described(expression: string, doc: string | undefined): string;
+/**
+ * The description a declared scalar publishes: its own doc, else the nearest one up its `extends`
+ * chain, and never a standard type's.
+ *
+ * Both halves are openapi3's, from `#getSchemaForScalar`: a derived scalar starts from its base's
+ * schema, description included, and overwrites what it declares itself - so `scalar B extends A`
+ * with no doc publishes A's. A standard scalar's description is deleted, because "standard types are
+ * going to be inlined in the spec and we don't want the description of the scalar to show up".
+ * Without that, `string`'s own "A sequence of textual characters." would sit on every `z.string()`.
+ */
+export declare function scalarDocOf(program: Program, scalar: Scalar): string | undefined;
 export declare function withSyntheticDeclarations<T>(hook: (name: string, build: () => string) => string, run: () => T): T;
 /**
  * Every property the model declares, **including the ones it inherits**.

package/dist/src/zod.js

@@ -1,6 +1,7 @@
-import { getDiscriminatedUnion, getDiscriminator, getEncode, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
-import { createMetadataInfo, isQueryParam, Visibility } from "@typespec/http";
+import { getDiscriminatedUnion, getDiscriminator, getDoc, getEncode, resolveEncodedName, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
+import { createMetadataInfo, getCookieParamOptions, getHeaderFieldName, getPathParamName, getQueryParamName, isCookieParam, isHeader, isPathParam, isQueryParam, Visibility, } from "@typespec/http";
 import { applyConstraints } from "./constraints.js";
+import { literal } from "./literal.js";
 import { reportDiagnostic } from "./lib.js";
 /**
  * What a walk returns after reporting a refusal.
@@ -406,10 +407,57 @@ const SCALARS = {
     url: "z.url()",
 };
 function scalarToZod(program, scalar) {
+    return described(scalarSchemaOf(program, scalar), scalarDocOf(program, scalar));
+}
+/**
+ * **A doc becomes `.describe()`, which is the one place Zod keeps a description.**
+ *
+ * `@typespec/openapi3` writes every `getDoc` as a JSON Schema `description`, and nothing carried it
+ * into the validators: a surface publishing its input schema FROM them - an MCP server's
+ * `tools/list` - gave a model calling a tool bare patterns and enums with no word on what a field is
+ * for. Measured on one consumer: a tool refused 369 calls and accepted 98, most refusals coming from
+ * the client checking that published schema before it called.
+ *
+ * `.describe()` records the text in `z.globalRegistry`, which is a `globalThis` singleton shared by
+ * every copy of Zod in a process, and both `z.toJSONSchema` and Zod's Standard Schema converter read
+ * it by default. It returns a clone and changes nothing a parse decides.
+ *
+ * **It is always the OUTERMOST call at a position, and never on a bare reference.** Inside
+ * `.nullable()` the text lands in `anyOf[0]` rather than on the property; on an identifier inside
+ * `z.array()` or a union it would clone a declaration that other code finds by identity. So it is
+ * applied where a declaration's body, a property's value or a scalar's schema is finished, and
+ * nowhere else.
+ *
+ * Gated on `undefined` rather than on truthiness, as openapi3's `applyConstraint` is: an empty
+ * `@doc("")` is published as `""`, and so is it here.
+ */
+export function described(expression, doc) {
+    return doc === undefined ? expression : `${expression}.describe(${literal(doc)})`;
+}
+/**
+ * The description a declared scalar publishes: its own doc, else the nearest one up its `extends`
+ * chain, and never a standard type's.
+ *
+ * Both halves are openapi3's, from `#getSchemaForScalar`: a derived scalar starts from its base's
+ * schema, description included, and overwrites what it declares itself - so `scalar B extends A`
+ * with no doc publishes A's. A standard scalar's description is deleted, because "standard types are
+ * going to be inlined in the spec and we don't want the description of the scalar to show up".
+ * Without that, `string`'s own "A sequence of textual characters." would sit on every `z.string()`.
+ */
+export function scalarDocOf(program, scalar) {
+    for (let current = scalar; current !== undefined && !program.checker.isStdType(current); current = current.baseScalar) {
+        const doc = getDoc(program, current);
+        if (doc !== undefined)
+            return doc;
+    }
+    return undefined;
+}
+/** A scalar's schema without its description, for a position that publishes its own. */
+function scalarSchemaOf(program, scalar) {
     // `scalar unixTimestamp32 is utcDateTime;` with `@encode(int32)` on the SCALAR, not on each use.
     const encoded = encodedTypeOf(program, scalar);
     if (encoded !== undefined && encoded !== scalar) {
-        return applyConstraints(program, scalarToZod(program, encoded), scalar);
+        return applyConstraints(program, scalarSchemaOf(program, encoded), scalar);
     }
     let current = scalar;
     // Walk the `extends` chain so a named scalar (`scalar chNumber extends string`) resolves to the
@@ -454,7 +502,7 @@ function scalarToZod(program, scalar) {
 function enumToZod(_program, target) {
     const values = [...target.members.values()].map((member) => member.value ?? member.name);
     if (values.some((value) => typeof value !== "string")) {
-        return `z.union([${values.map((value) => `z.literal(${JSON.stringify(value)})`).join(", ")}])`;
+        return `z.union([${values.map((value) => `z.literal(${literal(value)})`).join(", ")}])`;
     }
     /**
      * Every string vocabulary resolves through the generated constant rather than being restated.
@@ -475,7 +523,7 @@ function enumToZod(_program, target) {
      */
     const shared = contractsPackage();
     if (shared === undefined) {
-        return `z.enum([${values.map((value) => JSON.stringify(value)).join(", ")}])`;
+        return `z.enum([${values.map((value) => literal(value)).join(", ")}])`;
     }
     noteExternalImport(shared, "SPEC_VOCABULARIES");
     return `z.enum(SPEC_VOCABULARIES.${target.name})`;
@@ -534,7 +582,7 @@ function declaresDiscriminator(program, variant, property) {
  */
 function discriminatedVariant(program, union, variantName, variant, options) {
     const inner = typeToZod(program, variant);
-    const tag = `${objectKey(options.discriminatorPropertyName)}: z.literal(${JSON.stringify(variantName)})`;
+    const tag = `${objectKey(options.discriminatorPropertyName)}: z.literal(${literal(variantName)})`;
     // The variant already carries the discriminator, so the document publishes it and there is
     // nothing to add.
     if (options.envelope === "none")
@@ -587,7 +635,7 @@ function unionToZod(program, union) {
         }
         const members = [...discriminated.variants.entries()].map(([name, variant]) => discriminatedVariant(program, union, name, variant, options));
         const property = options.discriminatorPropertyName;
-        return `z.discriminatedUnion(${JSON.stringify(property)}, [${members.join(", ")}])`;
+        return `z.discriminatedUnion(${literal(property)}, [${members.join(", ")}])`;
     }
     const variants = [...union.variants.values()].map((variant) => variant.type);
     const nullable = variants.some((type) => type.kind === "Intrinsic" && type.name === "null");
@@ -602,7 +650,7 @@ function unionToZod(program, union) {
     }
     const suffix = nullable ? ".nullable()" : "";
     if (real.every((type) => type.kind === "String")) {
-        const literals = real.map((type) => JSON.stringify(type.value));
+        const literals = real.map((type) => literal(type.value));
         return `z.enum([${literals.join(", ")}])${suffix}`;
     }
     if (real.length === 1)
@@ -698,9 +746,10 @@ function modelToZod(program, model) {
      */
     const subtypes = discriminatedSubtypes(program, model);
     if (subtypes.length > 0) {
-        const discriminator = getDiscriminator(program, model);
+        // `discriminatedSubtypes` is empty unless the model has a discriminator.
+        const discriminator = getDiscriminator(program, model)?.propertyName ?? "";
         const options = subtypes.map((derived) => typeToZod(program, derived));
-        return `z.discriminatedUnion(${JSON.stringify(discriminator?.propertyName)}, [${options.join(", ")}])`;
+        return `z.discriminatedUnion(${literal(discriminator)}, [${options.join(", ")}])`;
     }
     const indexer = effectiveIndexer(model);
     const indexerKey = indexer?.key.name;
@@ -945,7 +994,16 @@ export function wireKindOf(program, type) {
  * Exported so there is one answer to this question. There were two sites and only one of them knew.
  */
 export function objectKey(name) {
-    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : JSON.stringify(name);
+    /**
+     * **`__proto__` is the one name a key cannot spell plainly.** In an object literal, `__proto__:`
+     * - quoted or not - sets the object's prototype rather than declaring a key, so the emitted shape
+     * had no such property: it vanished from the published JSON Schema, and under
+     * `seal-object-schemas` every body carrying it was refused as an unrecognised key. A computed
+     * key declares it, in a value and in a type alike. See `unenforceable-property-name`.
+     */
+    if (name === "__proto__")
+        return `[${literal(name)}]`;
+    return /^[A-Za-z_$][\w$]*$/.test(name) ? name : literal(name);
 }
 /**
  * A doc string as a JSDoc comment, indented, or `""` when there is none.
@@ -1063,9 +1121,56 @@ const PARAMETER_STYLE_ENCODINGS = new Set([
     "ArrayEncoding.commaDelimited",
     "ArrayEncoding.newlineDelimited",
 ]);
+/**
+ * **A date-time header with no `@encode` is an RFC 7231 HTTP-date, as if it said
+ * `@encode(DateTimeKnownEncoding.rfc7231)`.**
+ *
+ * That is TypeSpec's wire form for one, and `@typespec/openapi3` publishes it as
+ * `format: http-date` from `applyEncoding`'s `isDateTimeHeader` branch, which this emitter did not
+ * follow. The header fell through to the scalar's default, `z.iso.datetime({ offset: true })`, so a
+ * request sending it as the document describes was refused with 400, and a handler setting it as an
+ * HTTP-date failed its own response contract with 500 (issue #4). The explicit encoding already
+ * emitted `z.string()`, and this is that.
+ *
+ * **The predicate is openapi3's: the header's own schema carries `format: date-time`.** That is
+ * the standard `utcDateTime` or `offsetDateTime` itself. A declared scalar extending one is
+ * published as a `$ref`, a list carries the format on its items, and `T | null` is an `anyOf`
+ * under 3.1 and 3.2 - the versions this package grades against - so none of those is an HTTP-date
+ * in the document, and none is here. (3.0 publishes the nullable one as `nullable: true` beside an
+ * `http-date` format; the graded documents do not.)
+ */
+function isDateTimeHeader(program, property) {
+    const type = property.type;
+    return isHeader(program, property) && type.kind === "Scalar" && isStdDateTime(program, type);
+}
+function isStdDateTime(program, scalar) {
+    const { checker } = program;
+    return (scalar === checker.getStdType("utcDateTime") || scalar === checker.getStdType("offsetDateTime"));
+}
+/** Whether a property's value, or a scalar, is a date-time: one of the two, or built on one. */
+function isDateTime(program, target) {
+    const type = target.kind === "ModelProperty" ? (nullableInnerOf(target.type) ?? target.type) : target;
+    for (let current = type.kind === "Scalar" ? type : undefined; current !== undefined; current = current.baseScalar) {
+        if (isStdDateTime(program, current))
+            return true;
+    }
+    return false;
+}
 export function encodedTypeOf(program, target) {
     const encoded = getEncode(program, target);
-    if (encoded === undefined)
+    if (encoded === undefined) {
+        return target.kind === "ModelProperty" && isDateTimeHeader(program, target)
+            ? program.checker.getStdType("string")
+            : undefined;
+    }
+    /**
+     * **`rfc3339` on a date-time is the form it already has, so it changes nothing.** openapi3's
+     * `mergeFormatAndEncoding` keeps `format: date-time` for it, and the type it reports, `string`,
+     * emitted `z.string()`: the explicit spelling of the default dropped the date-time check the
+     * document still states. Only the encodings that change the wire form - `rfc7231`,
+     * `unixTimestamp` - change the type.
+     */
+    if (encoded.encoding === "rfc3339" && isDateTime(program, target))
         return undefined;
     if (target.kind === "ModelProperty" &&
         isQueryParam(program, target) &&
@@ -1091,9 +1196,26 @@ export function propertyToZod(program, property) {
     // wrapper is kept: `@encode` changes what the value IS, not whether it may be absent.
     const encoded = encodedTypeOf(program, property);
     const declared = encoded ?? nullable ?? property.type;
-    const base = nullable === undefined || encoded !== undefined
-        ? applyConstraints(program, typeToZod(program, declared), property)
-        : `${applyConstraints(program, typeToZod(program, declared), property)}.nullable()`;
+    const bare = nullable === undefined || encoded !== undefined;
+    /**
+     * **One description per position, and a property's own doc wins over its scalar's.**
+     *
+     * openapi3 publishes `subject: Subject` as `{ $ref: Subject, description: <the property's doc> }`,
+     * and a reader takes the sibling over what the reference carries. A scalar here is inlined rather
+     * than referenced, so where the property's value IS the scalar, its schema is taken without its
+     * description and the one the position publishes is decided once: the property's doc, else the
+     * scalar's. Otherwise a documented property of a documented scalar was written
+     * `.describe(a).describe(b)`, which says the same thing in a way no one would write.
+     *
+     * Under `.nullable()` the scalar keeps its own, inside the wrapper: openapi3 publishes
+     * `anyOf: [{ $ref: Subject }, { type: "null" }]` there, so the scalar's description belongs to the
+     * branch and only the property's belongs to the property.
+     */
+    const inlinedScalar = bare && declared.kind === "Scalar";
+    const value = inlinedScalar ? scalarSchemaOf(program, declared) : typeToZod(program, declared);
+    const constrained = applyConstraints(program, value, property);
+    const base = bare ? constrained : `${constrained}.nullable()`;
+    const description = getDoc(program, property) ?? (inlinedScalar ? scalarDocOf(program, declared) : undefined);
     /**
      * **Optionality is a function of the position too, not only of the `?` in the spec.**
      *
@@ -1104,6 +1226,7 @@ export function propertyToZod(program, property) {
      * predicate `@typespec/openapi3` uses to decide the `required` list.
      */
     const optional = property.optional || isOptionalAt(program, property);
+    reportInheritedName(program, property, optional);
     /**
      * **A default only applies where the document says the property may be absent.**
      *
@@ -1125,7 +1248,7 @@ export function propertyToZod(program, property) {
             target: property,
             format: { name: property.name },
         });
-        return base;
+        return described(base, description);
     }
     /**
      * A TypeSpec default (`basis?: string = "s1159"`) becomes `.default(...)`, which in Zod also makes
@@ -1136,7 +1259,7 @@ export function propertyToZod(program, property) {
      */
     const defaulted = defaultOf(program, property);
     if (defaulted !== undefined)
-        return `${base}.default(${defaulted})`;
+        return described(`${base}.default(${defaulted})`, description);
     /**
      * **`.exactOptional()`, because the document says the KEY may be absent and nothing more.**
      *
@@ -1155,7 +1278,66 @@ export function propertyToZod(program, property) {
      * differential's serialisation axis is untouched, and `def.type` is still `"optional"`, so the
      * shape describers read it unchanged.
      */
-    return optional ? `${base}.exactOptional()` : base;
+    return described(optional ? `${base}.exactOptional()` : base, description);
+}
+/**
+ * The names every JavaScript object inherits, which Zod reads in place of an absent property.
+ * `__proto__` is among them and is the different case: Zod skips it outright.
+ */
+const INHERITED_NAMES = new Set(Object.getOwnPropertyNames(Object.prototype));
+/** Properties already reported, by declaration: one property renders once per visibility. */
+const reportedNames = new WeakMap();
+/**
+ * **A wire name the validator cannot treat as an ordinary key is reported where it bites.** See
+ * `unenforceable-property-name` and `optional-prototype-name` in `lib.ts` for why each is a
+ * warning and what each costs.
+ *
+ * Reported here rather than from a walk over the program because `optional` is a fact about the
+ * POSITION: a PATCH makes a required property optional, and only there does an inherited name
+ * refuse its omission. Once per declaration, by its syntax node, because a visibility projection
+ * hands this a different `ModelProperty` for the same one.
+ */
+function reportInheritedName(program, property, optional) {
+    const name = wireNameOf(program, property);
+    if (!INHERITED_NAMES.has(name))
+        return;
+    const unenforceable = name === "__proto__";
+    if (!unenforceable && !optional)
+        return;
+    const declaration = property.node ?? property;
+    let reported = reportedNames.get(program);
+    if (reported === undefined)
+        reportedNames.set(program, (reported = new WeakSet()));
+    if (reported.has(declaration))
+        return;
+    reported.add(declaration);
+    if (unenforceable) {
+        reportDiagnostic(program, {
+            code: "unenforceable-property-name",
+            target: property,
+            format: { name },
+        });
+    }
+    else {
+        reportDiagnostic(program, {
+            code: "optional-prototype-name",
+            target: property,
+            format: { name },
+        });
+    }
+}
+/** The key a property is validated under: its parameter name, or its name in a JSON body. */
+function wireNameOf(program, property) {
+    if (isHeader(program, property))
+        return getHeaderFieldName(program, property);
+    if (isQueryParam(program, property))
+        return getQueryParamName(program, property) ?? property.name;
+    if (isPathParam(program, property))
+        return getPathParamName(program, property) ?? property.name;
+    if (isCookieParam(program, property)) {
+        return getCookieParamOptions(program, property)?.name ?? property.name;
+    }
+    return rawPropertyKey(program, property);
 }
 /**
  * A default value as a JS literal, or `undefined` where this emitter cannot render one.
@@ -1180,7 +1362,7 @@ export function propertyToZod(program, property) {
  */
 function renderValue(value) {
     if (value.valueKind === "StringValue")
-        return JSON.stringify(value.value);
+        return literal(value.value);
     if (value.valueKind === "NumericValue")
         return String(value.value.asNumber());
     if (value.valueKind === "BooleanValue")
@@ -1189,7 +1371,7 @@ function renderValue(value) {
         return "null";
     if (value.valueKind === "EnumValue") {
         const member = value.value;
-        return JSON.stringify(member.value ?? member.name);
+        return literal(member.value ?? member.name);
     }
     if (value.valueKind === "ArrayValue") {
         const rendered = value.values.map(renderValue);
@@ -1203,7 +1385,7 @@ function renderValue(value) {
             const rendered = renderValue(descriptor.value);
             if (rendered === undefined)
                 return undefined;
-            entries.push(`${JSON.stringify(name)}: ${rendered}`);
+            entries.push(`${literal(name)}: ${rendered}`);
         }
         return `{${entries.join(", ")}}`;
     }
@@ -1330,13 +1512,13 @@ export function typeToZodBody(program, type) {
         case "Union":
             return unionToZod(program, type);
         case "String":
-            return `z.literal(${JSON.stringify(type.value)})`;
+            return `z.literal(${literal(type.value)})`;
         case "Number":
             return `z.literal(${type.value})`;
         case "Boolean":
             return `z.literal(${String(type.value)})`;
         case "EnumMember":
-            return `z.literal(${JSON.stringify(type.value ?? type.name)})`;
+            return `z.literal(${literal(type.value ?? type.name)})`;
         /**
          * **A named union VARIANT is a type you can refer to, and it is not the union.**
          *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typespec-http-zod",
-  "version": "0.28.0",
+  "version": "0.29.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",