Organizing building blocks by type first?

[jerstlouis]

I feel it would make things a lot easier to maintain if we used as top-level subdirectories the following list:

• apiSpec (inside could be sub-directory for each part, and inside could be each conformance class)
• paths
• responses
• schemas
• queryParameters
• requestHeaders
• responseHeaders

This should make it easier to import and synchronize the different building blocks from existing specs which already use several of these directories, e.g.:

• https://github.com/opengeospatial/ogcapi-common/tree/master/core/openapi
• https://github.com/opengeospatial/ogcapi-common/tree/master/collections/openapi
• https://github.com/opengeospatial/ogcapi-features/tree/master/core/openapi
• https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/crs/openapi
• https://github.com/opengeospatial/ogcapi-features/tree/master/extensions/transactions/create-replace-update-delete/openapi
• https://github.com/opengeospatial/ogcapi-coverages/tree/master/standard/openapi
• https://github.com/opengeospatial/ogcapi-maps/tree/master/openapi
• https://github.com/opengeospatial/ogcapi-tiles/tree/master/openapi
• https://github.com/opengeospatial/ogcapi-discrete-global-grid-systems/tree/master/openapi
• https://github.com/opengeospatial/ogcapi-environmental-data-retrieval/tree/master/standard/openapi
• https://github.com/opengeospatial/ogcapi-processes/tree/master/core/openapi

Entries in the registry should probably be in a machine-readable form like JSON rather than ASCIIDoc (to implement organization / filtering by type etc.), including all the properties needed to efficiently support the building blocks registry.
e.g., following properties could be included:

• title
• description
• maturity
• isGeoSpatial
• originatingSpec
• schema / definition
• ...

[jerstlouis]

@doublebyte1 @rob-metalinkage @ghobona

I believe it should be possible to almost fully automate building this registry of building blocks (or at the very least the foundation for it) by pulling the information out of the various OpenAPI definitions programmatically. The end result would also be much more usable as a backend to a queryable table of building blocks than a bunch of static ASCIIDoc files.
Most building blocks would be used by other building blocks, and by other specifications, so all of these relationships could be discovered and presented and queried.

[doublebyte1]

Thanks for your comment @jerstlouis !
You mean getting rid of the top level hierarchy?

                 common
      geo <
                features

      ogc-utils

So instead of having these on the folder structure, they would be encoded in the "IsGeospatial" category?

[doublebyte1]

This is the current schema for the building blocks (in JSON). I think it contains the properties you are suggesting?

[jerstlouis]

@doublebyte1

You mean getting rid of the top level hierarchy?

Yes, but also having that specific top-level organization that I am suggesting.

A relational database might be a more suitable storage mechanism than a GitHub repository for the building blocks though, so that the data can easily be presented organized in different ways.

[doublebyte1]

@cportele what do you think of this reorganisation? did you have a strong motivation to have the top level hierarchy with geo, ogc-utils and unstable, or you think that distinction could be moved to an attribute?

[chris-little]

@doublebyte1 I am not averse to @jerstlouis 's suggestion, but I found it easier to add the EDR building blocks by creating an EDR folder, alongside the Common and Feature folders. That might help with provenance or authority if considered important.
I have no idea whether GitHub could support separate views. I am sure the registry infrastructure could.

[jerstlouis]

@chris-little @doublebyte1 With a database / relational model, the API specification owning the building block (common, features, edr, tiles...), and the re-usable building block type (schema, query parameter, response, request header, response header, resource path...) would be two fields, so we could have it both ways :)

I think being able to query by building block type first is better for discovering already existing building blocks of a paticular type, and for maintaining consistency across the OGC API specifications.

[cportele]

• In my view, the separation between "geo" and "ogc-utils" is essential and should be the top level. OGC should promote the "geo" building blocks for reuse by others that want to spatially enable their APIs. The "ogc-utils" building blocks are "just" needed to make OGC API standards work, but are not something that OGC should promote as a general API good practice. If the HTTP API WG or OAI or another standards body for Web APIs in general develops a standard for one of those aspects and we see good adoption, we should consider those for use in the OGC API standards to stay aligned with the rest of the web.

• Building blocks should be easy to author and should be easy to read/understand, but clear specification fragments. Like we do not write our standards in JSON, I also do not see that this is how we should write the building blocks. I agree that elements that occur in every building block should be structured so that the OGC definition server can make it searchable, but we could use AsciiDoc document variables for this (like in our standards).

