OpenAPI documents and normative statements

[cportele]

In another issue (#1), a discussion started about normative OpenAPI documents or normative elements in an OpenAPI document. Since this is out-of-scope of the other issue, I have created a new topic.

Beyond WFS, it might be worth seeking broader guidance (from the OAB perhaps?) as to whether API descriptions can be used at all to contain any normative constraints.

I would prefer that we come to a conclusion first of what we think works best and then discuss with the OAB, if they see any concerns.

But the answer to this question wouldn't stand in the way of continuing on the current WFS course (since you're currently just using it as a source of examples).

Yes, but some parts of the OpenAPI definition of a WFS implementation will be based upon normative statements. See https://github.com/opengeospatial/WFS_FES/blob/master/core/standard/clause_5_conventions.adoc#references-to-openapi-components-in-normative-statements.

The idea behind the general approach in the current draft is that it should be possible to implement a single API (i.e. have a single OpenAPI definition) that conforms to, for example, WFS, WMS and WMTS at the same time (and using the same segmentation of layers/feature collections). There are very likely still elements in the current draft that do not yet fit this idea, but it is on my list to review the normative statements, and the general text, from that perspective.

In other words, the idea is not to define standalone services, but more to define "building blocks" for an API that supports spatial aspects. This is closely related to the idea of the OGC essentials. In that sense the use of "service" in the names of our standards which implies that a WFS instance and a WMS instance are separate services would no longer be true.

[nmtoken]

Does the use of "service" in the interface standard name really imply that that a WMS instance and a WFS instance must be separate services?

[cportele]

No. In the current standards a WMS 1.3 and a WFS 2.0 implementation will always be separate services, but the idea is that it should be possible to have an API/service instance described by a single OpenAPI definition that conforms to WFS 3.0 and other revisions of OGC web service standards that follow the same approach.

See also the OGC White Paper on APIs.

[cportele]

Discussed during the meeting on 2017-11-28: Document the idea / approach in the document (WFS and other OGC web services, not specifically WMS).