@ancplua/qyl-api-schema 7.3.0 → 7.4.0

package/README.md

@@ -59,6 +59,28 @@ rather than from prose here; this line moves faster than a README is revised.
 `main.tsp` is the local compile entry point and includes emitter routing. `index.tsp`
 is the published TypeSpec entry point and contains only the client-facing contract.
 
+## Runtime validation
+
+`@ancplua/qyl-api-schema/zod` builds Zod validators from the bundled JSON Schema at
+runtime. It is a translation layer over `z.fromJSONSchema` — authored in `src/zod/`
+and compiled to `generated/zod-runtime/` — not a second hand-written schema, so a
+contract change cannot leave a validator describing the previous shape.
+
+```ts
+import { publishedContractSchema } from "@ancplua/qyl-api-schema/zod";
+import type { Span } from "@ancplua/qyl-api-schema/types";
+
+const SpanSchema = publishedContractSchema<Span>("OTel.Traces.Span");
+const span = SpanSchema.parse(await response.json());
+```
+
+`zod` is an optional peer dependency (`>=4.5.0 <5`): a consumer that does not
+install it simply never imports this subpath, and the other subpaths do not depend
+on it. Definition names are the published `$defs` keys — the same names the OpenAPI
+components and the generated C# and TypeScript DTOs carry — and
+`contractDefinitionNames()` lists all of them. The type argument is not checked
+against the schema, so pair it with the matching type from `./types`.
+
 ## Contract revision
 
 `scripts/emit-contract-revision.mjs` stamps a deterministic revision — `sha256:` plus

package/generated/zod-runtime/index.d.ts

@@ -0,0 +1,50 @@
+import { z } from "zod";
+/**
+ * A published contract type as it looks *before* validation: branded identity
+ * scalars are still plain strings and arrays may be readonly, because branding
+ * is what `parse` produces rather than what a caller can construct.
+ *
+ * Annotating a projection with `satisfies ContractInput<T>` moves the wire-name
+ * check from a runtime `parse` throw to a compile error, so a property spelled
+ * in an internal camelCase instead of the contract's snake_case cannot reach a
+ * response at all.
+ */
+export type ContractInput<TContract> = TContract extends {
+    readonly __brand: string;
+} ? string : TContract extends readonly (infer TElement)[] ? readonly ContractInput<TElement>[] : TContract extends (...args: never[]) => unknown ? TContract : TContract extends object ? {
+    readonly [K in keyof TContract]: ContractInput<TContract[K]>;
+} : TContract;
+/**
+ * Build a strict runtime validator for one published contract definition.
+ *
+ * `definitionName` is a key of the published schema's `$defs` — the same name
+ * the OpenAPI component and the generated C#/TypeScript DTOs carry, for example
+ * `"OTel.Traces.Span"` or `"Common.Errors.ProblemDetails"`. Pair it with the
+ * matching type from `@ancplua/qyl-api-schema/types`; the type argument is not
+ * checked against the schema, so an unrelated one produces a validator that
+ * lies about what it returns.
+ *
+ * Results are memoized per name: building a schema walks the whole definition,
+ * and the returned validator is stateless.
+ *
+ * @throws Error if no such definition is published.
+ *
+ * @example
+ * ```ts
+ * import { publishedContractSchema } from "@ancplua/qyl-api-schema/zod";
+ * import type { Span } from "@ancplua/qyl-api-schema/types";
+ *
+ * const SpanSchema = publishedContractSchema<Span>("OTel.Traces.Span");
+ * const span = SpanSchema.parse(await response.json());
+ * ```
+ */
+export declare function publishedContractSchema<TContract>(definitionName: string): z.ZodType<TContract>;
+/**
+ * Every definition name {@link publishedContractSchema} accepts, sorted.
+ *
+ * Enumerating the published surface is how a consumer proves it covers all of
+ * it — a contract definition that gains no validator is otherwise invisible.
+ */
+export declare function contractDefinitionNames(): readonly string[];
+/** The published schema's `$id`, for reporting which contract a validator came from. */
+export declare const contractJsonSchemaId: string;

