feat(api-gen): enhance schema merging

[mdanilowicz]

Prevents conflicts when merging overrides that use composition keywords. In OpenAPI, an object cannot have both $ref and composition keywords, so this removes $ref when composition is present.

closes: #2125

Schema patching improvements

• Added logic to patchJsonSchema.ts to remove $ref from schema objects when an override uses composition keywords (oneOf, anyOf, allOf, not), preventing conflicts and ensuring correct schema merging. [1] [2]

Code consistency and formatting

• Updated function signatures and method calls throughout patchJsonSchema.ts for consistency, such as removing trailing commas and ensuring uniform argument formatting. [1] [2] [3] [4] [5] [6] [7]
• Minor formatting changes to log messages for clarity and consistency in output. [1] [2]

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Preview	Updated (UTC)
frontends-demo	Ready	Preview	Nov 21, 2025 1:53pm
frontends-vue-starter-template	Error		Nov 21, 2025 1:53pm
shopware-frontends-docs	Ready	Preview	Nov 21, 2025 1:53pm

[codspeed-hq]

CodSpeed Performance Report

Merging #2126 will create unknown performance changes

_{Comparing feat/GH-2125 (7ca42bf) with main (61a60a0)¹}

Summary

⚠️ No benchmarks were detected in both the base of the PR and the PR.
Please ensure that your benchmarks are correctly instrumented with CodSpeed.

Check out the benchmarks creation guide

⏩ 8 skipped²

Footnotes

1. No successful run was found on main (2439238) during the generation of this report, so 61a60a0 was used instead as the comparison base. There might be some changes unrelated to this pull request in this report. ↩

2. 8 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. ↩

[patzick]

Nice addition, currently during override you should specify _DELETE_ value in $ref for the same effect. What if it's the other way around and you want to have $ref instead of composition key?

One thing is that it's missing test scenarios for it so than it would make it also properly documented and easier to understand

[patzick]

probably that would not trigger linter error

Suggested change

	// biome-ignore lint/performance/noDelete: delete $ref
	delete obj.$ref;
	delete obj["$ref"];

[mdanilowicz]

this will trigger lint/complexity/useLiteralKeys

[patzick]

what's the difference here? from previous condition? I'd love to see test scenarios for it

[mkucmus]

the condition is really hard to get through, please maybe move some parts to the helper funcion to be used later on, maybe event the whole condition - then we can write an additional unit test 😍 for that?

  const compositionKeywords = ["oneOf", "anyOf", "allOf", "not"];
  const hasCompositionKeyword = (val: unknown): boolean => {
    if (typeof val !== "object" || val === null || Array.isArray(val)) {
      return false;
    }
    return compositionKeywords.some((keyword) => keyword in val);
  };

[mkucmus]

then:

Suggested change

	if (
	typeof key === "string" &&
	compositionKeywords.includes(key) &&
	typeof obj === "object" &&
	obj !== null &&
	"$ref" in obj
	) {
	if (
	typeof obj === "object" &&
	obj !== null &&
	"$ref" in obj &&
	hasCompositionKeyword(value)
	) {