From bbb1e81615dffc182754da7a2c763175e9881314 Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 6 Sep 2026 04:52:51 +0000 Subject: [PATCH] docs(spec): record DeleteDataRequestSchema's consumer and why the DELETE data door carries no requestSchema MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The docblock above `DeleteDataRequestSchema` in `packages/spec/src/api/protocol.zod.ts` was bare. It now records three verified facts for the next reader who greps the name and sees "exported, documented, zero safeParse call sites": the schema is the request contract of `DataProtocol.deleteData()` (consumed statically via the `DeleteDataRequest` alias); it deliberately carries no REST-door `requestSchema` under #3899, which the catalog entry states in place of the key and `plugin-rest-api.schema-refs.test.ts` pins ("requestSchema appears only on body-carrying methods"); and drift between the schema and that door is caught at compile time by the typed request literal `ServerScopedDataRequest` in `packages/rest/src/rest-server.ts` (#15866), not by a runtime parse. Comment and changeset only — no shape, `.describe()`, or export change; no other `*RequestSchema` docblock is touched. Co-Authored-By: Claude Opus 5 Claude-Session: https://claude.ai/code/session_01T6HeZvT9wdSJD1ZxJb5Eno --- .../delete-data-request-schema-provenance.md | 9 +++++++ packages/spec/src/api/protocol.zod.ts | 24 +++++++++++++++++++ 2 files changed, 33 insertions(+) create mode 100644 .changeset/delete-data-request-schema-provenance.md diff --git a/.changeset/delete-data-request-schema-provenance.md b/.changeset/delete-data-request-schema-provenance.md new file mode 100644 index 0000000000..7c1bccf9d5 --- /dev/null +++ b/.changeset/delete-data-request-schema-provenance.md @@ -0,0 +1,9 @@ +--- +"@objectstack/spec": patch +--- + +Record, on `DeleteDataRequestSchema` itself, what it is for and why the DELETE data door carries no `requestSchema` for it. + +The schema is the request contract of `DataProtocol.deleteData()`, consumed statically through the `DeleteDataRequest` type alias and parsed at runtime nowhere — a grep that finds "exported, documented, zero `safeParse` call sites" is reading the wrong surface, and had already filed it once as a gap. Its docblock now says so; records that the absence of a `requestSchema` on `DELETE /api/v1/data/:object/:id` is a pinned decision (#3899 — the catalog entry states it in place of the key, and `plugin-rest-api.schema-refs.test.ts` goes red if one is added, because the route reads no body); and points at the compile-time check (#15866) under which a field added to the schema as required reddens the door at build instead of being silently unsent. + +Documentation only: no shape, `.describe()` text, or export changes. `@objectstack/spec` ships the new text in its published type declarations and in the source file it publishes directly via its `src/**/*.zod.ts` entry. diff --git a/packages/spec/src/api/protocol.zod.ts b/packages/spec/src/api/protocol.zod.ts index 84d329b3a0..8c427d73a4 100644 --- a/packages/spec/src/api/protocol.zod.ts +++ b/packages/spec/src/api/protocol.zod.ts @@ -2125,6 +2125,30 @@ export const UpdateDataResponseSchema = lazySchema(() => z.object({ /** * Delete Data Request + * + * [#13852] The request contract of {@link DataProtocol.deleteData} — its + * declared parameter type is the `DeleteDataRequest` alias below. That + * protocol boundary is this schema's whole job: it is consumed statically, by + * the compiler, and parsed at runtime nowhere in the tree. A grep that finds + * "exported, documented, zero `safeParse` call sites" is reading the wrong + * surface — #13852 is that grep, filed once already. + * + * It deliberately carries no REST-door `requestSchema` (#3899): + * `DELETE /api/v1/data/:object/:id` reads no body — `object` and `id` are + * path-bound, `expectedVersion` rides `?expectedVersion` / `If-Match` — so a + * schema on that door would promise a validation nothing can violate. The + * catalog entry in `plugin-rest-api.zod.ts` says so in place of the key, and + * the pin in `plugin-rest-api.schema-refs.test.ts` ("requestSchema appears + * only on body-carrying methods") goes red if one is added. ⛔ Do not wire + * one, and do not retire this schema either — it types a shipped interface + * method. + * + * Drift between this schema and that door is caught at COMPILE time, not by a + * runtime parse: the door's request literal is typed against + * `DeleteDataRequest` (`ServerScopedDataRequest` in + * `packages/rest/src/rest-server.ts`, #15866 / PR #16071), so a field added + * here as REQUIRED reddens that file at build, naming the route that would + * otherwise have gone on not sending it. */ export const DeleteDataRequestSchema = lazySchema(() => z.object({ object: z.string().describe('Object name'),