typespec-http-zod 0.31.0 → 0.33.0

package/README.md

@@ -50,6 +50,9 @@ And the OpenAPI that [`@typespec/openapi3`](https://typespec.io) generates from
 
 - **Documentation and validation cannot drift** - both come from one definition, so there is no
   second source to keep in step
+- **Agrees with the OpenAPI version you publish** - 3.0, `@typespec/openapi3`'s default, and 3.1 read
+  some schemas differently; the validators follow the `openapi-versions` you give openapi3, and refuse
+  at compile what a 3.0 document cannot say. See [OpenAPI versions](docs/guides.md#openapi-versions)
 - **One runtime dependency** - `zod`, and nothing else
 - **No framework** - use the validators in a server, a client, or a test
 - **Types with zero imports** - a contracts module anything can depend on

package/dist/src/api.d.ts

@@ -575,6 +575,43 @@ export interface EmittedService {
     readonly routes: readonly EmittedRoute[];
     /** The identifiers every per-operation validator was declared under, keyed by operation id. */
     readonly schemaNames: ReadonlyMap<string, RouteSchemaNames>;
+    /**
+     * **The identifier each declared type's validator is exported under in `schemas.gen.ts`**, keyed
+     * by the type: a model, union or enum the document publishes as a component of its own. A scalar
+     * is validated inline wherever it is used and has no entry.
+     *
+     * **Keyed by the types this service was emitted from**, which are the ones `operations` holds: a
+     * walk from an operation's response bodies, through each base's `derivedModels`, reaches the keys
+     * themselves. For a versioned service those are the types projected to its latest version, not
+     * the types as declared, which hold every version at once.
+     *
+     * **A body is keyed by the model it is, its effective payload type.** Where visibility reshapes a
+     * model, `@typespec/http` hands its body over as a copy - `Widget` returned beside a create-only
+     * property is `{ ...Widget }` - which is not a key and has no `derivedModels`. openapi3 resolves it
+     * to `Widget` with `getEffectivePayloadType`, and so does a lookup:
+     * `createMetadataInfo(program, { canonicalVisibility: Visibility.Read })
+     * .getEffectivePayloadType(body.type, Visibility.Read)`.
+     *
+     * **The declaration under the type's own component name**, which is the one a response reads
+     * wherever a response reads the type: `Widget` -> `widgetSchema`, beside a create view
+     * `widgetCreateSchema` that is not in this map. `@friendlyName` names it and a reserved word takes
+     * the module's `_`, as the module declares it: `@friendlyName("Canine") model Hound` ->
+     * `canineSchema`, `` model `default` `` -> `default_Schema`. A multipart body's model is here,
+     * validated as the form the document publishes. A type the document publishes only under views of
+     * it, sent in create and update bodies and never returned, has none.
+     *
+     * **Every subtype of a discriminated base is here**, nested bases included and whether or not an
+     * operation names it, so a wrapping emitter can tell which subtype a value is by the subtype's
+     * own validator: the base's parsed output does not say which arm of its dispatch matched.
+     *
+     * **A declaration that validates nothing has no entry** - `duplicate-declaration`,
+     * `split-visibility` and every other refusal of a whole type - so a lookup answers `undefined`
+     * rather than a validator that refuses every value.
+     *
+     * Published so that an emitter building on this one imports a declared type's validator by name
+     * rather than agreeing with this package about how the name is spelled.
+     */
+    readonly typeSchemaNames: ReadonlyMap<Type, string>;
     /**
      * **The operation each route was collected from, keyed by operation id**, so a wrapping emitter
      * reading its doc comment, tags or diagnostic target reads the right one. Verb and path do not

package/dist/src/api.js

@@ -1,8 +1,9 @@
 import { emitFile, getDiscriminatedUnion, getDiscriminator, getDoc, getDocData, getEncode, getLocationContext, getSummary, getTypeName, isErrorModel, isNeverType, isVoidType, navigateProgram, NoTarget, resolvePath, } from "@typespec/compiler";
-import { getAuthenticationForOperation, isOrExtendsHttpFile, Visibility, } from "@typespec/http";
+import { getAuthenticationForOperation, getVisibilitySuffix, isOrExtendsHttpFile, Visibility, } from "@typespec/http";
 import { getOperationId, resolveOperationId } from "@typespec/openapi";
 import { firstReportOf } from "./constraints.js";
 import { reportDiagnostic } from "./lib.js";
+import { openApiVersionsOf, publishesOpenApi30AndLater } from "./openapi-versions.js";
 import { literal } from "./literal.js";
 import { beginServiceView, parameterVisibilityOf, publishedComponents, publishedTypes, requestVisibilityOf, unreachedTypes, withServiceView, } from "./published.js";
 import { isSingleObjectLiteral, SchemaRegistry, TypeRegistry } from "./registry.js";
@@ -13,7 +14,7 @@ import { resolveVersioningModule, serviceSnapshots } from "./versioning.js";
 import { EXPLODED_QUERY_SOURCE, explodedQueryCall, eachReader, NO_READERS, needsExpansionDecoding, routeTemplateOf, URI_EXPANSION_SOURCE, uriExpansionCall, WIRE_READ_OBJECT_SOURCE, WIRE_READ_AS_SOURCE, WIRE_READ_SOURCE, WIRE_ITSELF_SOURCE, WIRE_READERS_SOURCE, wireItselfCall, wireReadObjectCall, } from "./uri-template.js";
 export { CONTENTLESS_STATUS_CODES, STATUS_CODES } from "./statuses.js";
 export { isJsonMediaType, isMediaRange, isTextualMediaType, mediaTypeEssenceOf, mediaTypeTypeOf, resultMembersOf, statusCodesOf, } from "./results.js";
-import { collectExternalImports, encodedTypeOf, externalReferenceOf, holdsRawBytes, isExclusive, isTypelessMember, nullableInnerOf, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, objectOfModel, reachesItselfThroughUnions, refuseExternalReference, refuseSelfReachingUnion, atItem, bindingIndexerOf, currentVisibility, dispatchedSubtypesOf, readsFromText, renderedVisibilityOf, rootVisibilityOf, withContractsPackage, withSealedObjects, withMetadataAnnotationsIgnored, withMultipartBinary, withParameterPosition, UNREPRESENTABLE, withVisibility, } from "./zod.js";
+import { collectExternalImports, encodedTypeOf, externalReferenceOf, holdsRawBytes, isExclusive, isTypelessMember, nullableInnerOf, noteDeclaredVocabularies, noteKeyVocabularies, objectKey, objectOfModel, reachesItselfThroughUnions, refuseExternalReference, refuseSelfReachingUnion, atItem, bindingIndexerOf, currentVisibility, dispatchedSubtypesOf, readsFromText, renderedVisibilityOf, rootVisibilityOf, withContractsPackage, withSealedObjects, withMetadataAnnotationsIgnored, requiredReadOnlyIn, reportUnpublishable, withRequestReading, withMultipartBinary, withParameterPosition, UNREPRESENTABLE, withVisibility, } from "./zod.js";
 /**
  * `typespec-http-zod` - Zod validators and framework-free contract types from a TypeSpec HTTP
  * service, agreeing with the OpenAPI document `@typespec/openapi3` publishes from the same source.
@@ -626,6 +627,33 @@ function bodyTypeOf(type) {
  * `undeclared-discriminator` refuses a discriminator the document cannot state. `void` says "no
  * body", and openapi3 publishes it as none.
  */
+/**
+ * **A request holding a required read-only property, where openapi3 publishes 3.0 and a later
+ * version** - see `ambiguous-read-only`. The 3.0 document lets the request leave it out and the later
+ * one does not, so no request validator agrees with both.
+ */
+function reportAmbiguousReadOnly(program, type, requested) {
+    if (!publishesOpenApi30AndLater(program))
+        return;
+    const property = requiredReadOnlyIn(program, type, rootVisibilityOf(program, type, requested), new Set());
+    if (property === undefined || !firstReportOf(program, "ambiguous-read-only", type))
+        return;
+    reportDiagnostic(program, {
+        code: "ambiguous-read-only",
+        target: type,
+        format: {
+            type: getTypeName(type),
+            property: property.model === undefined
+                ? property.name
+                : `${getTypeName(property.model)}.${property.name}`,
+            later: openApiVersionsOf(program)
+                .filter((version) => !version.startsWith("3.0."))
+                .map((version) => `OpenAPI ${version}`)
+                .join(" and "),
+            view: `${getVisibilitySuffix(requested, Visibility.Read)}<${getTypeName(property.model ?? type)}>`,
+        },
+    });
+}
 function reportNeverBody(program, operation, body, position) {
     if (body?.bodyKind !== "single" || !isNeverType(body.type))
         return;
@@ -2490,6 +2518,7 @@ export function collectRoutes(program, registry, service) {
 }
 function collectServiceRoutes(program, registry, service) {
     const routes = [];
+    reportUnpublishable(program, service.namespace);
     {
         for (const operation of service.operations) {
             /**
@@ -2583,7 +2612,7 @@ function collectServiceRoutes(program, registry, service) {
                  * one and not the other, and `@visibility` can add or remove properties outright. Walking
                  * both at one visibility gives whichever was seen first to both.
                  */
-                ...withVisibility(requestVisibility, () => {
+                ...withVisibility(requestVisibility, () => withRequestReading(program, requestVisibility, () => {
                     // Multipart first: its body has no single type to walk, and skipping it left every
                     // such route mounted with nothing checking the request at all.
                     const parameterBody = requestBodyParameterOf(operation);
@@ -2595,6 +2624,7 @@ function collectServiceRoutes(program, registry, service) {
                     }
                     if (requestType === undefined)
                         return { requestSchema: undefined };
+                    reportAmbiguousReadOnly(program, requestType, requestVisibility);
                     const declared = withMetadataAnnotationsIgnored(ignoresMetadata(parameterBody), () => registry.expressionFor(requestType, true));
                     const form = formBodyOf(program, registry, operation, parameterBody, requestType, declared);
                     return form === undefined
@@ -2602,7 +2632,7 @@ function collectServiceRoutes(program, registry, service) {
                         : form.only
                             ? { requestSchema: form.schema }
                             : { requestSchema: declared, formRequestSchema: form.schema };
-                }),
+                })),
                 ...(() => {
                     const split = withVisibility(requestVisibility, () => parameterSchemasOf(program, operation, registry, template.segments, template.literalQuery.map(([name]) => name)));
                     return {
@@ -3253,7 +3283,7 @@ function collectRequestTypes(program, registry, service) {
          * The predicates `propertyToTs` consults read the visibility `withVisibility` sets, and outside
          * one they read `Read`.
          */
-        withVisibility(requestVisibilityOf(program, operation), () => {
+        withVisibility(requestVisibilityOf(program, operation), () => withRequestReading(program, requestVisibilityOf(program, operation), () => {
             const body = requestBodyOf(operation);
             const placement = requestBodyPlacementOf(program, operation);
             /** The parts of a multipart body, which `requestBodyOf` deliberately does not return. */
@@ -3351,7 +3381,7 @@ function collectRequestTypes(program, registry, service) {
                     : `Simplify<${parts.join(" & ")}>`,
                 streamsBody,
             });
-        });
+        }));
     }
     return entries;
 }
@@ -4154,6 +4184,7 @@ export async function emitHttpZod(context) {
                 service,
                 routes,
                 schemaNames: names,
+                typeSchemaNames: registry.typeIdentifiers(),
                 operations,
                 outputDir,
                 options: resolved,

package/dist/src/lib.d.ts

@@ -194,6 +194,15 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
     "never-body": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId", "position"]>;
     };
+    "unpublishable-null": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "why"]>;
+    };
+    "unpublishable-record": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "base", "base"]>;
+    };
+    "ambiguous-read-only": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "property", "later", "view"]>;
+    };
     "unsatisfiable-encoding": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "declared", "encoded", "why"]>;
     };
@@ -225,7 +234,7 @@ export declare const $lib: import("@typespec/compiler").TypeSpecLibrary<{
         readonly context: import("@typespec/compiler").CallableMessage<["name"]>;
     };
 }, EmitterOptions, never>;
