[dinwwwh]

Requested by dinwwwh · project thread

Docs only, no code change.

Since #174 (and #150 for branches beside a discriminator), a $ref with only annotations beside it to a schema whose discriminator stays becomes the bare $ref in 3.0. The annotations go with it, and that set includes readOnly, writeOnly, default and deprecated, so those are lost too:

{ "$ref": "#/components/schemas/KeyDataV2", "description": "...", "readOnly": true }

now becomes { "$ref": "#/components/schemas/KeyDataV2" }. In the Cryptography Provider v2 API that makes openapi-typescript drop readonly on ExportKeyResponseV2Dto.keyData, and Kiota gives it a public setter.

This is rare. Across a corpus of 19,775 real docs, #174 changes 1,553 sites, and only 3 of them carry one of these keywords (1 readOnly, 2 deprecated). oRPC never writes a discriminator, so its output never hits this path. A README note fits better than keeping the allOf wrapper at those few sites.

The $ref with siblings row now ends with: "In both cases the annotations beside the $ref are dropped, so a readOnly, writeOnly, default or deprecated there is lost, as for the readOnly the Cryptography Provider API writes beside one."

---

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-srml6g (f6598d6) with main (ab98262)}

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

• Bare-$ref annotation loss noted — appends to the A [$ref][js-ref] with siblings row of packages/downgrader/README.md: in both bare-$ref rewrites (a oneOf/anyOf branch beside a surviving discriminator, and a $ref with only annotations to a schema whose discriminator stays), the annotations beside the $ref are dropped, so a readOnly, writeOnly, default or deprecated there is lost. Cites the Cryptography Provider API's readOnly as the example.

The claim matches the code: convertTaggedBranch → convertSchemaRef and convertSchema's isAnnotatedRef + isTaggedRef path both emit a bare { $ref }, and ANNOTATION_KEYWORDS in v3.1-to-v3.0.ts contains default, deprecated, readOnly, and writeOnly. The behavior is pinned by the tests keeps a $ref beside only annotations bare in a union beside a discriminator and keeps a $ref beside only annotations bare to a schema with a discriminator (packages/downgrader/tests/v3.1-to-v3.0.test.ts:1885, :1936), and uncheck passes on the README.

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