package/generated/zod-runtime/index.js

@@ -0,0 +1,262 @@
+// Runtime validators for the contracts this package publishes.
+//
+// The JSON Schema in generated/json-schema/qyl-api-schema.json is the artifact a
+// validator should be derived from, not a second hand-maintained copy of it: a
+// contract change that a consumer forgets to mirror is exactly the failure this
+// module exists to make impossible. Everything below is therefore a translation
+// layer over `z.fromJSONSchema`, not a schema in its own right.
+//
+// The package's own schema is reached by self-reference through the "exports"
+// map, so this file resolves the same artifact from source, from
+// generated/zod-runtime, and from inside an installed node_modules copy.
+import contractJsonSchema from "@ancplua/qyl-api-schema/json-schema" with { type: "json" };
+import { z } from "zod";
+/**
+ * Rewrite the published JSON Schema into the subset `z.fromJSONSchema` accepts,
+ * preserving the contract's meaning exactly. Three published constructs need it:
+ *
+ * - `unevaluatedProperties` — `z.fromJSONSchema` rejects the keyword outright.
+ *   The emitted schemas only ever use it to seal an object, which
+ *   `additionalProperties` expresses for the same shapes.
+ * - `allOf` inheritance — a derived object carries a single `$ref` base plus its
+ *   own properties. Zod builds that as an intersection, and an intersection of a
+ *   sealed base with a sealed extension accepts neither side's extra keys but
+ *   also loses the base's own key set, so the derived object stops rejecting
+ *   unknown keys. Flattening the base into the derivative keeps one sealed
+ *   object with the full key set.
+ * - 64-bit integers — Zod's `int64` conversion adds a +/-2^53 range check. The
+ *   contract has no such bound (Unix nanosecond timestamps exceed it), so the
+ *   integer rule is kept as `multipleOf: 1` and the format is dropped.
+ *
+ * `format: "date-time"` is deliberately left untouched: Zod 4.5's conversion is
+ * already RFC 3339 offset-aware (it accepts `+02:00`, requires seconds, and
+ * rejects colon-less offsets). scripts/verify-zod-contracts.mjs pins that.
+ * One consequence for consumers that republish a validator through
+ * `z.toJSONSchema`: the output carries `format: "date-time"` next to the RFC
+ * 3339 pattern, so a pinned snapshot of such output changes when a consumer
+ * moves onto this module.
+ */
+function adaptPublishedSchemaForZod(schemaNode) {
+    if (typeof schemaNode !== "object" || schemaNode === null || Array.isArray(schemaNode)) {
+        throw new Error("Published Qyl JSON Schema root must be an object");
+    }
+    const root = schemaNode;
+    const sourceDefinitions = asSchemaRecord(root.$defs, "$defs");
+    const definitionCache = new Map();
+    const resolvingDefinitions = new Set();
+    const definition = (name) => {
+        const cached = definitionCache.get(name);
+        if (cached)
+            return cached;
+        // Inheritance is flattened by inlining the base, so a cycle would recurse
+        // forever rather than fail; a $ref cycle that is not inheritance is fine and
+        // never reaches here.
+        if (resolvingDefinitions.has(name)) {
+            throw new Error(`Published Qyl JSON Schema has an inheritance cycle at '${name}'`);
+        }
+        const source = sourceDefinitions[name];
+        if (source === undefined) {
+            throw new Error(`Published Qyl JSON Schema is missing definition '${name}'`);
+        }
+        resolvingDefinitions.add(name);
+        const adapted = adaptNode(source);
+        resolvingDefinitions.delete(name);
+        definitionCache.set(name, adapted);
+        return adapted;
+    };
+    const adaptNode = (node) => {
+        if (typeof node !== "object" || node === null || Array.isArray(node)) {
+            throw new Error("Expected a JSON Schema object node");
+        }
+        const source = node;
+        const inheritedDefinitions = inheritedObjectDefinitions(source, definition);
+        const adapted = {};
+        if (inheritedDefinitions.length > 0) {
+            let inheritedAdditionalProperties;
+            for (const inherited of inheritedDefinitions) {
+                const existingProperties = optionalSchemaRecord(adapted.properties);
+                const inheritedProperties = optionalSchemaRecord(inherited.properties);
+                const existingRequired = stringArray(adapted.required);
+                const inheritedRequired = stringArray(inherited.required);
+                Object.assign(adapted, inherited);
+                adapted.properties = { ...existingProperties, ...inheritedProperties };
+                adapted.required = [...new Set([...existingRequired, ...inheritedRequired])];
+                inheritedAdditionalProperties = inherited.additionalProperties;
+            }
+            // The derivative documents itself and seals itself; inheriting either
+            // would describe the wrong type and could reopen a sealed object.
+            delete adapted.description;
+            delete adapted.additionalProperties;
+            for (const [keyword, child] of Object.entries(source)) {
+                if (keyword === "allOf" ||
+                    keyword === "properties" ||
+                    keyword === "required" ||
+                    keyword === "unevaluatedProperties") {
+                    continue;
+                }
+                adapted[keyword] = adaptValue(child);
+            }
+            adapted.properties = {
+                ...optionalSchemaRecord(adapted.properties),
+                ...adaptSchemaRecord(source.properties),
+            };
+            const required = [
+                ...new Set([...stringArray(adapted.required), ...stringArray(source.required)]),
+            ];
+            if (required.length > 0)
+                adapted.required = required;
+            else
+                delete adapted.required;
+            if ("unevaluatedProperties" in source) {
+                adapted.additionalProperties = adaptUnevaluatedProperties(source.unevaluatedProperties);
+            }
+            else if (inheritedAdditionalProperties !== undefined) {
+                adapted.additionalProperties = inheritedAdditionalProperties;
+            }
+        }
+        else {
+            for (const [keyword, child] of Object.entries(source)) {
+                if (keyword === "unevaluatedProperties")
+                    continue;
+                adapted[keyword] = adaptValue(child);
+            }
+            if ("unevaluatedProperties" in source) {
+                adapted.additionalProperties = adaptUnevaluatedProperties(source.unevaluatedProperties);
+            }
+        }
+        if (source.type === "integer" &&
+            (source.format === "int64" || source.format === "uint64")) {
+            adapted.type = "number";
+            adapted.multipleOf = 1;
+            delete adapted.format;
+        }
+        return adapted;
+    };
+    const adaptValue = (value) => {
+        if (Array.isArray(value))
+            return value.map(adaptValue);
+        if (typeof value === "object" && value !== null)
+            return adaptNode(value);
+        return value;
+    };
+    const adaptSchemaRecord = (value) => {
+        const record = optionalSchemaRecord(value);
+        return Object.fromEntries(Object.entries(record).map(([name, child]) => [name, adaptValue(child)]));
+    };
+    const adaptUnevaluatedProperties = (value) => isFalseSchema(value) ? false : adaptValue(value);
+    const rootWithoutDefinitions = { ...root };
+    delete rootWithoutDefinitions.$defs;
+    const adaptedRoot = adaptNode(rootWithoutDefinitions);
+    // Re-attached after adaptation so every `#/$defs/...` reference in an adapted
+    // node resolves against the adapted definitions rather than the source ones.
+    adaptedRoot.$defs = Object.fromEntries(Object.keys(sourceDefinitions).map((name) => [name, definition(name)]));
+    return adaptedRoot;
+}
+/**
+ * The base definitions a node inherits from, or none if this is not the
+ * single-`$ref`-base object inheritance the emitter produces. Anything else —
+ * an `allOf` of inline schemas, a non-object base — is left for Zod to build as
+ * a real intersection.
+ */
+function inheritedObjectDefinitions(source, resolve) {
+    if (source.type !== "object" || !Array.isArray(source.allOf))
+        return [];
+    const names = source.allOf.map((entry) => definitionNameFromRef(entry));
+    if (names.some((name) => name === undefined))
+        return [];
+    const inherited = names.map((name) => resolve(name));
+    return inherited.every((definition) => definition.type === "object") ? inherited : [];
+}
+function definitionNameFromRef(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return undefined;
+    const record = value;
+    if (Object.keys(record).length !== 1 || typeof record.$ref !== "string")
+        return undefined;
+    const prefix = "#/$defs/";
+    return record.$ref.startsWith(prefix) ? record.$ref.slice(prefix.length) : undefined;
+}
+function asSchemaRecord(value, context) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new Error(`Published Qyl JSON Schema ${context} must be an object`);
+    }
+    return value;
+}
+function optionalSchemaRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+function stringArray(value) {
+    return Array.isArray(value) && value.every((item) => typeof item === "string")
+        ? value
+        : [];
+}
+/** `{ "not": {} }` — how the emitter spells "no further properties". */
+function isFalseSchema(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return false;
+    const record = value;
+    const not = record.not;
+    return Object.keys(record).length === 1 &&
+        typeof not === "object" &&
+        not !== null &&
+        !Array.isArray(not) &&
+        Object.keys(not).length === 0;
+}
+const zodCompatibleContractJsonSchema = adaptPublishedSchemaForZod(contractJsonSchema);
+const zodCompatibleDefinitions = asSchemaRecord(zodCompatibleContractJsonSchema.$defs, "$defs");
+const publishedContractSchemas = new Map();
+/**
+ * Build a strict runtime validator for one published contract definition.
+ *
+ * `definitionName` is a key of the published schema's `$defs` — the same name
+ * the OpenAPI component and the generated C#/TypeScript DTOs carry, for example
+ * `"OTel.Traces.Span"` or `"Common.Errors.ProblemDetails"`. Pair it with the
+ * matching type from `@ancplua/qyl-api-schema/types`; the type argument is not
+ * checked against the schema, so an unrelated one produces a validator that
+ * lies about what it returns.
+ *
+ * Results are memoized per name: building a schema walks the whole definition,
+ * and the returned validator is stateless.
+ *
+ * @throws Error if no such definition is published.
+ *
+ * @example
+ * ```ts
+ * import { publishedContractSchema } from "@ancplua/qyl-api-schema/zod";
+ * import type { Span } from "@ancplua/qyl-api-schema/types";
+ *
+ * const SpanSchema = publishedContractSchema<Span>("OTel.Traces.Span");
+ * const span = SpanSchema.parse(await response.json());
+ * ```
+ */
+export function publishedContractSchema(definitionName) {
+    const cached = publishedContractSchemas.get(definitionName);
+    if (cached)
+        return cached;
+    if (!Object.hasOwn(zodCompatibleDefinitions, definitionName)) {
+        throw new Error(`Published Qyl JSON Schema has no '${definitionName}' definition`);
+    }
+    const schema = z.fromJSONSchema({
+        $schema: zodCompatibleContractJsonSchema.$schema,
+        $defs: zodCompatibleDefinitions,
+        $ref: `#/$defs/${definitionName}`,
+    });
+    publishedContractSchemas.set(definitionName, schema);
+    return schema;
+}
+const definitionNames = Object.freeze(Object.keys(zodCompatibleDefinitions).sort());
+/**
+ * Every definition name {@link publishedContractSchema} accepts, sorted.
+ *
+ * Enumerating the published surface is how a consumer proves it covers all of
+ * it — a contract definition that gains no validator is otherwise invisible.
+ */
+export function contractDefinitionNames() {
+    return definitionNames;
+}
+/** The published schema's `$id`, for reporting which contract a validator came from. */
+export const contractJsonSchemaId = typeof contractJsonSchema.$id === "string"
+    ? contractJsonSchema.$id
+    : "";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ancplua/qyl-api-schema",
-  "version": "7.3.0",
+  "version": "7.4.0",
   "description": "TypeSpec source of truth for qyl API contracts. Emits OpenAPI, JSON Schema, Qyl.Api.Contracts DTOs, and TypeScript contract types; not an OpenTelemetry package, storage schema, or server implementation.",
   "license": "Apache-2.0",
   "repository": {
@@ -46,6 +46,11 @@
     },
     "./json-schema": {
       "default": "./generated/json-schema/qyl-api-schema.json"
+    },
+    "./zod": {
+      "types": "./generated/zod-runtime/index.d.ts",
+      "import": "./generated/zod-runtime/index.js",
+      "default": "./generated/zod-runtime/index.js"
     }
   },
   "files": [
@@ -75,6 +80,8 @@
     "generated/ts-runtime/api.js",
     "generated/openapi/qyl.openapi.json",
     "generated/json-schema/qyl-api-schema.json",
+    "generated/zod-runtime/index.d.ts",
+    "generated/zod-runtime/index.js",
     "README.md",
     "LICENSE"
   ],
