docs: update zod docs on openai patterns

[nikuscs]

Summary by CodeRabbit

• Documentation
  • Expanded guidance for generating OpenAPI schemas from Zod, introducing a customizable mapping approach.
  • Clarifies how date fields are represented as string date-time in OpenAPI for more accurate API contracts and client generation.
  • Provides examples for overriding type handling during schema generation, helping users tailor output for specific types beyond dates.

[coderabbitai]

Walkthrough

Replaces a simple z.toJSONSchema mapper in documentation with a custom mapper that calls z.toJSONSchema(schema, { io, unrepresentable, override }). The override forces Zod date types to map to an OpenAPI string with date-time format, affecting OpenAPI schema generation behavior for dates (and potentially others via override).

Changes

Cohort / File(s)	Summary
Docs: OpenAPI mapping with Zod docs/patterns/openapi.md	Updated example to use a custom JSON Schema mapper with an override hook. The override maps Zod date to OpenAPI type "string" with format "date-time", replacing prior simple mapper usage.

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Dev as Developer
  participant Mapper as Custom Mapper
  participant Zod as z.toJSONSchema(...)
  participant OAS as OpenAPI Schema

  Dev->>Mapper: Generate schema from Zod
  Mapper->>Zod: toJSONSchema(schema, { io, unrepresentable, override })
  alt override: ZodDate detected
    Zod-->>Mapper: type: date
    Mapper-->>OAS: { type: "string", format: "date-time" }
  else other types
    Zod-->>Mapper: default JSON Schema
    Mapper-->>OAS: default mapping
  end
  Note over OAS: Resulting OpenAPI schema reflects explicit date-time for dates

Loading

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~10 minutes

Poem

I hopped through schemas, paws so light,
Turned dates to strings with time in sight.
An override nibble, neat and clean,
Now OpenAPI knows what “date-time” means.
Thump-thump! Docs refreshed, I cheer—
Carrots for code that’s crystal clear. 🥕

Pre-merge checks and finishing touches

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Title Check	⚠️ Warning	The title “docs: update zod docs on openai patterns” is overly generic, contains a typo (“openai” instead of “openapi”), and does not clearly summarize the key change of introducing a custom Zod-to-OpenAPI JSON Schema mapper with a date-time override for Zod date types.	Please revise the title to accurately and concisely reflect the change, for example “docs: add custom Zod-to-OpenAPI mapping with date-time override.”

✅ Passed checks (2 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Docstring Coverage	✅ Passed	No functions found in the changes. Docstring coverage check skipped.

✨ Finishing touches

🧪 Generate unit tests

• Create PR with unit tests
• Post copyable unit tests in a comment

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🧹 Nitpick comments (1)

docs/patterns/openapi.md (1)

186-186: Improve the comment clarity.

The comment "Zod Mapping Invalid types, dates & more" could be more descriptive. Consider clarifying what "invalid types" means in this context and what "more" refers to.

Suggested improvement:

-// Zod Mapping Invalid types, dates & more
+// Custom Zod mapping for handling dates and unrepresentable types

📜 Review details

Configuration used: CodeRabbit UI

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 8e16219 and f7a94ca.

📒 Files selected for processing (1)

• docs/patterns/openapi.md (1 hunks)

🧰 Additional context used

🪛 markdownlint-cli2 (0.18.1)

docs/patterns/openapi.md

188-188: Hard tabs
Column: 1

(MD010, no-hard-tabs)

🔇 Additional comments (1)

docs/patterns/openapi.md (1)

189-198: Use spaces for indentation and clarify the example heading

• The use of ctx.zodSchema._zod.def is correct per Zod v4 JSON Schema docs; no change needed there.
• Replace the hard tabs with spaces for consistent indentation.
• Update the heading/comment to specifically describe handling of date schemas rather than “dates & more.”

Likely an incorrect or invalid review comment.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor

Fix indentation to use spaces instead of hard tabs.

The code block contains hard tabs which are flagged by markdownlint. For consistency with the rest of the documentation, use spaces for indentation.

Based on static analysis hints.

Apply consistent spacing throughout the code block (the exact diff would depend on viewing the raw file, but ensure all lines use spaces, not tabs).

🧰 Tools

🪛 markdownlint-cli2 (0.18.1)

188-188: Hard tabs
Column: 1

(MD010, no-hard-tabs)

🤖 Prompt for AI Agents

In docs/patterns/openapi.md around lines 188 to 200, the code block uses hard
tab characters for indentation which violates markdownlint and repository style;
replace all hard tabs with spaces to match the project's indentation convention
(use the same number of spaces per indent level used elsewhere in the file,
e.g., 2 or 4 spaces), ensuring every line in the shown block and any nested
lines use spaces only and no \t characters.