Update OpenAPI schema to version 3.1

[m-burgoyne]

OpenAPI schema 3.1 is fully aligned with JSON Schema, upgrading the OGC-EDR API to use OpenAPI schema 3.1 will remove the errors that occur when importing 3rd party data schemas that are based on the JSON Schema standard.

There would be one breaking change as OpenAPI schema 3.1 no longer supports nullable (JSON Schema allows for arrays of types which is much more flexible), this would require changes to the extent.yaml definition. Although not a required change the migration docs also recommend changing example values to examples arrays

[chris-little]

WE need to have some cross-API discussion.

[chris-little]

@tomkralidis pointed to differences of OpenAPI V3.0 and V3.1 at https://blog.stoplight.io/difference-between-open-v2-v3-v31

[ghobona]

SWG session on 2022-06-30

Action: @ghobona to look into arranging a special Cross-SWG session at the 124th OGC Member Meeting (October 3rd to 7th).

[cportele]

The Features API SWG already has a task in its charter for an OpenAPI 3.1 requirements class since 2019, but we have not done any actual work yet, because so far there is almost no uptake of v3.1 in the tooling ecosystem (see https://openapi.tools/). As long as that is the case, the value of supporting v3.1 in implementations - or the standards - seems limited.

[dblodgett-usgs]

Not much more discussion here -- SWG session 2022-08-11 decided to close till more SWGs decide to take this on.

[havardf]

Would it be possible to reopen this issue in the near future? We at MET Norway (https://www.met.no/) would very much like to proceed with OpenAPI 3.1 for our EDR services.

Also, it seems like a lot of tools have moved on to 3.1 in the last few months.

[chris-little]

@havardf Thank you for the update on the OpenAPI3.1 ecosystem. The decision to support Open API 3.1 will probably be across all of the OGC APIs. Or at least: Common, Features, EDR, and Records. I suspect that this will not be quick - meaning that 2025 is more likely than 2024.
What did you mean by "near future"? Did you mean within the life of the RODEO project?
I could raise it as an Issue at the OGC Architecture Board to re-start the required cross-OGC discussion.
And what features of 3.1 do you consider important?

[havardf]

Good question! There is no specific single feature we require, although the json schema compatibility would be an advantage.

We are currently building up a set of tools to support the development of EDR services at MET Norway, and we initially wanted to build them with OpenAPI 3.1 as a starting point. Having said that, 3.1 is not critical for this work, and we can migrate to that version at a later stage as well.

I think we will then plan for this migration to happen in 2025-2026. If there are new information on the timeline later, any update on this would also be much appreciated!

[chris-little]

@ghobona @cportele I thought you might like to see this discussion by API-EDR developers.

[cportele]

@chris-little

I saw this. OGC API Features has OpenAPI 3.1 support already as a task in its charter since its last charter update, but so far not worked on this task since other activities have been considered more important.

Any OGC Web API can already support OpenAPI 3.1 today. One does not need to have a standard for this (and writing a requirements class for OpenAPI 3.1 will be pretty simple and straightforward). So, if OpenAPI 3.1 is important for an API, the API provider can support it (either in addition to OpenAPI 3.0 or instead of OpenAPI 3.0). There is no need to wait for an OGC activity.

[havardf]

Thank you for that clarification @cportele!