@@ -87,17 +94,19 @@
     "clean:generated": "node scripts/clean-generated.mjs",
     "build:emitters": "tsc -p emitters/csharp && tsc -p emitters/ts-types && tsc -p emitters/qyl-lint",
     "build:ts-runtime": "tsc -p tsconfig.contracts.json",
+    "build:zod-runtime": "tsc -p tsconfig.zod.json",
     "build:json-schema": "node scripts/openapi-to-json-schema.mjs",
     "emit:mcp-tool-schemas": "node scripts/emit-mcp-tool-schemas.mjs",
     "emit:contract-revision": "node scripts/emit-contract-revision.mjs",
     "prepare": "npm run build:emitters",
     "prepack": "npm run compile",
-    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run emit:contract-revision && npm run build:json-schema && npm run emit:mcp-tool-schemas && npm run build:ts-runtime",
+    "compile": "npm run clean:generated && npm run build:emitters && tsp compile main.tsp && npm run emit:contract-revision && npm run build:json-schema && npm run emit:mcp-tool-schemas && npm run build:ts-runtime && npm run build:zod-runtime",
     "format": "tsp format **/*.tsp",
     "lint": "npm run build:emitters && tsp compile main.tsp --no-emit --warn-as-error",
     "lint:public": "npm run build:emitters && tsp compile index.tsp --no-emit --warn-as-error",
     "verify:routes": "node scripts/verify-route-contracts.mjs",
     "verify:contracts": "node scripts/verify-contract-fixtures.mjs",
