[Architecture board] Clarify location of spec artifacts

[OndroMih]

Some MP specs support non-Java artifacts like properties files inside an application. However, there are differences in how they define where the artifacts are expected.

For example, MP Config specifies locations for artifacts in META-INF folder on the classpath (there may be more folder like that on the classpath and all are considered)

Another example, MP OpenAPI allows artifacts to be in the application archive (JAR, WAR, etc.) in root/META-INF, which for WARs isn't on the classpath. After discussion in eclipse/microprofile-open-api#221, MP Config artifacts are also supported in root/META-INF if used with MP OpenAPI, see eclipse/microprofile-open-api#226. On the other hand, MP OpenAPI artifacts in META-INF on classpath aren't supported.

[OndroMih]

MP OpenAPI team came to a consensus that supporting artifacts in root/META-INF is the best option. Here is the only valid argument I found for this: @arthurdm here

On the other hand, many people from outside of MP OpenAPI, including MP committers, think that the best option is to expect files in META-INF folder on the classpath. Here are some arguments for this: @OndrejM here, @arjantijms here, @Emily-Jiang here and @rmannibucau here

[EricWittmann]

I'd like to add a bit of clarity to this issue, as I found the original description unclear. I believe that this issue is referring to multiple different files located in the application artifact. These files are:

1. MP Config properties file microprofile-config.properties
2. openapi.(yaml|yml|json) file which is a static OpenAPI spec document

The section of the MP+OpenAPI specification can be found here:

https://github.com/eclipse/microprofile-open-api/blob/master/spec/src/main/asciidoc/microprofile-openapi-spec.adoc#421-location-and-formats

This section indicates that file (2) above must be located here:

/META-INF/

It does not allow file (2) to be located in /WEB-INF/classes/META-INF.

Additionally, the same section in the spec includes this text:

For convenience, you may also place your microprofile-config.properties in the root META-INF folder, if you wish to keep both documents in the same directory. This is in addition to the default locations defined by MicroProfile Config.

So to summarize, the spec says this about the two files in question:

1. microprofile-config.properties can be located in /META-INF/ (regardless of the application artifact type) OR /WEB-INF/classes/META-INF (only when the application artifact is a WAR)
2. openapi.yaml must be located in /META-INF/ regardless of the application artifact type

So I think the decision that we need to reach is whether this is OK or whether these artifacts must be on the classpath (which would prohibit them from being located in /META-INF/ when the app artifact is a WAR).

I hope that adds some clarity to this issue. :)

[kenfinnigan]

In the Architecture meeting this week it was agreed that any non Java properties and files should be accessible on the classpath irrespective of the archive type.

https://wiki.eclipse.org/MicroProfile/ArchGuidelines has been updated with the new guidelines.

We did, however, agree that the OpenAPI spec could continue to retain the old /META-INF location in the root as a backward compatible option to prevent requiring a 2.x release just for this change