[dinwwwh]

Requested by dinwwwh · project thread

What

#150 and #174 keep a $ref with only annotations beside it bare in 3.0 when it is a branch of a tagged union, or points to a schema whose discriminator stays. The check, isAnnotatedRef, reads the 3.1 input but only counted the 3.0 annotation names (example, description, ...) and x- keys. So the 3.1 annotations examples and $comment made it fail, and { $ref: Tagged, examples: [...] } became { allOf: [{ $ref: Tagged }], example: ... }.

Real case: the Anthropic API's BetaWebhookEvent.data is { $ref: BetaWebhookEventData, examples: [...] }, where BetaWebhookEventData is a 22-way oneOf with a discriminator and mapping. On main, openapi-typescript then writes data: Omit<components["schemas"]["BetaWebhookEventData"], "type">, dropping the tag so code can't narrow on type. With this change it writes data: components["schemas"]["BetaWebhookEventData"].

Change

• isAnnotatedRef also accepts examples and $comment. As with example, they are dropped beside the bare $ref.
• The existing tests for both cases (tagged branch, $ref to a tagged target) now include examples and $comment; both fail on main.
• README $ref row names the examples the Anthropic API writes there.

Checks

• pnpm run check, pnpm test (364 tests), coverage 100%.
• Over the hunt corpus (19,775 docs) only this one site changes; a value oracle on the Anthropic doc finds no accepted value lost.

---

Generated by Claude Code

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will not alter performance

1 warning

⚠️ 1 benchmark is dominated by system calls

System calls cannot be simulated consistently and are left out of the measure. The reported value understates the real cost. Switch to the Walltime instrument to measure them.

Learn more about system calls

See affected benchmarks

✅ 29 untouched benchmarks
⏩ 2 skipped benchmarks¹

---

_{Comparing claude/project-thread-efhq6v (5e22405) with main (a16a798)}

Footnotes

1. 2 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

[pullfrog]

✅ No new issues found.

Reviewed changes

• isAnnotatedRef accepts examples and $comment — packages/downgrader/src/v3.1-to-v3.0.ts:358 now treats the two 3.1 annotation keys as annotation-only siblings, so a $ref beside them stays bare in a tagged union or when pointing at a schema whose discriminator survives.
• Tests extended — both tagged-ref tests in packages/downgrader/tests/v3.1-to-v3.0.test.ts now include examples/$comment on the ref, and the branch/property cases assert the bare $ref.
• README $ref row — names the Anthropic examples written beside the property holding a tagged union.

Both call sites are tagged-only (convertTaggedBranch, and convertSchema's isAnnotatedRef && isTaggedRef guard), and examples/$comment are validation-neutral, so the change cannot widen acceptance — it only drops the siblings as documented. Verified locally: vitest run packages/downgrader → 287 passed.

  ^{｜ View workflow run ｜ Using deepseek-v4.1-flash (free via Pullfrog for OSS) ｜ 𝕏}