-export declare const reportDiagnostic: <C extends "ambiguous-form-reading" | "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "header-case-collision" | "inline-cycle" | "invalid-default" | "invalid-subtype-discriminator" | "never-body" | "non-unicode-pattern" | "optional-prototype-name" | "sealed-base-extended" | "shared-input-key" | "split-visibility" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-constraint" | "unenforceable-property-name" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unrepresentable-override" | "unsatisfiable-encoding" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
+export declare const reportDiagnostic: <C extends "ambiguous-form-reading" | "ambiguous-read-only" | "default-on-required-property" | "duplicate-declaration" | "duplicate-operation-id" | "empty-union" | "header-case-collision" | "inline-cycle" | "invalid-default" | "invalid-subtype-discriminator" | "never-body" | "non-unicode-pattern" | "optional-prototype-name" | "sealed-base-extended" | "shared-input-key" | "split-visibility" | "truncated-doc-comment" | "undeclared-discriminator" | "unenforceable-encoded-constraint" | "unenforceable-property-name" | "unknown-key-vocabulary" | "unmirrorable-seal" | "unpublishable-null" | "unpublishable-record" | "unrepresentable-override" | "unsatisfiable-encoding" | "unsupported-default" | "unsupported-status-code-range" | "unsupported-type", M extends keyof {
     "unsupported-type": {
         readonly default: import("@typespec/compiler").CallableMessage<["artefact", "kind", "why", "remedy"]>;
     };
@@ -291,6 +300,15 @@ export declare const reportDiagnostic: <C extends "ambiguous-form-reading" | "de
     "never-body": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId", "position"]>;
     };
+    "unpublishable-null": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "why"]>;
+    };
+    "unpublishable-record": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "base", "base"]>;
+    };
+    "ambiguous-read-only": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "property", "later", "view"]>;
+    };
     "unsatisfiable-encoding": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "declared", "encoded", "why"]>;
     };
@@ -387,6 +405,15 @@ export declare const reportDiagnostic: <C extends "ambiguous-form-reading" | "de
     "never-body": {
         readonly default: import("@typespec/compiler").CallableMessage<["operationId", "position"]>;
     };
