[Mattias-Sehlstedt]

PR #23361 introduced so that a description is kept when normalizing oneOf/anyOf schemas that only have a single "meaningful" alternative. This lead to the shape

Shape:
  description: A shape to draw.
  oneOf:
    - $ref: "#/components/schemas/Circle"

becoming

Shape:
  description: A shape to draw.
  $ref: "#/components/schemas/Circle"

rather than the

Shape:
  $ref: "#/components/schemas/Circle"

it became before.

This in turn changes how the alias logic handles it, because it now is considered a composite schema rather than an alias. This means that Shape is kept rather than dropped.

This is an unintentional change in behavior, since the scope was mainly aimed at oneOf/anyOf in the case of being a nullable wrapper.

This is by no means a final and correct behavior, since the issue is much broader and tied to the separation between sibling management and de-aliasing being unclear. It is most likely a subject that has to be handled further, but this PR at least removes the unintended behavior while keeping what was requested and implemented in the previous PR that changed the behavior.

It would be helpful if @timonrieger could elaborate on for what the scenario is where they want to retain the description so one could better reason about whether the normalization rules should increase their granularity.

Fixes #25467

PR checklist

• Read the contribution guidelines.
• Run the following to build the project and update samples:

  ./mvnw clean package || exit
  ./bin/generate-samples.sh ./bin/configs/*.yaml || exit
  ./bin/utils/export_docs_generators.sh || exit
  

  (For Windows users, please run the script in WSL)
  Commit all changed files.
  This is important, as CI jobs will verify all generator outputs of your HEAD commit as it would merge with master.
  These must match the expectations made by your contribution.
  You may regenerate an individual generator by passing the relevant config(s) as an argument to the script, for example ./bin/generate-samples.sh bin/configs/java*.
  IMPORTANT: Do NOT purge/delete any folders/files (e.g. tests) when regenerating the samples as manually written tests may be removed.
• If your PR is targeting a particular programming language, @mention the technical committee members, so they are more likely to review the pull request.

---

Summary by cubic

Restores the pre-#23361 behavior where a oneOf/anyOf schema with a single non-null $ref alternative drops the parent description during normalization. PR #23361 kept the description in that case, which turned the collapsed $ref into a composite schema with sibling metadata and prevented the alias from being removed, so schemas like Shape were kept instead of dropped.

The parent description is now transferred only when a null subtype was removed or the collapsed child is inline, keeping nullable-wrapper descriptions intact. Fixes #25467.

^{Written for commit bd225bc. Summary will update on new commits.}

[cubic-dev-ai]

All reported issues were addressed across 4 files

<sub>Reply with feedback, questions, or to request a fix.

View guided diff | Re-trigger cubic</sub>

[timonrieger]

It would be helpful if @timonrieger could elaborate on for what the scenario is where they want to retain the description so one could better reason about whether the normalization rules should increase their granularity.

iirc, i understood my PR as a correctness fix since descriptions should make it into the client for documentation purposes.

[Mattias-Sehlstedt]

If the fix wasn’t targeted at any specific generator behavior, it may be worth considering a revert. If there’s no concrete behavior to preserve with this change, the original adjustment could be seen as unnecessary.

I also believe sibling handling is generally expected to use allOf when we want generators to recognize it (as introduced in #22364). In that context, moving the description currently doesn’t seem to be recognized correctly, because $ref normalization happens before oneOf/anyOf normalization.

That said, I’ll leave it to the maintainers to decide whether reverting this small adjustment is the best path forward.

[timonrieger]

If the fix wasn’t targeted at any specific generator behavior, it may be worth considering a revert. If there’s no concrete behavior to preserve with this change, the original adjustment could be seen as unnecessary.

ah yes, I made it to fix the python generator for my downstream project.
To follow up: I double-checked, #23361 has no effect on my project. I'm fine with narrowing it as done here or reverting #23361 entirely if that's cleaner given the alias regression in #25467

[wing328]

Shape:
  description: A shape to draw.
  oneOf:
    - $ref: "#/components/schemas/Circle"

Just a second thought. Should we auto fix it by converting it to allOf instead as follows?

Shape:
  description: A shape to draw.
  allOf:
    - $ref: "#/components/schemas/Circle"

My guess is that the intention to reuse the schema (Circle in this case) via allOf but incorrectly using oneOf instead.

[Mattias-Sehlstedt]

I believe auto-fixing it might also cause some regressions with regards to what people expected the "default behavior" to be. I think it would be easier to implement fixes if we also support them with concrete use cases for the stubs, so that we can capture and document the intended result. I.e., someone would showcase where they would expect the description to show up and why.