Resolve inconsistent OAS version references in available review materials

[Sam-Bolling]

This public comment is respectfully submitted by the Web Service Technical Panel (WSTP) of the Defence Geospatial Information Working Group (DGIWG). This comment addresses an identified issue where the version of OpenAPI Specification is inconsistent throughout the materials provided for review:
• From the bundled zip folder linked in the public announcement
o 21-001r0 makes 8 references to OpenAPI Specification 3.0. Five times in code fragments throughout the document and twice in test case descriptions
o 21-002r0 makes 7 references to OpenAPI Specification 3.0. Six times in code fragments throughout the document and once in a github link in Annex B
• From the OGC API – Connected Systems GitHub repository linked in the public announcement
o Openapi-connectedsystems-1.yaml references openapi 3.1.0
o Openapi-connectedsystems-2.yaml references openapi 3.1.0

Request: For the purposes of reviewing, please clarify which version of OpenAPI Specification is considered correct.

[alexrobin]

Discussed during 10/31 Telecon.

The group decided to favor support for OpenAPI 3.1 given that tooling is now available for this version and OGC API Features is also planning on adding a requirements class for it.

We can still have a normative dependency on OGC API Features, but not refer to Req Class 9: "OpenAPI 3.0".

We can provide the OpenAPI 3.0 bundle generated by @avillar in appendix for users that require it. This appendix will also explain why this decision was made (reference on-going work in OGC API - Features, tooling, etc.).

[fterpstra]

I would be very carefull in adopting 3.1 over 3.0 as 3.1 is not backward compatible with 3.0 and should probably have been labeled 4.0. In practice tooling support of 3.1 even after several years of existance is lacking. This means code generation based on OAS 3.1 spec will be much harder making implementations harder. The main advantage of 3.1 is full support of JSON schema. look at https://tools.openapis.org/ for current tooling support for 3.1 and 3.0

[alexrobin]

Discussed during 12/12 Telecon.

We will provide both OpenAPI 3.0 and 3.1 bundles.
The spec will mention that both versions are provided although conformance for 3.1 is still at draft stage (inherited from OGC API Features).

Ok to write OpenAPI snippets in the spec using version 3.1.

@ghobona