+    "verify:zod-contracts": "npm run build:zod-runtime && node scripts/verify-zod-contracts.mjs",
     "verify:lint-rules": "npm run build:emitters && node scripts/verify-lint-rules.mjs"
   },
   "peerDependencies": {
@@ -106,7 +115,8 @@
     "@typespec/http": "^1.13.0",
     "@typespec/openapi": "^1.13.0",
     "@typespec/openapi3": "^1.13.0",
-    "@typespec/sse": ">=0.83.0 <0.86.0"
+    "@typespec/sse": ">=0.83.0 <0.86.0",
+    "zod": ">=4.5.0 <5"
   },
   "peerDependenciesMeta": {
     "@typespec/compiler": {
@@ -126,13 +136,16 @@
     },
     "@typespec/sse": {
       "optional": true
+    },
+    "zod": {
+      "optional": true
     }
   },
   "devDependencies": {
     "@ancplua/typespec-emit-csharp": "file:./emitters/csharp",
     "@ancplua/typespec-emit-ts-types": "file:./emitters/ts-types",
     "@ancplua/typespec-qyl-lint": "file:./emitters/qyl-lint",
-    "@types/node": "26.2.0",
+    "@types/node": "26.3.0",
     "@typespec/compiler": "1.15.0",
     "@typespec/events": "0.85.0",
     "@typespec/http": "1.15.0",
@@ -140,6 +153,7 @@
     "@typespec/openapi3": "1.15.0",
     "@typespec/sse": "0.85.0",
     "ajv": "8.20.0",
-    "typescript": "7.0.2"
+    "typescript": "7.0.2",
+    "zod": "4.5.4"
   }
 }