feat: Custom named schemas in Documentation

[RobinTail]

Related to #1393 (comment)

Summary by CodeRabbit

• New Features

  • Documentation generation now supports explicit schema naming via schema metadata (use schema.meta({ id: "UniqueName" })) for stable, meaningful OpenAPI component names.

• Documentation

  • Changelog entry added for v26.2.0 describing schema-naming capability.
  • Example OpenAPI schema renamed to "Feature" in generated docs.
  • README contributor list updated and usage note added for schema.meta({ id }).

• Tests

  • Tests updated to exercise schema metadata and naming behavior.

• Refactor

  • Internal documentation naming logic refined for more consistent schema registration.

_{✏️ Tip: You can customize this high-level summary in your review settings.}

[coderabbitai]

📝 Walkthrough

Walkthrough

Zod schema metadata IDs (.meta({ id })) are now used to propose OpenAPI component names; documentation helpers and registration were updated to accept a proposed name, resolve a unique component name against rootDoc.components.schemas, cache the mapping, and register the schema under that name.

Changes

Cohort / File(s)	Summary
Example schemas & docs example/endpoints/retrieve-user.ts, example/example.documentation.yaml, express-zod-api/tests/documentation.spec.ts	Examples/tests now attach .meta({ id: "..." }) (e.g., Feature); OpenAPI YAML component renamed (Schema1 → Feature) and $ref occurrences updated.
Documentation helpers interface express-zod-api/src/documentation-helpers.ts	ReqResCommons.makeRef parameter names changed (subject→value, name→proposedName); call sites pass jsonSchema.id / depiction.id as the proposed name.
Documentation implementation express-zod-api/src/documentation.ts	#makeRef refactored to accept value and proposedName; resolves a unique name (prefers proposedName, falls back to "Schema"+counter), checks uniqueness against rootDoc.components.schemas, caches the key→name mapping, and registers via addSchema(name, value).
Changelog & README CHANGELOG.md, README.md	Added v26.2.0 changelog entry documenting schema naming via .meta({ id }); README updated with contributor avatars and a note about using schema.meta({ id: "UniqueName" }).

Sequence Diagram(s)

sequenceDiagram
  autonumber
  participant Route as Route (Zod schema)
  participant DocHelper as DocumentationHelpers
  participant DocImpl as Documentation (rootDoc)
  participant Registry as SchemaRegistry

  Note over Route,DocHelper: Route schema may include .meta({ id })
  Route->>DocHelper: provide jsonSchema (includes .meta.id)
  DocHelper->>DocImpl: ctx.makeRef(key, value, proposedName=jsonSchema.id)
  DocImpl->>Registry: resolveOrCreateName(key, proposedName)
  alt proposedName unused
    Registry-->>DocImpl: name = proposedName
  else name conflict
    Registry-->>DocImpl: name = proposedName + counter
  end
  DocImpl->>Registry: addSchema(name, value)
  DocImpl-->>DocHelper: ReferenceObject { $ref: "#/components/schemas/" + name }
  DocHelper-->>Route: attach reference in OpenAPI output

Loading

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~20 minutes

Possibly related PRs

• v24 is for Ashley Burton #2546: Related documentation/schema-naming updates that introduce and propagate schema IDs for OpenAPI generation.

Suggested labels

refactoring

Poem

🐰
I nudged an id into the bloom,
A Feature named to find its room.
If names collide I count and hop,
Till every schema finds its spot. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately summarizes the main feature introduced: enabling custom naming of schemas in generated documentation via .meta({ id }) metadata.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch custom-named-refs

---

📜 Recent review details

Configuration used: defaults

Review profile: CHILL

Plan: Pro

📥 Commits

Reviewing files that changed from the base of the PR and between 7ac7de3 and a0b3ec6.

📒 Files selected for processing (1)

• CHANGELOG.md

🧰 Additional context used

🧠 Learnings (4)

📓 Common learnings

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/src/metadata.ts:5-13
Timestamp: 2025-05-27T20:08:50.699Z
Learning: The `_zod` property in Zod v4 schemas is officially documented and recommended for library authors to differentiate between Zod 3 and Zod 4 schemas at runtime, despite the underscore prefix. This is explicitly mentioned in Zod's library authors documentation and is not a private internal property.

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/tests/form-schema.spec.ts:31-31
Timestamp: 2025-05-27T19:27:13.492Z
Learning: Zod version 3.25.0 and later expose the Zod v4 API through the special import paths "zod/v4" and "zod/v4/core", allowing v4 features like .loose() to be used even when the package.json dependency shows a 3.x version.

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/src/json-schema-helpers.ts:1-3
Timestamp: 2025-05-27T20:27:17.015Z
Learning: The JSONSchema type is not exported from the main "zod" module and must be imported from "zod/v4/core" when using Zod v4. This is acceptable for type-only imports as they don't create runtime dependencies.

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/src/documentation-helpers.ts:508-512
Timestamp: 2025-05-28T07:58:09.853Z
Learning: In express-zod-api, when working with Zod's JSON schema override callbacks, using `delete` to mutate `ctx.jsonSchema` is the recommended approach per Zod's official documentation, even if it triggers performance linting warnings. This is preferable to creating copies with `undefined` values, especially for snapshot testing.

📚 Learning: 2025-05-27T20:08:50.699Z

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/src/metadata.ts:5-13
Timestamp: 2025-05-27T20:08:50.699Z
Learning: The `_zod` property in Zod v4 schemas is officially documented and recommended for library authors to differentiate between Zod 3 and Zod 4 schemas at runtime, despite the underscore prefix. This is explicitly mentioned in Zod's library authors documentation and is not a private internal property.

Applied to files:

• CHANGELOG.md

📚 Learning: 2025-05-27T19:27:13.492Z

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2546
File: express-zod-api/tests/form-schema.spec.ts:31-31
Timestamp: 2025-05-27T19:27:13.492Z
Learning: Zod version 3.25.0 and later expose the Zod v4 API through the special import paths "zod/v4" and "zod/v4/core", allowing v4 features like .loose() to be used even when the package.json dependency shows a 3.x version.

Applied to files:

• CHANGELOG.md

📚 Learning: 2025-08-05T14:43:24.702Z

Learnt from: RobinTail
Repo: RobinTail/express-zod-api PR: 2869
File: zod-plugin/package.json:42-44
Timestamp: 2025-08-05T14:43:24.702Z
Learning: Zod version 4 has been officially released and is stable. As of August 2025, the latest published version is 4.0.14 (published July 30, 2025). Zod v4 is available on npm and can be used in peer dependencies with version constraints like "^4.0.0".

Applied to files:

• CHANGELOG.md

🔇 Additional comments (1)

CHANGELOG.md (1)

5-12: LGTM!

The changelog entry is well-structured and clearly documents the new feature. The attribution to both the original proposer (@arlyon) and the implementation contributor (@Upsilon-Iridani) is appreciated. The explanation properly notes the Zod 4 dependency, which aligns with the framework's versioning and release context.

---

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.}

[coveralls-official]

coverage: 100.0%. remained the same
when pulling a0b3ec6 on custom-named-refs
into 351ba7f on master.

[RobinTail]

🏁