+    "unpublishable-null": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "why"]>;
+    };
+    "unpublishable-record": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "base", "base"]>;
+    };
+    "ambiguous-read-only": {
+        readonly default: import("@typespec/compiler").CallableMessage<["type", "property", "later", "view"]>;
+    };
     "unsatisfiable-encoding": {
         readonly default: import("@typespec/compiler").CallableMessage<["name", "declared", "encoded", "why"]>;
     };

package/dist/src/lib.js

@@ -475,6 +475,46 @@ const diagnostics = {
             default: paramMessage `'${"operationId"}' declares a ${"position"} body of type 'never', which has no values, and '@typespec/openapi3' publishes it as any JSON value. Replace it with 'void' to declare no body.`,
         },
     },
+    /**
+     * **A `null` the OpenAPI 3.0 document cannot publish.** OAS 3.0.4: `nullable` "only takes effect if
+     * `type` is explicitly defined within the same Schema Object", and "Other Schema Object constraints
+     * retain their defined behavior, and therefore may disallow the use of `null`". `@typespec/openapi3`
+     * publishes `Inner | null` as `{ type: object, allOf: [Inner], nullable: true }`, `Color | null` as
+     * `{ allOf: [Color], nullable: true }` and `"a" | "b" | null` as `{ type: string, enum: [a, b],
+     * nullable: true }`, and each refuses `null` by that text; a bare `null` is `{ nullable: true }`,
+     * any value. Refused where openapi3 publishes 3.0, since a validator agreeing with the spec's
+     * `| null` disagrees with the document; at 3.1 each is `anyOf` with `{ type: "null" }`.
+     */
+    "unpublishable-null": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' admits null, and the OpenAPI 3.0 document '@typespec/openapi3' publishes does not: ${"why"}. Set 'openapi-versions: ["3.1.0"]' under '@typespec/openapi3' in tspconfig.yaml's options, whether or not it is emitted, to publish OpenAPI 3.1, which says null.`,
+        },
+    },
+    /**
+     * **A sealed model whose base is a record, where openapi3 publishes 3.0.** openapi3's 3.0 sealing
+     * is `additionalProperties: { not: {} }` beside the model's own `properties`, which cannot see the
+     * record its base declares in `allOf`, so the document refuses every key the record admits; 3.1
+     * seals with `unevaluatedProperties`, which can.
+     */
+    "unpublishable-record": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' extends the record '${"base"}' and is sealed, and the OpenAPI 3.0 document '@typespec/openapi3' publishes seals it with 'additionalProperties: { not: {} }', which does not see the record in its 'allOf': every key the record admits is refused. Set 'openapi-versions: ["3.1.0"]' under '@typespec/openapi3', which seals with 'unevaluatedProperties', or spread the record onto the model, '...${"base"}', which is published open.`,
+        },
+    },
+    /**
+     * **A required read-only property in a request, where openapi3 publishes 3.0 and a later version.**
+     * OAS 3.0.4 says such a `required` "will take effect on the response only"; 3.1 made `readOnly`
+     * an annotation, so `required` holds in a request too. One request validator cannot agree with both
+     * documents.
+     */
+    "ambiguous-read-only": {
+        severity: "error",
+        messages: {
+            default: paramMessage `'${"type"}' is sent in a request and holds the required read-only property '${"property"}', and '@typespec/openapi3' publishes OpenAPI 3.0, where a request may leave it out, and ${"later"}, where it must send it: a request validator agrees with only one. Set one version in 'openapi-versions', or declare the request's own view of it, '${"view"}', which openapi3 publishes without it.`,
+        },
+    },
     /**
      * **An `@encode` whose published schema no value satisfies, or which states no type.**
      *

package/dist/src/openapi-versions.d.ts

@@ -0,0 +1,20 @@
+import type { Program } from "@typespec/compiler";
+/**
+ * **The OpenAPI versions `@typespec/openapi3` publishes from this compile**: its `openapi-versions`
+ * option, read from the compile's options as `typespec-openapi-document` reads it, and openapi3's own
+ * default, `3.0.0`, where nothing sets it - whether or not openapi3 is emitted, since a project
+ * serving no document is still described by the one openapi3 would write.
+ *
+ * **The versions are two dialects, and a validator agrees with the one published.** 0.31.0 read every
+ * schema as OpenAPI 3.1 reads it while openapi3 published 3.0 by default, and the two answer one
+ * schema differently in two places: a required read-only property is required "on the response only"
+ * at 3.0 and in both directions at 3.1, and 3.0's `nullable` takes effect only beside `type` - see
+ * {@link publishesOpenApi30Only} and `unpublishable-null`.
+ */
+export declare function openApiVersionsOf(program: Program): readonly string[];
+/** Whether every document openapi3 publishes here is OpenAPI 3.0, which reads a request as 3.0 does. */
+export declare function publishesOpenApi30Only(program: Program): boolean;
+/** Whether openapi3 publishes an OpenAPI 3.0 document here, beside any other. */
+export declare function publishesOpenApi30(program: Program): boolean;
+/** Whether openapi3 publishes OpenAPI 3.0 and a later version here, two documents a request reads apart. */
+export declare function publishesOpenApi30AndLater(program: Program): boolean;

package/dist/src/openapi-versions.js

@@ -0,0 +1,31 @@
+/**
+ * **The OpenAPI versions `@typespec/openapi3` publishes from this compile**: its `openapi-versions`
+ * option, read from the compile's options as `typespec-openapi-document` reads it, and openapi3's own
+ * default, `3.0.0`, where nothing sets it - whether or not openapi3 is emitted, since a project
+ * serving no document is still described by the one openapi3 would write.
+ *
+ * **The versions are two dialects, and a validator agrees with the one published.** 0.31.0 read every
+ * schema as OpenAPI 3.1 reads it while openapi3 published 3.0 by default, and the two answer one
+ * schema differently in two places: a required read-only property is required "on the response only"
+ * at 3.0 and in both directions at 3.1, and 3.0's `nullable` takes effect only beside `type` - see
+ * {@link publishesOpenApi30Only} and `unpublishable-null`.
+ */
+export function openApiVersionsOf(program) {
+    const options = program.compilerOptions.options?.["@typespec/openapi3"];
+    const versions = options?.["openapi-versions"];
+    return versions === undefined || versions.length === 0 ? ["3.0.0"] : versions;
+}
+const is30 = (version) => version.startsWith("3.0.");
+/** Whether every document openapi3 publishes here is OpenAPI 3.0, which reads a request as 3.0 does. */
+export function publishesOpenApi30Only(program) {
+    return openApiVersionsOf(program).every(is30);
+}
+/** Whether openapi3 publishes an OpenAPI 3.0 document here, beside any other. */
+export function publishesOpenApi30(program) {
+    return openApiVersionsOf(program).some(is30);
+}
+/** Whether openapi3 publishes OpenAPI 3.0 and a later version here, two documents a request reads apart. */
+export function publishesOpenApi30AndLater(program) {
+    const versions = openApiVersionsOf(program);
+    return versions.some(is30) && versions.some((version) => !is30(version));
+}

package/dist/src/registry.d.ts

