Allow authors to define the merge order and precedence

[earth2marsh]

What if instead of overlays, you could define the merge rules like layers in Photoshop (a kind of makefile, if you will)? This might be an optional manifest or layers in the info object, and it defines the tasks to be executed. A fully resolved document would remove those instructions for a self-contained document.

[handrews]

This is a merge over the entire document? I did not keep up with the overlays discussion, why are we back to merges?

[earth2marsh]

It's really just the stub of an idea. The key bit is that different people might be responsible for different aspects of a description document. One approach we haven't considered AFAIK is to consider this a layering challenge where you define the layer order. You could similarly "merge down" to have an expressed artifact like a self-contained and resolved description doc.

[handrews]

I could see that working if you're controlling the merging through some sort of external manifest, etc. The problems I saw when people tried to use a $merge with JSON Schema had to do with runtime interactions of $merge and $ref. When you have two different things that both need lazy evaluation, it gets complicated very fast.

[darrelmiller]

Discussed in TDC call on Oct 27th.

• If we want to help people manage multi-file should this manifest be an external file? e.g. like a project file for OpenAPI stuff
• Also this conversation relates to the ongoing conversation hosted by JSON Schema about generalized referencing https://github.com/json-schema-org/referencing
• Can moonwalk solve merging problems so that there is less need for complex multi-file combinations?

[darrelmiller]

Discussed again in TDC call on Dec 12th.

• There is a common need expressed for being able to combine APIs from different internal teams into a single OpenAPI description
• Can a tree structure be used to help combine files to produce a single API structure?
• What should tags be used for? Should they just be used to mirror the path? Should we encourage the community to use them in the way tags are more commonly used instead of the way SwaggerUI uses them for grouping operations.
• Do we need another way of attaching metadata that is distinct from tags?

[darrelmiller]

To date the community has found workarounds for dealing with multi-file solutions. There is no clear obvious wins in this space that a specification change could help with.
If community tooling coalesces around some solution to dealing merging of files in a way where specification changes could help, we will revisit this topic.

[MikeRalphson]

As mentioned last week, some existing tooling, though none seem to have a great deal of traction.

Repo	Stars	Documents merge strategy	Notes
https://github.com/robertmassaioli/openapi-merge	75	No?
https://github.com/Typeform/openapi-micro-merge	9	No?	OAS 2.0 only
https://github.com/kpramesh2212/openapi-merger-plugin	12	Partially
https://github.com/marcelthole/openapi-merge	11	No?
https://github.com/kota65535/openapi-merger	16	Partially - adds $include keyword
https://github.com/networknt/openapi-bundler	7	Minimally, doesn't discuss conflicts
https://github.com/iouring-engineering/openapi-merge	18	Minimally, doesn't discuss conflicts