Manifest file for multiple overlays

[lornajane]

It is common to have multiple Overlays that can be applied, and order matters both within an Overlay document and between them. It would be useful to have a standard format to describe which Overlays should be used and in what order, that could be understood by tools that support Overlays. It would also allow more flexible Overlay design with more atomic, reusable Overlays which can be composed in different ways for different use cases.

[baywet]

Thanks for creating this issue!

I'll share our scenarios to help shape this feature.

In our OpenAPI description ingestion to TypeSpec process, we have multiple Overlay documents we apply. Some of them are sequential, some of them are alternative

1. OpenAPI description
2. Overlay for the really broken things
3. Overlay for the list operation (applies extensions)
4. Overlay for the "regular consumers" or Overlay for the "code generation consumers"

We split that into multiple overlay documents to help with management/review/edit processes. So we wouldn't be using a solution that requires all the documents to be merged together somehow.
We also anticipate more overlay documents will be created over time since we might find additional aspects that are self-contained, and/or have different set of consumer audiences.
In the end, our consumers use the TypeSpec definitions, so they never see the OpenAPI descriptions or the Overlay documents. However, just for our own management/scripting steps it'd be nice to have manifests to capture nicely the different groups, add some context, and ensure the sequence is properly followed.

Let me know if you have any additional comments or questions. I'm happy to expand on any specific aspect.

[lornajane]

Adding a note that there's some prior art here: https://darrelmiller.github.io/api-manifest/draft-miller-api-manifest.html and I think the API catalog formats (RFC9727 and apisjson in particular) are also relevant