fix(fastify): omit schema keys which the spec does not define

[eastagiletracker]

This PR proposes omitting the Fastify schema keys that a spec does not define, so toRoutes() no longer makes Fastify log FSTWRN001 for every route (fixes #167). We include this PR work along with a full history of your repo at https://eastagiletracker.com/projects/447. You can sign in with your GitHub ID to claim ownership of the project.

The defect

toSchema() copies all four request parts unconditionally, so a spec that defines only query still produces { querystring, params: undefined, body: undefined, headers: undefined, response }. Fastify does not test those keys for truthiness — in lib/validation.js it falls through to Object.hasOwn(schema, 'body') and warns with FSTWRN001 for each key that is present but undefined. Every route defined through toRoutes() therefore logs one warning per request part it does not use, which is exactly what #167 reports.

Reproduced on main at d816230, with the /users GET spec from examples/misc/spec/zod.ts registered on a Fastify 5.8.5 instance (toRoutes(pathMap) → fastify.route({ ...routes["/users"]["get"], handler }) → fastify.ready()):

$ npx tsx repro.mts
schema keys emitted by toRoutes(): ["querystring","params","body","headers","response"]
(node:121907) [FSTWRN001] FastifyWarning: The headers schema for GET: /users is missing. This may indicate the schema is not well specified.
(node:121907) [FSTWRN001] FastifyWarning: The body schema for GET: /users is missing. This may indicate the schema is not well specified.
(node:121907) [FSTWRN001] FastifyWarning: The params schema for GET: /users is missing. This may indicate the schema is not well specified.
(node:121907) [FSTWRN001] FastifyWarning: The headers schema for HEAD: /users is missing. This may indicate the schema is not well specified.
(node:121907) [FSTWRN001] FastifyWarning: The body schema for HEAD: /users is missing. This may indicate the schema is not well specified.
(node:121907) [FSTWRN001] FastifyWarning: The params schema for HEAD: /users is missing. This may indicate the schema is not well specified.
FastifyWarning count: 6

The change

toSchema() now starts from { response } and adds querystring / params / body / headers only when the spec actually defines them, as suggested in the issue. The same script on this branch prints schema keys emitted by toRoutes(): ["response","querystring"] and FastifyWarning count: 0, and the same holds through the built package (dist/fastify/index.js).

The exported FastifySchema type is deliberately left as it is, so this is a runtime-only change: code that reads routes[path][method].schema.querystring keeps compiling, and the fastify-type-provider-zod inference used in examples/misc/fastify/zod/fastify.ts is untouched. A spec key explicitly written as undefined is treated as not defined, which is the same behaviour Fastify would want for it.

Verification

src/fastify/index.test.ts is new and covers three things: the key set that toSchema() produces for a partial spec and for a spec that defines all four parts, that no FSTWRN001 is emitted while the generated routes are registered (asserted through a spy on process.emitWarning), and — via fastify.inject() — that the parts a spec does define are still compiled and enforced (GET /users?page=1 → 200, GET /users → 400). Against the unchanged toSchema() two of these fail, including AssertionError: expected [ 'FSTWRN001', 'FSTWRN001', …(7) ] to not include 'FSTWRN001'; with the change all four pass.

npm run build -w pkgs/typed-api-spec and npm test -w pkgs/typed-api-spec were run on main before the change and on this branch after it. Baseline: 39 tests in 8 files passing, with test:lint, test:format and test:type-check clean. After: 43 tests in 9 files passing, the same three checks clean, and the build unchanged — no new failures.

How this was managed

We tracked this work as the story for #167 on a board imported from this repository's own issues, pull requests and milestones (303 stories), and moved it through in-progress to finished as the fix was written and verified.

If you'd rather not receive contributions like this, reply no-more-prs on this pull request and we won't open any further ones on your repositories.

---

Lawrence W. Sinclair
CEO / East Agile
linkedin.com/in/lwsinclair/
eastagile.com