@@ -62,6 +62,8 @@ interface Declaration {
     /** The registry key it was declared under, and its metadata context, to render it again. */
     readonly key?: string;
     readonly ignore?: boolean;
+    /** The 3.0 request it is read for, to render it again - see `withRequestReading`. */
+    readonly reading?: Visibility;
     /** A shape no type stands for, and the type it is published for - see `declareNamed`. */
     readonly synthetic?: Synthetic;
     /** The keys a merge in it asked to be refused, to render it again when one is - see `refusedAt`. */
@@ -72,7 +74,7 @@ interface Synthetic {
     readonly kind: "multipart" | "envelope";
     readonly site: Type;
 }
-export declare function nameAt(bare: string, at: Visibility, type: Type): string;
+export declare function nameAt(bare: string, at: Visibility, type: Type, reading?: Visibility): string;
 export declare class SchemaRegistry {
     #private;
     constructor(program: Program);
@@ -117,6 +119,16 @@ export declare class SchemaRegistry {
     declareNamed(name: string, build: () => string, site: Type): string;
     /** Every declaration, dependencies first. */
     declarations(): readonly Declaration[];
+    /**
+     * **The identifier each type is declared under by its own component name** - see
+     * `EmittedService.typeSchemaNames`. That is the declaration a response reads, wherever one does:
+     * `Read` is never suffixed, so a view of the type (`WidgetCreate`) and a 3.0 request's reading of
+     * it are other declarations, and neither is the one a wrapping emitter resolves a value by. A
+     * multipart body is its model's, which the document publishes under the model's name as the form it
+     * is; an envelope is named for its union and variant, and is no type's own. A declaration that
+     * validates nothing is left out rather than published as a validator.
+     */
+    typeIdentifiers(): ReadonlyMap<Type, string>;
     /** The names of the declarations that validate nothing, refused here or in the walk beneath. */
     refusedNames(): ReadonlySet<string>;
 }

package/dist/src/registry.js

@@ -4,7 +4,7 @@ import { firstReportOf } from "./constraints.js";
 import { reportDiagnostic } from "./lib.js";
 import { isSplitByVisibility, isSuffixedByUsage, viewRemedyOf, viewTemplateOf, } from "./published.js";
 import { propertyToTs, propertyTypeToTs, typeToTs, typeToTsBody, withTsRefResolver, withTsSyntheticDeclarations, } from "./types.js";
-import { captureBackEdges, currentVisibility, described, externalReferenceOf, isArrayLiteral, isOptionalAt, isSpeakableInstance, refuseExternalReference, metadataAnnotationsIgnored, metadataInfoOf, multipartBinaryContext, noteBackEdge, OWN_POSITION, propertyToZod, renderedVisibilityOf, rootVisibilityOf, UNREPRESENTABLE, typeToZodBody, visibilityName, withDeclarationSite, withDeferredAnnotator, withMetadataAnnotationsIgnored, withMultipartBinary, withRefResolver, withHeldDeclarations, withSyntheticDeclarations, withParameterPosition, withVisibility, } from "./zod.js";
+import { captureBackEdges, currentVisibility, described, externalReferenceOf, isArrayLiteral, isOptionalAt, isSpeakableInstance, refuseExternalReference, metadataAnnotationsIgnored, metadataInfoOf, multipartBinaryContext, noteBackEdge, OWN_POSITION, propertyToZod, renderedVisibilityOf, requestReadingAt, requestReadsApart, rootVisibilityOf, UNREPRESENTABLE, typeToZodBody, visibilityName, withDeclarationSite, withDeferredAnnotator, withMetadataAnnotationsIgnored, withMultipartBinary, withRefResolver, withRequestReadingAs, withHeldDeclarations, withSyntheticDeclarations, withParameterPosition, withVisibility, } from "./zod.js";
 /**
  * The words TypeScript refuses as the name of a declaration the emitted files write - a type alias,
  * an interface, and the references to each - in a module, which is strict mode.
@@ -429,12 +429,33 @@ function visibilityAt(program, type, requested, depth) {
         ? rootVisibilityOf(program, type, requested)
         : renderedVisibilityOf(program, type, requested);
 }
-export function nameAt(bare, at, type) {
+export function nameAt(bare, at, type, reading) {
+    /**
+     * **A 3.0 request's reading of a shared schema is named for the request**, `WidgetCreate` beside
+     * the `Widget` a response reads: the document publishes one component and OAS 3.0 reads it two
+     * ways - see `withRequestReading` - so the module declares both, the request's under the name
+     * openapi3 gives a view of the type at that visibility.
+     */
+    if (reading !== undefined) {
+        return safeDeclarationName(`${bare}${getVisibilitySuffix(reading, Visibility.Read)}`);
+    }
     // Suffixed only where openapi3 suffixes it: used at more than one visibility - see `isSuffixedByUsage`.
     const suffixed = at !== Visibility.Read && isSuffixedByUsage(type);
     return safeDeclarationName(`${bare}${suffixed ? getVisibilitySuffix(at, Visibility.Read) : ""}`);
 }
-function keyFor(type, visibility) {
+/**
+ * **The 3.0 request a shared schema is read apart for here**, or `undefined`: only a type rendered at
+ * `Read` is shared with a response, and only one reaching a required read-only property reads apart -
+ * see `requestReadsApart`. A view openapi3 publishes for a request's own visibility drops read-only
+ * properties already, and the shared types it holds are read apart as they are reached.
+ */
+function readingOf(program, type, at) {
+    const reading = requestReadingAt();
+    return reading !== undefined && at === Visibility.Read && requestReadsApart(program, type, at)
+        ? reading
+        : undefined;
+}
+function keyFor(type, visibility, reading) {
     /**
      * **Keyed on the named model, never a copy of it**: `@typespec/http` synthesises a fresh anonymous
      * model per position, and two operations taking one body each hand over a copy. Both resolve to
@@ -445,7 +466,9 @@ function keyFor(type, visibility) {
     const body = metadataAnnotationsIgnored() ? "\u0000body" : "";
     // And inside a multipart part's union holding raw `bytes` - see `withMultipartBinary`.
     const binary = multipartBinaryContext() ? "\u0000multipart" : "";
-    return `${String(visibility)}\u0000${String(type.name ?? "")}\u0000${identityOf(type)}${body}${binary}`;
+    // And a 3.0 request's reading of a shared schema - see `readingOf`.
+    const request = reading === undefined ? "" : `\u0000request${String(reading)}`;
+    return `${String(visibility)}\u0000${String(type.name ?? "")}\u0000${identityOf(type)}${body}${binary}${request}`;
 }
 /** A stable per-type identity, since two models can share a name across namespaces. */
 const identities = new WeakMap();
@@ -472,6 +495,8 @@ export class SchemaRegistry {
     #withheld = new Set();
     /** Every type name a refused identifier stood for: `Foo` and `foo` are both `fooSchema`. */
     #refusedTypeNames = new Set();
+    /** Each type declared by another type's declaration, the two rendered alike under one name. */
+    #alike = [];
     /**
      * Inlined types currently being walked, by identity, against the number of declarations that were
      * in flight when each was entered.
@@ -541,7 +566,8 @@ export class SchemaRegistry {
          * request and a response. Collapsing onto `Read` first is what makes the key and the name agree,
          * and it is the same collapse openapi3 performs before naming a component.
          */
-        const key = keyFor(type, at);
+        const reading = readingOf(this.#program, type, at);
+        const key = keyFor(type, at, reading);
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
             return existing.identifier;
@@ -566,7 +592,7 @@ export class SchemaRegistry {
                 this.#cyclic.add(inFlight);
             return pending;
         }
-        const name = nameAt(bare, at, type);
+        const name = nameAt(bare, at, type, reading);
         const identifier = `${lowerFirst(name)}Schema`;
         const { source, deferred, consulted } = this.#render(type, at, name, key, identifier);
         const declaration = {
@@ -577,6 +603,7 @@ export class SchemaRegistry {
             at,
             key,
             ignore: metadataAnnotationsIgnored(),
+            ...(reading === undefined ? {} : { reading }),
             ...(this.#cyclic.has(key) ? { structural: this.#structuralBodyOf(type, at) } : {}),
             ...(deferred ? { annotated: true } : {}),
             ...(consulted.size === 0 ? {} : { consulted }),
@@ -607,6 +634,9 @@ export class SchemaRegistry {
          */
         if (twin !== undefined && twin.source === declaration.source) {
             this.#declarations.set(key, twin);
+            // Another type of the name, rendered alike, is validated by it too - see `typeIdentifiers`.
+            if (twin.type !== type)
+                this.#alike.push({ type, identifier });
             return twin.identifier;
         }
         if (twin !== undefined) {
@@ -713,14 +743,14 @@ export class SchemaRegistry {
         refused: (expression) => this.#refused.has(expression),
         annotated: (expression) => this.#order.some((declaration) => declaration.identifier === expression && declaration.annotated === true),
         refusedAt: (type, at) => {
-            const key = keyFor(type, at);
+            const key = keyFor(type, at, readingOf(this.#program, type, at));
             this.#consulted.at(-1)?.add(key);
             const declared = this.#declarations.get(key);
             return (declared !== undefined &&
                 (this.#refused.has(declared.identifier) || this.#withheld.has(declared.identifier)));
         },
         holdsRefusalAt: (type, at) => {
-            const key = keyFor(type, at);
+            const key = keyFor(type, at, readingOf(this.#program, type, at));
             this.#consulted.at(-1)?.add(key);
             const declared = this.#declarations.get(key);
             return declared !== undefined && this.#reachesRefusal(declared.identifier, new Set());
@@ -771,7 +801,7 @@ export class SchemaRegistry {
                 .map(([each]) => each);
             for (const each of keys)
                 this.#declarations.delete(each);
-            const { source, deferred, consulted } = withMetadataAnnotationsIgnored(held.ignore ?? false, () => this.#render(type, at, held.typeName, key, held.identifier));
+            const { source, deferred, consulted } = withRequestReadingAs(held.reading, () => withMetadataAnnotationsIgnored(held.ignore ?? false, () => this.#render(type, at, held.typeName, key, held.identifier)));
             const fresh = {
                 ...held,
                 source,
@@ -953,7 +983,8 @@ export class SchemaRegistry {
         const bare = declaredNameOf(this.#program, candidate);
         if (bare === undefined)
             return undefined;
-        return nameAt(bare, renderedVisibilityOf(this.#program, candidate, currentVisibility()), candidate);
+        const at = renderedVisibilityOf(this.#program, candidate, currentVisibility());
+        return nameAt(bare, at, candidate, readingOf(this.#program, candidate, at));
     }
     /**
      * Render `type` without consulting its own declaration, but letting nested types use theirs.
@@ -1031,6 +1062,50 @@ export class SchemaRegistry {
     declarations() {
         return this.#order;
     }
+    /**
+     * **The identifier each type is declared under by its own component name** - see
+     * `EmittedService.typeSchemaNames`. That is the declaration a response reads, wherever one does:
+     * `Read` is never suffixed, so a view of the type (`WidgetCreate`) and a 3.0 request's reading of
+     * it are other declarations, and neither is the one a wrapping emitter resolves a value by. A
+     * multipart body is its model's, which the document publishes under the model's name as the form it
+     * is; an envelope is named for its union and variant, and is no type's own. A declaration that
+     * validates nothing is left out rather than published as a validator.
+     */
+    typeIdentifiers() {
+        const found = new Map();
+        const consider = (type, declaration) => {
+            if (this.#validatesNothing(declaration))
+                return;
+            // A view, and a 3.0 request's reading, are named with a suffix - see `nameAt`.
+            const bare = declaredNameOf(this.#program, type);
+            if (bare === undefined || declaration.typeName !== safeDeclarationName(bare))
+                return;
+            found.set(type, declaration.identifier);
+        };
+        for (const declaration of this.#order) {
+            const { type, synthetic } = declaration;
+            if (type !== undefined)
+                consider(type, declaration);
+            else if (synthetic?.kind === "multipart")
+                consider(synthetic.site, declaration);
+        }
+        // By identifier, because the declaration a type shares can be rendered again since.
+        for (const { type, identifier } of this.#alike) {
+            const declaration = this.#order.find((each) => each.identifier === identifier);
+            if (declaration !== undefined)
+                consider(type, declaration);
+        }
+        return found;
+    }
+    /**
+     * **Rendered as `z.never()`, and described where it has a doc comment**, so its source is not always
+     * `UNREPRESENTABLE` itself: a model split by visibility keeps its description. A declaration refused
+     * as two shapes under one name is replaced by a bare `UNREPRESENTABLE`, so it is one of these too.
+     */
+    #validatesNothing(declaration) {
+        return (declaration.source === UNREPRESENTABLE ||
+            declaration.source.startsWith(`${UNREPRESENTABLE}.describe(`));
+    }
     /** The names of the declarations that validate nothing, refused here or in the walk beneath. */
     refusedNames() {
         return new Set([
@@ -1154,8 +1229,9 @@ export class TypeRegistry {
                 this.#inlineInProgress.delete(type);
             }
         }
-        const key = keyFor(type, at);
-        const name = nameAt(bare, at, type);
+        const reading = readingOf(this.#program, type, at);
+        const key = keyFor(type, at, reading);
+        const name = nameAt(bare, at, type, reading);
         const existing = this.#declarations.get(key);
         if (existing !== undefined)
             return existing.name;

package/dist/src/zod.d.ts

@@ -1,4 +1,4 @@
-import { type Enum, type Model, type ModelProperty, type Program, type Scalar, type Type, type Union } from "@typespec/compiler";
+import { type Enum, type Model, type ModelProperty, type Namespace, type Program, type Scalar, type Type, type Union } from "@typespec/compiler";
 import { type MetadataInfo, Visibility } from "@typespec/http";
 /**
  * What a walk returns after reporting a refusal.
@@ -27,6 +27,21 @@ export declare function metadataInfoOf(program: Program): MetadataInfo;
 export declare function withVisibility<T>(next: Visibility, run: () => T): T;
 /** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
 export declare function isOptionalAt(program: Program, property: ModelProperty): boolean;
+export declare function withRequestReading<T>(program: Program, requested: Visibility, run: () => T): T;
+/** A declaration's recorded reading, restored to render it again - see `Declaration.reading`. */
+export declare function withRequestReadingAs<T>(reading: Visibility | undefined, run: () => T): T;
+/** The request visibility a 3.0 request reading is under, or `undefined` outside one. */
+export declare function requestReadingAt(): Visibility | undefined;
+/**
+ * **Whether a type, rendered at `at`, is read apart in a 3.0 request**: it reaches a required
+ * read-only property openapi3 publishes in it - through its own and inherited properties, a list's
+ * elements, a record's values, a union's members and a discriminated base's subtypes, each at the
+ * visibility openapi3 renders it at. Such a type's request reading lets that property be left out
+ * and its response reading does not, so the two are two declarations; a type reaching none is one.
+ */
+export declare function requestReadsApart(program: Program, type: Type, at: Visibility): boolean;
+/** The first required read-only property `type` reaches at `at` - see {@link requestReadsApart}. */
+export declare function requiredReadOnlyIn(program: Program, type: Type, at: Visibility, seen: Set<Type>): ModelProperty | undefined;
 /** Whether a property belongs in the BODY at the current position, rather than being metadata. */
 export declare function isPayloadProperty(program: Program, property: ModelProperty): boolean;
 export declare function withMetadataAnnotationsIgnored<T>(ignored: boolean, run: () => T): T;
@@ -285,6 +300,31 @@ export declare function optionalDiscriminator(program: Program, union: Union, va
  * at more than one. None for a union with no name, whose envelopes are written out where it is.
  */
 export declare function envelopeNameOf(program: Program, union: Union, variantName: string, variant: Type): string | undefined;
+/**
+ * **Why the OpenAPI 3.0 document refuses a `null` the spec admits**, or `undefined` where it does not -
+ * asked only where openapi3 publishes 3.0. Read off openapi3's 3.0 `unionSchema` and OAS 3.0.4's
+ * `nullable`, which "only takes effect if `type` is explicitly defined within the same Schema Object",
+ * while "Other Schema Object constraints retain their defined behavior":
+ *
+ * - Each JSON kind of literal is one `{ type, enum }` member, and the `enum` refuses `null`.
+ * - **One member**, or any member a `$ref`, is written with `nullable` beside it: a `$ref` is wrapped
+ *   as `{ type?, allOf: [$ref], nullable }` and the component refuses `null` unless it has no type; an
+ *   inline schema admits it where it carries a `type` - a standard scalar, a list, a record, a model
+ *   expression - or none at all.
+ * - **Several inline members** are `{ anyOf: [...], nullable: true }`, with no `type`, so `nullable`
+ *   does nothing and only a member admitting `null` on its own does.
+ * - A bare `null` is `{ nullable: true }` - any value - and a union of nothing but `null` is refused by
+ *   openapi3 itself, as `union-null`.
+ */
+export declare function unpublishableNullWhy(program: Program, type: Type): string | undefined;
+/**
+ * **Everything a service declares that its 3.0 document cannot publish, reported once each**,
+ * whichever walk renders it or none: a `null` in a union, named or written where it is used, a bare
+ * `null`, and a sealed model's record - see `unpublishable-null` and `unpublishable-record`.
+ * The walks refuse each as they reach it; this is what makes sure every one is named, the way a
+ * property's `T | null` is peeled off before any union is rendered.
+ */
+export declare function reportUnpublishable(program: Program, service: Namespace): void;
 /**
  * Every property the model declares, **including the ones it inherits**.
  *
@@ -697,6 +737,15 @@ export interface HeldDeclarations {
     readonly holdsRefusalAt: (type: Type, at: Visibility) => boolean;
 }
 export declare function withHeldDeclarations<T>(given: HeldDeclarations, run: () => T): T;
+/**
+ * **The record a sealed model's 3.0 document cannot see**, or `undefined`. openapi3's 3.0 sealing is
+ * `additionalProperties: { not: {} }` beside the model's own `properties` - it re-declares a base's
+ * properties there, so they survive - and a base that is a record declares none: `model M extends
+ * Record<string> { name: string }` sealed refuses every key the record admits, where 3.1's
+ * `unevaluatedProperties` sees the record through `allOf`. Mirrors {@link isSealed}: sealed here,
+ * with an ancestor whose indexer admits a value.
+ */
+export declare function unpublishableRecordOf(program: Program, model: Model): Model | undefined;
 /**
  * A model as the object it publishes at the current position: the merge of one - see
  * {@link mergeShapes}. **HTTP metadata is not payload**, and neither is a property invisible here or

package/dist/src/zod.js

@@ -1,4 +1,4 @@
-import { getDiscriminatedUnion, getDiscriminatedUnionFromInheritance, getDiscriminator, getDoc, getEncode, getTypeName, ignoreDiagnostics, resolveEncodedName, serializeValueAsJson, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
+import { getDiscriminatedUnion, getDiscriminatedUnionFromInheritance, getDiscriminator, getDoc, getEncode, getTypeName, ignoreDiagnostics, isGlobalNamespace, navigateTypesInNamespace, resolveEncodedName, serializeValueAsJson, isNeverType, isTemplateDeclaration, } from "@typespec/compiler";
 import { createMetadataInfo, getCookieParamOptions, getHeaderFieldName, getVisibilitySuffix, getPathParamName, getQueryParamName, isCookieParam, isHeader, isPathParam, isQueryParam, Visibility, } from "@typespec/http";
 import { $ } from "@typespec/compiler/typekit";
 import { z } from "zod";
@@ -7,6 +7,7 @@ import { applyConstraints, firstReportOf, brokenConstraintOf, brokenItemsOf, has
 import { literal } from "./literal.js";
 import { isPublishedSplit, isSharedRouteOptional, isSuffixedByUsage, keptVisibilityOf, readVisibilityOf, } from "./published.js";
 import { reportDiagnostic } from "./lib.js";
+import { publishesOpenApi30, publishesOpenApi30Only } from "./openapi-versions.js";
 /**
  * What a walk returns after reporting a refusal.
  *
@@ -109,7 +110,7 @@ function isSealed(model) {
 /**
  * Whether `@typespec/openapi3` is sealing object schemas for this compile.
  *
- * **This emitter cannot see the other emitter's options, so the consumer states it twice.**
+ * **The consumer states it twice, here and in openapi3's own options.**
  * Awkward, and the alternative is worse: assume sealing is on and a project running openapi3 with
  * its default gets validators that reject properties its published document permits. Whichever way
  * the two are configured, the conformance differential compares openness in both directions and
@@ -187,7 +188,109 @@ export function withVisibility(next, run) {
 }
 /** Whether a property is optional AT THE CURRENT POSITION - PATCH makes update fields optional. */
 export function isOptionalAt(program, property) {
-    return (metadataInfoOf(program).isOptional(property, visibility) || isSharedRouteOptional(property));
+    return (metadataInfoOf(program).isOptional(property, visibility) ||
+        isSharedRouteOptional(property) ||
+        (requestReading !== undefined && isReadonlyProperty(program, property)));
+}
+/**
+ * **A request read as an OpenAPI 3.0 document reads it: the request's visibility, while the walk is
+ * inside one, where openapi3 publishes only 3.0.**
+ *
+ * openapi3 shares a read-only property into the schema a request is published with - a create body
+ * with nothing create-specific IS the canonical schema, `id` required and `readOnly` - and OAS 3.0.4
+ * says such a `required` "will take effect on the response only". So at 3.0 a request may leave it
+ * out, and the validator lets it, as 0.30.0 did; 0.31.0 read every request as 3.1 does, where
+ * `readOnly` is an annotation and `required` holds both ways, and refused every create body leaving
+ * out a server-assigned id while openapi3 published 3.0 by default.
+ *
+ * A declaration a request reads apart from its response is declared again for the request - keyed and
+ * named for it, `WidgetCreate` beside `Widget` - see {@link requestReadsApart}.
+ */
+let requestReading;
+export function withRequestReading(program, requested, run) {
+    const previous = requestReading;
+    requestReading = publishesOpenApi30Only(program) ? requested : undefined;
+    try {
+        return run();
+    }
+    finally {
+        requestReading = previous;
+    }
+}
+/** A declaration's recorded reading, restored to render it again - see `Declaration.reading`. */
+export function withRequestReadingAs(reading, run) {
+    const previous = requestReading;
+    requestReading = reading;
+    try {
+        return run();
+    }
+    finally {
+        requestReading = previous;
+    }
+}
+/** The request visibility a 3.0 request reading is under, or `undefined` outside one. */
+export function requestReadingAt() {
+    return requestReading;
+}
+/**
+ * **Whether a type, rendered at `at`, is read apart in a 3.0 request**: it reaches a required
+ * read-only property openapi3 publishes in it - through its own and inherited properties, a list's
+ * elements, a record's values, a union's members and a discriminated base's subtypes, each at the
+ * visibility openapi3 renders it at. Such a type's request reading lets that property be left out
+ * and its response reading does not, so the two are two declarations; a type reaching none is one.
+ */
+export function requestReadsApart(program, type, at) {
+    return requiredReadOnlyIn(program, type, at, new Set()) !== undefined;
+}
+/** The first required read-only property `type` reaches at `at` - see {@link requestReadsApart}. */
+export function requiredReadOnlyIn(program, type, at, seen) {
+    if (seen.has(type))
+        return undefined;
+    seen.add(type);
+    const inner = (next) => requiredReadOnlyIn(program, next, renderedVisibilityOf(program, next, at), seen);
+    switch (type.kind) {
+        case "Model": {
+            if (type.indexer !== undefined) {
+                const found = inner(type.indexer.value);
+                if (found !== undefined)
+                    return found;
+            }
+            const info = metadataInfoOf(program);
+            for (const { property } of flattenedPropertiesOf(program, type)) {
+                if (!info.isPayloadProperty(property, at, metadataIgnored))
+                    continue;
+                if (isReadonlyProperty(program, property) && !property.optional)
+                    return property;
+                const found = inner(property.type);
+                if (found !== undefined)
+                    return found;
+            }
+            for (const derived of type.derivedModels) {
+                const found = requiredReadOnlyIn(program, derived, at, seen);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        }
+        case "Union":
+            for (const variant of type.variants.values()) {
+                const found = inner(variant.type);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        case "UnionVariant":
+            return inner(type.type);
+        case "Tuple":
+            for (const value of type.values) {
+                const found = inner(value);
+                if (found !== undefined)
+                    return found;
+            }
+            return undefined;
+        default:
+            return undefined;
+    }
 }
 /** Whether a property belongs in the BODY at the current position, rather than being metadata. */
 export function isPayloadProperty(program, property) {
@@ -1017,7 +1120,150 @@ export function envelopeNameOf(program, union, variantName, variant) {
     const suffixed = envelopeAt !== Visibility.Read && isSuffixedByUsage(union);
     return `${union.name}${capitalise(variantName)}${suffixed ? getVisibilitySuffix(envelopeAt, Visibility.Read) : ""}`;
 }
+/**
+ * **Why the OpenAPI 3.0 document refuses a `null` the spec admits**, or `undefined` where it does not -
+ * asked only where openapi3 publishes 3.0. Read off openapi3's 3.0 `unionSchema` and OAS 3.0.4's
+ * `nullable`, which "only takes effect if `type` is explicitly defined within the same Schema Object",
+ * while "Other Schema Object constraints retain their defined behavior":
+ *
+ * - Each JSON kind of literal is one `{ type, enum }` member, and the `enum` refuses `null`.
+ * - **One member**, or any member a `$ref`, is written with `nullable` beside it: a `$ref` is wrapped
+ *   as `{ type?, allOf: [$ref], nullable }` and the component refuses `null` unless it has no type; an
+ *   inline schema admits it where it carries a `type` - a standard scalar, a list, a record, a model
+ *   expression - or none at all.
+ * - **Several inline members** are `{ anyOf: [...], nullable: true }`, with no `type`, so `nullable`
+ *   does nothing and only a member admitting `null` on its own does.
+ * - A bare `null` is `{ nullable: true }` - any value - and a union of nothing but `null` is refused by
+ *   openapi3 itself, as `union-null`.
+ */
+export function unpublishableNullWhy(program, type) {
+    if (!publishesOpenApi30(program))
+        return undefined;
+    if (type.kind === "Intrinsic" && type.name === "null") {
+        return "a bare 'null' is published as '{ nullable: true }', which is any value";
+    }
+    if (type.kind !== "Union" || getDiscriminatedUnion(program, type)[0] !== undefined)
+        return undefined;
+    const variants = [...type.variants.values()].map((variant) => variant.type);
+    if (!variants.some(isNull))
+        return undefined;
+    const real = variants.filter((variant) => !isNull(variant));
+    if (real.length === 0) {
+        return "a union of nothing but 'null' has no 3.0 schema, and openapi3 refuses it as 'union-null'";
+    }
+    if (admitsNullAt30(program, type, new Set()))
+        return undefined;
+    const referenced = real.some((member) => publishedAsReference(program, member));
+    return referenced
+        ? "'nullable' is published beside a reference, which still refuses null - OAS 3.0.4 lets 'nullable' take effect only beside 'type', and keeps every other constraint"
+        : "'nullable' is published beside an 'enum' or an 'anyOf' that refuses null - OAS 3.0.4 lets 'nullable' take effect only beside 'type', and keeps every other constraint";
+}
+/** Whether openapi3's 3.0 schema for `union` admits `null` - see {@link unpublishableNullWhy}. */
+function admitsNullAt30(program, union, seen) {
+    if (seen.has(union))
+        return false;
+    seen.add(union);
+    const variants = [...union.variants.values()].map((variant) => variant.type);
+    const nullable = variants.some(isNull);
+    const real = variants.filter((variant) => !isNull(variant));
+    const literal = (member) => member.kind === "EnumMember" ||
+        (member.kind !== "UnionVariant" && literalValueOf(member) !== undefined);
+    const members = real.filter((member) => !literal(member));
+    const groups = new Set(real.filter(literal).map((member) => member.kind)).size;
+    const wrapped = nullable &&
+        (members.length + groups === 1 ||
+            members.some((member) => publishedAsReference(program, member)));
+    return members.some((member) => memberAdmitsNullAt30(program, member, wrapped, seen));
+}
+/** Whether one member of a 3.0 union admits `null`, with `nullable` beside it or not. */
+function memberAdmitsNullAt30(program, member, wrapped, seen) {
+    if (member.kind === "UnionVariant")
+        return memberAdmitsNullAt30(program, member.type, wrapped, seen);
+    if (isTypelessMember(program, member))
+        return true;
+    if (publishedAsReference(program, member)) {
+        // The component answers: a named union by its own members, anything else typed and refusing.
+        return member.kind === "Union" && admitsNullAt30(program, member, seen);
+    }
+    if (member.kind === "Union")
+        return admitsNullAt30(program, member, seen);
+    // Inline and typed - a standard scalar, a list, a record, a model expression: `nullable` beside it.
+    return wrapped;
+}
+/**
+ * **Whether openapi3 publishes `type` as a `$ref` to a component**: a named model, enum or named union
+ * it can name, and a scalar outside the standard library. Everything else it writes out where it is
+ * used. Mirrors `declaredNameOf`, plus scalars, which this emitter validates inline and openapi3
+ * declares.
+ */
+function publishedAsReference(program, type) {
+    switch (type.kind) {
+        case "UnionVariant":
+            return publishedAsReference(program, type.type);
+        case "Enum":
+            return true;
+        case "Union":
+            return type.name !== undefined && isSpeakableInstance(type) && !shouldInline(program, type);
+        case "Scalar":
+            return !program.checker.isStdType(type);
+        case "Model":
+            return (type.name !== "" &&
+                !isArrayLiteral(program, type) &&
+                !(type.name === "Record" && program.checker.isStdType(type)) &&
+                isSpeakableInstance(type) &&
+                !shouldInline(program, type));
+        default:
+            return false;
+    }
+}
+/**
+ * **Everything a service declares that its 3.0 document cannot publish, reported once each**,
+ * whichever walk renders it or none: a `null` in a union, named or written where it is used, a bare
+ * `null`, and a sealed model's record - see `unpublishable-null` and `unpublishable-record`.
+ * The walks refuse each as they reach it; this is what makes sure every one is named, the way a
+ * property's `T | null` is peeled off before any union is rendered.
+ */
+export function reportUnpublishable(program, service) {
+    if (!publishesOpenApi30(program))
+        return;
+    const check = (type) => {
+        const why = unpublishableNullWhy(program, type);
+        if (why !== undefined)
+            refuseUnpublishableNull(program, type, why);
+    };
+    navigateTypesInNamespace(service, {
+        union: check,
+        // A bare `null` is one type everywhere, so it is reported where it is used.
+        modelProperty: (property) => {
+            if (property.type.kind !== "Intrinsic")
+                return;
+            const why = unpublishableNullWhy(program, property.type);
+            if (why !== undefined)
+                refuseUnpublishableNull(program, property.type, why, property);
+        },
+        model: (model) => {
+            const record = unpublishableRecordOf(program, model);
+            if (record !== undefined)
+                refuseUnpublishableRecord(program, model, record);
+        },
+    }, { skipSubNamespaces: isGlobalNamespace(program, service) });
+}
+/** Refused where the 3.0 document cannot publish its `null` - see `unpublishable-null`. */
+function refuseUnpublishableNull(program, type, why, at = refusalTarget(type)) {
+    const target = at;
+    if (firstReportOf(program, "unpublishable-null", target)) {
+        reportDiagnostic(program, {
+            code: "unpublishable-null",
+            target,
+            format: { type: getTypeName(type), why },
+        });
+    }
+    return UNREPRESENTABLE;
+}
 function unionToZod(program, union) {
+    const unpublishable = unpublishableNullWhy(program, union);
+    if (unpublishable !== undefined)
+        return refuseUnpublishableNull(program, union, unpublishable);
     /**
      * A `@discriminated` union becomes `z.discriminatedUnion`, not `z.union`.
      *
@@ -2990,7 +3236,40 @@ export function withHeldDeclarations(given, run) {
         held = previous;
     }
 }
+/**
+ * **The record a sealed model's 3.0 document cannot see**, or `undefined`. openapi3's 3.0 sealing is
+ * `additionalProperties: { not: {} }` beside the model's own `properties` - it re-declares a base's
+ * properties there, so they survive - and a base that is a record declares none: `model M extends
+ * Record<string> { name: string }` sealed refuses every key the record admits, where 3.1's
+ * `unevaluatedProperties` sees the record through `allOf`. Mirrors {@link isSealed}: sealed here,
+ * with an ancestor whose indexer admits a value.
+ */
+export function unpublishableRecordOf(program, model) {
+    if (!publishesOpenApi30(program) || model.indexer !== undefined || !isSealed(model)) {
+        return undefined;
+    }
+    for (let base = model.baseModel; base !== undefined; base = base.baseModel) {
+        if (base.indexer !== undefined && !isNeverType(base.indexer.value))
+            return base;
+    }
+    return undefined;
+}
+/** Refused where the 3.0 document seals away a base's record - see `unpublishable-record`. */
+function refuseUnpublishableRecord(program, model, base) {
+    const target = refusalTarget(model);
+    if (firstReportOf(program, "unpublishable-record", target)) {
+        reportDiagnostic(program, {
+            code: "unpublishable-record",
+            target,
+            format: { type: getTypeName(model), base: getTypeName(base) },
+        });
+    }
+    return UNREPRESENTABLE;
+}
 function modelToZod(program, model) {
+    const record = unpublishableRecordOf(program, model);
+    if (record !== undefined)
+        return refuseUnpublishableRecord(program, model, record);
     /**
      * **A `@discriminator` base is its own object, deserialized as a subtype where the value is one.**
      * See {@link DiscriminatedBase}.
@@ -4284,6 +4563,14 @@ function propertyValueToZod(program, property, position = OWN_POSITION) {
      * `.optional()` stays outermost: a constraint after it would apply to the optionality rather than
      * to the value.
      */
+    // A `null` the 3.0 document cannot publish refuses the value - see `unpublishableNullWhy`.
+    const unpublishable = unpublishableNullWhy(program, property.type);
+    if (unpublishable !== undefined) {
+        return {
+            base: refuseUnpublishableNull(program, property.type, unpublishable),
+            description: getDoc(program, property),
+        };
+    }
     /**
      * `@encode` is read as `encodedValueOf` says the document publishes it, nullability included:
      * openapi3 3.1 publishes `anyOf: [<the encoded value>, { type: "null" }]` where the encoding is
@@ -5144,15 +5431,18 @@ export function typeToZodBody(program, type) {
          */
         case "UnionVariant":
             return typeToZod(program, type.type);
-        case "Intrinsic":
-            if (type.name === "null")
-                return "z.null()";
+        case "Intrinsic": {
+            if (type.name === "null") {
+                const why = unpublishableNullWhy(program, type);
+                return why === undefined ? "z.null()" : refuseUnpublishableNull(program, type, why);
+            }
             if (type.name === "unknown")
                 return "z.unknown()";
             if (type.name === "void" || type.name === "never") {
                 return refuse(program, type, `\`${type.name}\` has no runtime representation`, "Give the position a type a value can inhabit. A `never` property or parameter is dropped to match the document, and `Record<never>` seals the model, so none of those reaches here.");
             }
             return refuse(program, type, `intrinsic "${type.name}"`, "This emitter has no rule for that intrinsic. Replace it with a declared scalar or model.");
+        }
         /**
          * **openapi3 publishes a tuple as `prefixItems`, with no `items` or `minItems` beside it**:
          * any length, each position checked where it is present, anything past the last. That is a

package/package.json

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