Include a list of conformance classes somewhere?

[cportele]

The goal is to support both types of developers:

• those that have never heard about WFS - it should be possible to create a client using the OpenAPI definition (they may need to learn a little bit about geometry, etc., but it should not be required to read the WFS spec, for example);
• those that want to write a "generic" client that can access WFSs (and maybe WMSs, etc), i.e. are not specific for an specific API/server.

To make it simpler for the second group, should we include somewhere an array of requirements classes met by the server?

This could either be in the root resource or in some extension element in the OpenAPI document.
Here an example how this could be added to the root resource:

{
   "collections" : [ ... ],
   "conformsTo" : [ 
       "http://www.opengis.net/spec/wfs-1/3.0/req/core", 
       "http://www.opengis.net/spec/wfs-1/3.0/req/geojson" 
    ]
}

Those that do not care about WFS etc. could simply ignore that information.

[cportele]

Discussed during the meeting on 2017-11-28: Add this in a separate access path. This pattern could also be used for other information from the current capabilities that we want to expose. Ties in to the idea to use a hypermedia-based approach. Specify the link-relations to the additional resources.

[cmheazel]

I hate to stir things up, but have you considered the Tag object? These are OpenAPI objects which "can be used for logical grouping of operations by resources or any other qualifier." The OpenAPI object maintains a list of all tags used by that API and each Operation object (part of the Path) maintains a list of those tags applicable to that operation. Using tags would allow us to identify compliance classes at both the API and operation level.

[cportele]

@cmheazel The "problem" with using Tags for this purpose is that they group operations, but conformance/requirements classes do not fit. For example, a requirements class may just add an additional query parameter to an existing operation. And this is just one example. If every operation would belong to exactly one of those, then Tags would work.

Another (probably unwanted) side effect would be that operations are grouped by conformance class in HTML representations (at least in Swagger UI), but a publisher might prefer a different presentation. For example, in the sample OpenAPI/Swagger definition we have two tags: "Capabilities" for operations that describe "essential characteristics of this API including information about the data" and "Features" for operations that provide "access to data (features)".

[cportele]

Agreement on 2018-02-01: Keep the decision from 2017-11-28.

Use /api/conformance.