[chris-little]

This is a 'straw man' proposed structure for building blocks from @robatkinson:

• link to specification
• description
• metadata about governance
• link to github container
• model (UML)
• model (OWL, or at least a formal and stable mapping of concepts to URIs)
• JSON schema
• JSON-LD context
• validator
• examples
• link to further guidance
  @doublebyte1 I have structured the parameter-name building block as above, plus maturity, in my PR#3. Only thing not done is producing UML or OWL definitions. What do you think?

[doublebyte1]

• In my view, the separation between "geo" and "ogc-utils" is essential and should be the top level. OGC should promote the "geo" building blocks for reuse by others that want to spatially enable their APIs. The "ogc-utils" building blocks are "just" needed to make OGC API standards work, but are not something that OGC should promote as a general API good practice. If the HTTP API WG or OAI or another standards body for Web APIs in general develops a standard for one of those aspects and we see good adoption, we should consider those for use in the OGC API standards to stay aligned with the rest of the web.
• Building blocks should be easy to author and should be easy to read/understand, but clear specification fragments. Like we do not write our standards in JSON, I also do not see that this is how we should write the building blocks. I agree that elements that occur in every building block should be structured so that the OGC definition server can make it searchable, but we could use AsciiDoc document variables for this (like in our standards).

I agree @cportele , but what about "unstable"? isn't that already captured in the "maturity" property?

[doublebyte1]

I refactored the register, based on feedback:

https://blocks.ogc.org/register.html

(there is also a shortcut, in the top menu from https://blocks.ogc.org/)

To do this, I added another property, "type", which captures what we have in the folder structure: "geo", "ogc-utils".

The edr and coverage blocks from @chris-little were included - thank you for the contribution!

I also added a couple of issues discussing various things - I really welcome your feedback!

[chris-little]

@doublebyte1 Now that I have seen the re-factored register (looks good!), perhaps parameter-name(s) should be in geo-utils. Is that something that you could do easily, or should I do it?

Also, on the register page, how about giving each of the filter properties a definition in a mouse-over?

[rob-metalinkage]

This looks great now, but as we develop more building blocks and have more schema and query parameter equivalent forms, and more specialisations (like we see with Extent, bbox, bounding box, bbox-crs) already we may need to include the common conceptual models as a grouping and filtering mechanism, as well as the type of building block. We can play with this after loading into a knowledge graph and annotating - then push the ideas that work back into the point of truth registry once we have tested these facets and found the right level of granularity of typing.

[doublebyte1]

@doublebyte1 Now that I have seen the re-factored register (looks good!), perhaps parameter-name(s) should be in geo-utils. Is that something that you could do easily, or should I do it?

Also, on the register page, how about giving each of the filter properties a definition in a mouse-over?

@chris-little Good idea 👍🏽

[jerstlouis]

@doublebyte1 The improved building blocks register page is a thousand times better, thank you.

My organization/structure-hungry brain still finds it difficult to find things in https://blocks.ogc.org/register.html .
This will become particularly problematic as I expect there will be 10x or even 100x more building blocks than there currently are on this page as we register more OGC API building blocks.

The tags can possibly help with this, but all tags are currently presented as a flat single list. I imagine most tags are enumeration value for a particular thing.
e.g., domain:geo, domain:ogc-utils; status:valid, status:proposal, status:mature; ogc-api:features, ogc-api:edr.
GitLab premium has these "scoped labels" (the ones that look like medicine pills) for these things. Using something like this would help a lot i think.

I still think a single block per row presentation, with the first column being the name, second column description, and additional columns reflecting each of these scoped labels categories, and the tags within them, and the ability to sort and filter by the value of these tag categories, with a default sort, would make it much easier to discover building blocks of interest, and see the big picture of what building blocks exist. Right now the building blocks appear to be listed in a random order.

I don't know if the intention is to remain at this level of granularity (which is either very high level or only includes a small selection of the APIs building blocks), but I was thinking every path, response, parameter, schema and requirements class of OGC API could/would be registered as a building block, with several of them shared between multiple APIs (e.g., all of those from OGC API - Common). That is the first and most important tag scope that I would include: type:path, type:response, type:parameter, type:schema, type:reqClass.