Sprint Goal #1 Feedback about using the OGC API - Connected Systems Parts 1& 2 YAML files

[Sam-Bolling]

CSAPI Sprint Goal #1 for OGC Code Sprint 26:
Confirm that the OpenAPI bundle definition YAML files for OGC CSAPI Parts 1 & 2 work as intended and can be used to autogenerate useful code without issues

Please post here any and all feedback you have relating to the CSAPI parts 1 & 2 yaml files. Opinions, testimonials, experiences, complaints, concerns, issues, challenges, recommendations and ideas of all kinds are welcome.

[EricLo-417]

The redoc examples seem complete and working. However, when I tried to download the openAPI yaml file for code generation I ran into some problems.

• The linked yaml file in redoc does not work without downloading other files. Not nearly as simple as OGC Features Part 1-3's one bundled file
• I downloaded from the link schema registry: https://schemas.opengis.net/ogcapi/connected-systems/
  • Noticed that these references files outside of connected-systems so i downloaded even more files, the whole registry: http://schemas.opengis.net/SCHEMAS_OPENGIS_NET.zip
  • This is where the first problem started. schemas/sensormlDefs is looking for sensorml but the folder at the root is called "sensorML"
  • Then it appears sensorML/common (root from the whole registry) is missing some files (instantForNow and instantForPeriod)
• After trying to fiddle with everything I noticed that the github contains different openAPI files and those appear to work. Ran into one duplicate issue but nothing broke.

Overall, It seems there is some disconnect between github and schemas.opengis. I assume the GitHub version is the most up to date and maybe the files should be consolidated into one place and ideally have bundle provided (much easier for quick viewing and for code generation as you only need to add one file not a whole file structure)

[SpeckiJ]

ideally have bundle provided

we have a bundles available, but we are currently pretty bad at marketing those. They are automatically build when a new tag is pushed to the repo and then released here: https://github.com/opengeospatial/ogcapi-connected-systems/releases/

I have just pushed a new tag based on the current master, so the bundles should regenerate right now.

TODO: we whould probably link to them more prominently than in old (now closed) issues. (opengeospatial/ogcapi-connected-systems#137)

[SpeckiJ]

This is where the first problem started. schemas/sensormlDefs is looking for sensorml but the folder at the root is called "sensorML"

This is a general issue with the repository structure, there are so many relative imports mixed with absolute ones, mixed with local ones, mixed with ones from "bundler" classes that sometimes get optimized out by tools that it gets really complicated.

This causes huge troubles as can be seen here: https://github.com/52North/connected-systems-pygeoapi/blob/3a20a04d932aa3e2b00dfcb8bf09093e5bfc89e8/tools/bundler/bundler.js#L64

[Sam-Bolling]

Follow-up: bundled OpenAPI files now exist, but the developer path to them remains unclear

I did some follow-up research after this discussion and found that the repository already contains prior work addressing part of the problem raised here.

Two earlier issues requested self-contained OpenAPI bundle files because the modular YAML entry files rely on numerous relative $ref dependencies and are difficult for common code-generation and automation tools to consume directly:

• [#78 — Make bundle file available to reviewers for CSAPI Part 1](Make bundle file available to reviewers for CSAPI Part 1 opengeospatial/ogcapi-connected-systems#78)
• [#79 — Make bundle file available to reviewers for CSAPI Part 2](Make bundle file available to reviewers for CSAPI Part 2 opengeospatial/ogcapi-connected-systems#79)

A later issue established automated bundle generation:

• [#137 — Add GitHub workflow for bundle generation](Add GitHub workflow for bundle generation opengeospatial/ogcapi-connected-systems#137)

As a result, the published v1.0.0 release now includes bundled OpenAPI 3.1 files for both parts:

• [Part 1 bundled OpenAPI 3.1 YAML](https://github.com/opengeospatial/ogcapi-connected-systems/releases/download/v1.0.0/ogcapi-connectedsystems-1.bundled.oas31.yaml)
• [Part 2 bundled OpenAPI 3.1 YAML](https://github.com/opengeospatial/ogcapi-connected-systems/releases/download/v1.0.0/ogcapi-connectedsystems-2.bundled.oas31.yaml)
• [OGC API – Connected Systems v1.0.0 release](https://github.com/opengeospatial/ogcapi-connected-systems/releases/tag/v1.0.0)

This means the remaining problem is no longer primarily that the bundle files do not exist. The remaining problem is that developers arriving through the official [OGC API – Connected Systems web page](https://ogcapi.ogc.org/connectedsystems/) are not clearly directed to them.

The official web page currently presents one ReDoc link for Part 1 and one for Part 2 under Developer-friendly OpenAPI definitions. Those ReDoc views load the modular OpenAPI entry files rather than the published bundled artifacts:

• [Part 1 modular OpenAPI entry file](https://schemas.opengis.net/ogcapi/connected-systems/part1/1.0/openapi/openapi-connectedsystems-1.yaml)
• [Part 2 modular OpenAPI entry file](https://schemas.opengis.net/ogcapi/connected-systems/part2/1.0/openapi/openapi-connectedsystems-2.yaml)
• [Official Connected Systems schema repository](https://schemas.opengis.net/ogcapi/connected-systems/)

The modular files are appropriate for specification maintenance and component reuse, but the entry files depend on additional paths, parameters, requests, responses, schemas, and related resources. A developer who downloads only the YAML associated with the current ReDoc view may therefore receive an entry file rather than a complete, readily consumable API definition.

This creates an avoidable gap between:

1. the files presented as the developer-friendly OpenAPI definitions; and
2. the bundled files most suitable for validation, client generation, server-stub generation, and other OpenAPI tooling.

I opened a follow-on issue proposing that the existing two ReDoc views use the corresponding bundled OpenAPI 3.1 files and provide a visible download action for the exact files being displayed:

• [#186 — Use bundled OpenAPI 3.1 files for Part 1 and Part 2 ReDoc views](Use bundled OpenAPI 3.1 files for Part 1 and Part 2 ReDoc views opengeospatial/ogcapi-connected-systems#186)

The intent is not to add more links or complexity to the [OGC API – Connected Systems web page](https://ogcapi.ogc.org/connectedsystems/). The recommendation is to preserve its existing simple Part 1 and Part 2 presentation while making the two ReDoc views the clear developer gateway:

• Human users can browse the API through ReDoc.
• Developers can download the exact bundled OpenAPI definition being displayed.
• Code-generation and validation tools do not need to reconstruct the modular dependency tree.
• The modular schema repository remains available for maintainers and advanced reuse.
• The ReDoc display and the recommended downloadable implementation artifact remain aligned.

In summary, [#78](opengeospatial/ogcapi-connected-systems#78), [#79](opengeospatial/ogcapi-connected-systems#79), and [#137](opengeospatial/ogcapi-connected-systems#137) successfully addressed bundle creation and automated generation. The new [#186](opengeospatial/ogcapi-connected-systems#186) addresses the remaining bundle discoverability, access, and developer-experience problem.