Consider suggesting a file-naming convention for overlay documents

[earth2marsh]

I wonder if it might be worth suggesting a convention for naming Overlay documents. It could help improve discoverability and consistency, especially in scenarios where the main OpenAPI document (e.g., openapi.yaml) is present.

Currently, an Overlay that augments an OpenAPI document (such as a translation or service-level agreement) might be named in ways that don’t immediately suggest its connection to the OpenAPI document. For example, you might see fr.yaml or it.yaml for translations, or sla.yaml for a service-level agreement. Looking at the files in a directory, you might spot an openapi.yaml document (a common name for an OpenAPI file) and not realize there are related Overlay documents!

One pattern to consider is prepending any overlay document with "overlay," such as:

• overlay.fr.yaml
• overlay.it.yaml
• overlay.sla.yaml

This approach would group overlays visually when listed in alphabetical order. Since it begins with ov, it would likely appear near openapi.yaml, making the connection between the main document and its overlays more obvious.

Recommending a convention like this would make it clearer that a document is an OpenAPI Overlay when viewing a list of files.

[mfbx9da4]

Yeah this would be nice to have consensus. I was thinking more

my-company.openapi.yaml
fr-translation.openapi-overlay.yaml