sanurb/zod-openapi

zod-openapi

Purpose

This skill produces one atomic REST API contract for a new or changed HTTP surface. Good APIs are boring, WE DO NOT BREAK USERSPACE, and zod-openapi keeps the schema-first source of truth in Zod while createDocument emits the OpenAPI contract. Use it only when the project already uses zod-openapi as the contract layer.

Instructions

1. Define the Zod schema module. Read references/typescript-interfaces.md and references/zod-openapi-patterns.md. Declare GlobalMeta extends ZodOpenApiMetadata, register every reusable component with .meta({ id }), model branded IDs, separate input from output schemas, and include the reusable ProblemDetails schema.
2. Define the error contract. Read references/errors.md. Enumerate every failure mode, model RFC 9457 Problem Details, use application/problem+json for every 4xx/5xx, keep title static per error class, put dynamic context in detail, and wire HTTP Retry-After plus retry_after on 429 and 503.
3. Emit via createDocument. Read references/zod-openapi-patterns.md. Compose the ZodOpenApiObject with openapi: '3.1.0', info, components.securitySchemes.bearerAuth, security, and paths built from requestParams, requestBody, and responses; include rate-limit headers in response headers; then produce the final Output artifact.

Non-Negotiable Acceptance Criteria

Deliver nothing if ANY criterion fails.

General REST

1. Every 4xx and 5xx response MUST be RFC 9457 Problem Details under application/problem+json.
2. Every type URI MUST resolve to a url documentation.
3. Every error class MUST have a static title; dynamic context goes in detail only.
4. Every instance MUST be unique per occurrence.
5. Every 422 validation failure MUST include an errors array of { field, message, code }.
6. Every 429 and 503 MUST set HTTP Retry-After and the retry_after body field.
7. Every error_code and error_name MUST come from a central catalog.
8. Every POST create or side-effect endpoint MUST accept Idempotency-Key via requestParams.header; DELETE by resource ID MUST NOT require it.
9. Every list endpoint MUST paginate; cursor MUST be the default for unbounded datasets; the response MUST include next_page or nextCursor.
10. Every response MUST set RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers.
11. Every endpoint MUST support long-lived API key auth via Authorization: Bearer <key> through components.securitySchemes.bearerAuth; OAuth MAY layer on top.
12. Every endpoint MUST have separate TypeScript input and output types.
13. Every input MUST be validated with Zod at the HTTP boundary before any service call.
14. Every path MUST use plural-noun kebab-case; verbs in paths are forbidden.
15. WE DO NOT BREAK USERSPACE. Stable contracts change additively only, and consumers MUST tolerate unexpected fields.
16. Versioning is a last resort. Additive extension MUST come first.
17. Expensive or associated response fields MUST be opt-in via ?include=<field>.

zod-openapi specific

18. The legacy helpers extendZodWithOpenApi and the .openapi() runtime extension (both removed in v5) are forbidden. Metadata flows through native Zod .meta() only.
19. Every project MUST declare GlobalMeta extends ZodOpenApiMetadata via declare module 'zod/v4' once per module graph.
20. Every reusable component MUST register through .meta({ id: 'Name' }); hand-written $ref strings and implicit __schemaN names are forbidden.
21. Every recursive or z.lazy schema MUST declare an explicit .meta({ id }).
22. z.transform in output schemas is forbidden; use .pipe(), .overwrite(), or manual .meta({ override }).
23. createDocument MUST be the single entry point; hand-written OpenAPI YAML and direct oas31.OpenAPIObject construction are forbidden.
24. openapi: MUST be '3.1.0' or newer unless a concrete downstream constraint requires 3.0.x; if 3.0.x is used, the generator file MUST document why inline.
25. Every failure response MUST use content: { 'application/problem+json': { schema: ProblemDetails } }, and ProblemDetails MUST register via .meta({ id: 'ProblemDetails' }).
26. Every request parameter MUST live under requestParams: { path | query | header | cookie }; hand-rolled parameters: [...] arrays are forbidden.

Output

1. Resource Summary

Table columns: Method, Path (kebab-case plural), Purpose, Success Status, Auth Scope, Rate Limit Tier, Idempotency.

2. Zod Schema Module

TypeScript block with import * as z from 'zod/v4';, import type { ZodOpenApiMetadata } from 'zod-openapi';, declare module 'zod/v4' { interface GlobalMeta extends ZodOpenApiMetadata {} }, every input/output/reusable schema, branded IDs, and ProblemDetails.

3. createDocument Module

TypeScript block with import { createDocument } from 'zod-openapi';, import type { ZodOpenApiObject, ZodOpenApiPathsObject } from 'zod-openapi';, and a full createDocument({ openapi: '3.1.0', info, components: { schemas, securitySchemes }, security, paths }) call using requestParams, requestBody, responses, and response headers.

4. Error Catalog

Table: error_code, error_name, error_category, status, retryable, owner_action_required, title, type.

5. ProblemDetails Instances

One JSON block per failure mode showing the complete RFC 9457 Problem Details body emitted at runtime.

6. TypeScript Input/Output Types

TypeScript block deriving types via z.infer<>, including the input/output split for schemas that diverge and can emit Foo / FooOutput components.

7. curl Examples

One success curl and one failure curl per endpoint. Every curl MUST include Authorization: Bearer <key>, and every success case MUST show RateLimit-* response headers.

References

| File | One Job | |---|---| | references/zod-openapi-patterns.md | zod-openapi v5 path modeling, requestParams, createDocument, auth, rate limits | | references/errors.md | RFC 9457 catalog rules and ProblemDetails wiring | | references/typescript-interfaces.md | GlobalMeta augmentation, branded IDs, input/output type split |