[dinwwwh]

Requested by dinwwwh · project thread

What

Part of making the 3.1 → 3.0 downgrade only ever lose restrictions, never add them.

OAS 3.0 applies required to a readOnly property in responses only, and to a writeOnly one in requests only. In 3.1 (JSON Schema 2020-12) both are annotations, so required holds in both directions. The 3.0 output therefore accepts more than the input, but the converter did not count that as a lost restriction, so:

• not: { type: object, properties: { id: { readOnly: true } }, required: [id] } stayed a not, and the request {}, which 3.1 accepts, was rejected by 3.0.
• A oneOf told apart only by a tag one branch requires as readOnly stayed a oneOf. With A: { properties: { kind: { const: a } } } and B: { properties: { kind: { const: b, readOnly: true } }, required: [kind] }, the request {} matches only A in 3.1 but both in 3.0, so 3.0's oneOf rejected it.

The fix is kept minimal: finishSchema counts any readOnly or writeOnly schema as loose. The existing checks then carry that up to every object around it and every $ref to it, so no walk over required names is needed. tagsOf no longer treats a one-way required property as a tag that tells branches apart; that check reads through $refs, as 3.0 reads each target in its place.

README: one new row in the 3.1 → 3.0 schema table.

Tests

includes a readOnly or writeOnly schema covers the not case for both keywords, an optional property behind a two-$ref chain, a oneOf tagged only by readOnly tags (becomes anyOf), one tag required both ways (stays oneOf), and a $ref cycle in the tag check. pnpm check, pnpm test and coverage (100%) pass.

Tradeoffs

• Code generators. An object with any readOnly or writeOnly property now counts as loose, even when it does not require that property. That is more than the rule needs, but it keeps the logic to one line. A oneOf over such objects that is not told apart by type or by a tag required both ways now comes out as anyOf, which openapi-generator and others model as a different union type, and a not over one is dropped. Tagged unions whose tag is not readOnly stay oneOf.
• Speed. The check is two property reads per schema.

🤖 Generated with Claude Code

https://claude.ai/code/session_01VVaw7NmVyQoYtVBNPuE4uV

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[codspeed]

Merging this PR will degrade performance by 17.62%

2 warnings

⚠️ 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

⚠️ 1 benchmark with a significant change ran on different hardware

Its base and head results were measured on machines with a different CPU, core count or memory, so the change might not come from the code. Run base and head on the same runner type.

Learn more about Macro Runners

See affected benchmarks

❌ 1 regressed benchmark
✅ 28 untouched benchmarks
⏩ 2 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	BASE	HEAD	Efficiency
❌	order schema with $defs	1.2 ms	1.4 ms	-17.62%

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

---

_{Comparing claude/project-thread-h3q238 (9811aeb) with main (cb94ddf)}

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]

Approved. The change correctly detects objects whose required list names a readOnly/writeOnly property and marks them loose, so a not is dropped and a oneOf becomes anyOf when branches may overlap. isOneWay follows $ref chains with a cycle guard and only allocates a visited set when a $ref is present. tagsOf stops treating one-way required properties as branch-distinguishing tags. Tests cover both keywords, a two-$ref chain, a oneOf tagged only by readOnly, one tag required both ways, and an optional readOnly property; README updates match the behavior.

Non-blocking: isOneWay follows only $ref chains, not allOf members. A property whose readOnly/writeOnly sits in an allOf member while required sits on the parent won't mark the object loose. The code comment and README could make that $ref-only scope explicit, or a follow-up test could cover the allOf split case.

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

[dinwwwh]

On the non-blocking allOf note: this stays scoped to the property itself and its $ref chain. In 3.0 the "required one way only" rule belongs to the property's own readOnly/writeOnly, and a $ref stands in for its target, so those two count. A readOnly that sits only inside an allOf member is an annotation that 3.0 never says it collects, and reading it on every required property would add per-schema cost to a check CodSpeed already flagged. A readOnly written beside the allOf, which is how NestJS and the annotated $ref conversion write it, is on the property and is covered.

---

Generated by Claude Code

[pullfrog]

Blocking: the new isOneWay skips adding the first property to visited, so a self-referential $ref (P -> P) never reaches the cycle guard and loops forever. The previous version added the first node unconditionally and handled that case. The added cycle test covers a two-node cycle (Loop <-> Back) but not a self-cycle. Please add the first node to visited (or handle the self-cycle after the first resolve) and add a self-cycle test. The rest — the requiresOneWay split, the tagsOf filter, and the extra cycle test — looks good.

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

[pullfrog]

✅ No new issues found.

Reviewed changes — the delta since the prior pullfrog review (9962db1, which requested changes; the blocking cycle bug is now resolved).

• Rewrote isOneWay to add each node to its visited set before following that node's $ref, so a self-referential $ref (P -> P) terminates instead of looping forever. The prior blocking finding is fixed by structure, not by a special case.
• Replaced the old requiresOneWay(schema.required, schema.properties) scan with a direct rule in finishSchema: any readOnly or writeOnly schema is marked loose. The existing loosen/convertSchemaRef propagation carries that to enclosing objects (out.properties/out.allOf/out.anyOf values loose) and to every $ref, so no walk over required names is needed. This is a deliberate over-approximation, which only ever drops a not or widens a oneOf to anyOf.
• tagsOf now filters required names through isOneWay(properties[name]), so a tag that 3.0 honours in only one direction no longer tells oneOf branches apart, while a tag required both ways still does.
• Updated the 3.1 → 3.0 README row and its tests to the broadened rule, and reverted the now-inaccurate limitations note about readOnly around a cycle.

I verified the rewrite with a throwaway probe covering a self-$ref cycle and a mutual A <-> B cycle: both terminate in milliseconds (probe removed). pnpm vitest run packages/downgrader/tests/v3.1-to-v3.0.test.ts passes 130/130, and uncheck on the three changed files passes oxlint, oxfmt, and tsc.

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

[dinwwwh]

On the CodSpeed result for order schema with $defs: CodSpeed itself flags that this benchmark's base and head ran on different hardware. The bench schema has no readOnly or writeOnly, so the only new work on that path is two property reads per schema. Measured locally under callgrind with CodSpeed's V8 flags, one warmed conversion costs 1,356,928 instructions on main and 1,365,378 on this head (+0.6%).

---

Generated by Claude Code