join fails on commonly referenced components

[uncaught]

Describe the bug

When referencing the same components, join fails with the error Conflict on components.

To Reproduce

1. Run:

git clone https://github.com/uncaught/redocly-join-conflicting-components.git
cd redocly-join-conflicting-components
npm install
./node_modules/.bin/redocly join ./RouteA.yml ./RouteB.yml --output=joined.yml

2. See error output:

Conflict on components => schemas : readonly in files: RouteA.yml,RouteB.yml
Please fix conflicts before running join.

Expected behavior

Common components should be reused correctly and not throw an error.

Redocly Version(s)

1.12.2

Node.js Version(s)

20.13.1

Additional context

See example at https://github.com/uncaught/redocly-join-conflicting-components

[tatomyr]

Hi @uncaught!
The issue is that Redocly CLI attempts to create a common components.schemas section in the joined description and it doesn't know what to do with the multiple schemas named readonly. You can easily work around that with the following command: redocly join RouteA.yml RouteB.yml --prefix-components-with-info-prop title (see the docs for more options).

BTW, I noticed you're using plain array notation here. In OAS v3.0.0 you should be using a Schema object instead. Did you forget using allOf?

[uncaught]

I know about the prefix-options. The issue is, that the referenced readonly component is the same and not some accidental conflict in naming. It's the same schema from the same file (BaseShape.yml). This should result in one item in the joined yaml, and not cause an error.

When using the prefix-option, it will add the referenced schema once for each reference. This can get out of hand real quick with some more levels of nesting, blowing up the joined file. (Of course the resulting schema is still technically the same.)

---

BTW, I noticed you're using plain array notation here. In OAS v3.0.0 you should be using a Schema object instead. Did you forget using allOf?

Yep, you are correct! I forgot that when creating the example repo. I've fixed that.

[tatomyr]

The issue is, that the referenced readonly component is the same and not some accidental conflict in naming. It's the same schema from the same file (BaseShape.yml).

Not exactly the same 🙂. There are 3 different readonly fields that conflict with each other: in ShapeA, in ShapeB, and in BaseShape. Actually, in the current configuration, the one from BaseShape is not even taken into account (since the schema object is incorrect). Once you name the different fields differently (I mean readonly's in SchemaA and SchemaB are different), join will resolve the common field without duplicating.

In other words, this is not a bug but a trade-off -- you either manually name different fields differently or the tool will try to rename them automatically (which could result in duplications).

[uncaught]

Sorry, I might have misinterpreted the error message!

So, without auto-prefixing, I have to prefix myself. With auto-prefixing, I get exponentially growing duplications.

Unfortunately, neither option is feasible for us.

Having to manually prefix each definition inside a file, which is by itself already in a namespace (the filename), sounds like a big code smell and prone to error. These schemas are supposed to be referrable anywhere, without any global knowledge on unique component names.

Thank you for your replies, I guess I will open a new feature request issue to get something more useful.