Model-based standard (OpenAPI)

[ronaldtse]

From @ogcscotts

For the OGC API family of standards, we are currently using OpenAPI to describe interfaces. In the Doc Team meeting I am going to propose that we get a little radical and make the primary publication fo the standard the OpenAPI definition plus a simple implementers guide and that guide is mostly driven by the OpenAPI definition. It would be great if the OpenAPI definition could also drive most of the normative portion of the more traditional publication format (OGC and ISO, we still need those). So in this case, OpenAPI is the model in a model-based standard.

This will rely on us to create an OpenAPI parser integration, e.g. mn-plugin-openapi that allows referring to OpenAPI specifications within Metanorma.

This relies on the framework to be implemented in metanorma/metanorma#125

[ronaldtse]

The https://github.com/Nexmo/oas_parser gem seems to be useful here.

[ghobona]

OGC Staff briefed on 2023-09-04.

[opoudjis]

Can parse the Markdown of OpenAPI into Asciidoc and vice versa via coradoc, if we extend coradoc.

OpenAPI (with Markdown) => OpenAPI (with Coradoc) =Lutaml (manipulating Asciidoctor)=> Metanorma, patterned after ISO-10303 approach

[ronaldtse]

The relevant task is

• Parse Markdown into Coradoc coradoc#11

[ghobona]

Discussed 2024-02-15

[ghobona]

@ronaldtse Any update on this issue?

[ghobona]

2024-07-08 Discussed with OGC Staff.

Note that several OGC API SWG implement OpenAPI 3.0 and are starting to explore 3.1. These two versions should be supported.

[ghobona]

2025-01-07

The various OGC API SWGs are planning to adopt the approach for OpenAPI 3.1 taken by the Features API SWG in the next version of OGC API - Features.