[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.