Moving to open api spec 3.1

[alamers]

Related to #214, the question pops up whether or not to move our spec to OpenAPi 3.1.

Two main questions on this topic:

• Does this impact (runtime) backwards compatibility? (expectation: no)
• What is our policy on following the OpenApi spec? What can our partners expect with regards to maintaining a stable tool stack?

[ahokkonen]

Things to review for migration: https://www.openapis.org/blog/2021/02/16/migrating-from-openapi-3-0-to-3-1-0

Also to notice - currently not all generators supports OAS3.1 so the migration should be considered carefully.

[alamers]

As discussed in the meeting today, investigating will continue but we don't expect 3.1 to be used for the next version. Version 3.0 will be the openapi spec to use for now.

[cookeac]

The group members at a meeting on 23 Sep 2021 discussed a move to support OpenAPI 3.1
(release announcement here: https://www.openapis.org/blog/2021/02/18/openapi-specification-3-1-released)

Our policy will be to move to newer versions providing that there is tool chain support from the commonly used toolchains by implementers across the wider ICAR group.

At present we cannot move as we await open-api generator support for OpenAPI spec 3.1. In turn this depends on when swagger-parser Supports OAS 3.1.

[cookeac]

Discussed this with reference to #409 which would require OAS3.1
OAS3.1 is now fully supported by open-api generator and other tooling. It better supports the elements of JSON Schema, and better supports documentation and examples.

Recommended a move to support OAS 3.1 within the timeline of ADE 1.4, subject to checking the way that code generation, particularly of the change from nullable to a [null] type option, is handled in C# and Java.
@AlexeyHardCode and @AndreasSchultzGEA we hope you could test this with just one or two files in your code generation.

[cookeac]

Noted also that use of GeoJSON's geometry type in #430 would also require OpenAPI 3.1 as it uses a $schema and $id specification that is not supported in OpenAPI 3.0.