Repository navigation
Commit 8a5abff
fix(downgrader): keep a $ref bare beside a type its tagged target holds too (#344)
<!-- claude-projects-attribution: {"github_login":"dinwwwh"} -->
_Requested by **dinwwwh** · [project
thread](https://claude.ai/code/project/chan_01UcKMz91tMarPV1kWLVgLYE?thread=cmsg_01UcKMz91tMarPV1kWLVgLYE3WDrsammLg4kGEz5ZjzAjg)_
## What
#174 already turns a `$ref` into the bare `$ref` when two things hold:
only annotations sit beside it, and its target keeps a `discriminator`.
Without that, the `allOf` wrapper reads as a subtype in 3.0. That change
left a `type` sibling wrapped.
With this PR, a `type` beside the `$ref` that equals the target's own
`type` also counts. It restricts nothing the target doesn't already
restrict, so dropping it changes no value. Any other `type` stays
wrapped:
- a list such as `['object', 'null']` beside an `object` target, which
would reject null where the target allows it
- `string` beside an `object` target
- any `type` beside a target that is itself a `$ref` and so holds no
`type` of its own
The change is in `isTaggedRef` (it now takes the schema and checks its
keys). `convertSchema` calls it in place of `isAnnotatedRef(...) &&
isTaggedRef(...)`.
## Why
I found this on a recent SwaggerHub document, the NPP (National Parking
Platform) API 3.1.0:
```json
"EntranceOpenTime": { "title": "EntranceOpenTime", "description": "...", "type": "object", "x-package": "time", "$ref": "#/components/schemas/PeriodsOrValidity" }
```
Here `PeriodsOrValidity` is `type: "object"` with a `discriminator` on
`type` (`validity` / `periods`). On main, 3.0 gets `{ ..., type:
"object", allOf: [{ $ref: PeriodsOrValidity }] }`, which 3.0 reads as
one of the discriminator's subtypes. openapi-typescript 7.13 then types
the property as `{ type: "EntranceOpenTime" } & Omit<PeriodsOrValidity,
"type">`. That type rejects every real value. `ExitOpenTime` has the
same problem.
With this change, both become the bare `$ref`, and the
openapi-typescript diffs for these two properties go away. Round 855 of
the earlier hunt saw the same shape in OpenAI's `InputItem` branch `{
type: "object", title: "Item", description, $ref: Item }`.
## Checks
- **Output against main:** across 279 3.1/3.2 docs (225 recent
SwaggerHub docs, GitHub, Discord, Figma, OpenRouter and others, oRPC
corpora, FastAPI, Litestar, Huma, utoipa, Effect, Fastify, aide, Elysia,
swagger-core, ASP.NET Core 10, OAI fixtures), the 3.0 output changes
only in the NPP document, at those two components.
- **Values on NPP:** none of the 120,757 values the 3.1 schema accepts
is lost (Ajv 2020 on the input, draft-04 with `nullable` on the output),
and the 3.0 output is valid.
- **Tests:** the #174 test fails on main and passes here. The `typed`
case is now bare, and new `nullable`, `other` and `alias` cases stay
wrapped. 363 tests pass with 100% coverage, and `pnpm check` is clean.
- **README:** the `$ref`-with-siblings row now names the case.
---
_Generated by [Claude
Code](https://claude.ai/code/session_01VVaw7PbWyR4kZ18CjgHzqs)_
---------
Co-authored-by: Claude <noreply@anthropic.com>1 parent 06b5d00 commit 8a5abff
3 files changed
Lines changed: 31 additions & 7 deletions
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
201 | 201 | | |
202 | 202 | | |
203 | 203 | | |
204 | | - | |
| 204 | + | |
205 | 205 | | |
206 | 206 | | |
207 | 207 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
362 | 362 | | |
363 | 363 | | |
364 | 364 | | |
365 | | - | |
366 | | - | |
| 365 | + | |
| 366 | + | |
| 367 | + | |
| 368 | + | |
| 369 | + | |
| 370 | + | |
| 371 | + | |
367 | 372 | | |
368 | | - | |
| 373 | + | |
| 374 | + | |
| 375 | + | |
| 376 | + | |
| 377 | + | |
| 378 | + | |
| 379 | + | |
369 | 380 | | |
370 | 381 | | |
371 | 382 | | |
| |||
1529 | 1540 | | |
1530 | 1541 | | |
1531 | 1542 | | |
1532 | | - | |
| 1543 | + | |
1533 | 1544 | | |
1534 | 1545 | | |
1535 | 1546 | | |
| |||
| Original file line number | Diff line number | Diff line change | |
|---|---|---|---|
| |||
2258 | 2258 | | |
2259 | 2259 | | |
2260 | 2260 | | |
| 2261 | + | |
| 2262 | + | |
| 2263 | + | |
| 2264 | + | |
2261 | 2265 | | |
2262 | 2266 | | |
2263 | 2267 | | |
| |||
2270 | 2274 | | |
2271 | 2275 | | |
2272 | 2276 | | |
2273 | | - | |
| 2277 | + | |
| 2278 | + | |
| 2279 | + | |
| 2280 | + | |
| 2281 | + | |
| 2282 | + | |
2274 | 2283 | | |
2275 | 2284 | | |
2276 | 2285 | | |
| |||
2283 | 2292 | | |
2284 | 2293 | | |
2285 | 2294 | | |
2286 | | - | |
| 2295 | + | |
| 2296 | + | |
| 2297 | + | |
| 2298 | + | |
| 2299 | + | |
2287 | 2300 | | |
2288 | 2301 | | |
2289 | 2302 | | |
| |||
0 commit comments