search

opengeospatial / ogcapi-common

OGC API - Common provides those elements shared by most or all of the OGC API standards to ensure consistency across the family.
https://ogcapi.ogc.org/common
Other
45 stars 14 forks source link

Don't make it a standard #222

Closed jyutzler closed 3 years ago

jyutzler commented 3 years ago

I request that the following opinion be submitted along with a Request for Public Comment for any part of OAPI-Common.

I believe that adoption of OGC-API-Common as a standard will cause problems without creating benefits for the community.

When cases inevitably occur that requirements from OAPI-Common conflict with adopted standards, forcing breaking changes, it puts the SWGs in an impossible situation. First, the timelines for standards updates are disconnected and unpredictable. It could be many years before a downstream standard is revised to conform to OAPI-Common and OAPI-Common itself could be revised again in the interim. Second, breaking changes are extremely problematic for many implementers of adopted standards. They are often not in a position to update their implementations to conform and deploy those implementations into the field, at least not in a timely manner.

Meanwhile, organizations that manage a standards registry like the US Department of Defense's DoD Information Technology Systems Registry (DISR) will not know what to do with OAPI-Common if it becomes a standard. To such an organization, the purpose of standards is to enable proper governance. Since OAPI-Common has no implementation (and it is not intended to apply to every web-based API), conformance to it cannot be verified. Conformance can only be verified in the context of some other standard. Since OAPI-Common proposals already conflict with OAPI-Features, it is not possible to be conformant to both. To them, a standard would add no value and would only cause confusion.

I believe it would be better for the community for OAPI-Common to remain guidance that SWGs can drag and drop into their respective emerging standards as they see fit.

jerstlouis commented 3 years ago

@jyutzler Maybe it's a different class of OGC specifications, that can only be indirectly, not directly conformed to?

cportele commented 3 years ago

@jyutzler - I share the general concern. From a Features perspective and looking at Part 1 only I think there should be ways to handle the small incompatibilities between Features Part 1 and Common Part 1 without breaking changes, but I will also review the draft again during the public review and provide comments, if needed. But the general issue will remain at least as long as Common does not just reuse building blocks, but changes/amends them.

For what it's worth, I have proposed to manage Common as a building block registry and not make it a standard like the rest of the OGC API series, but that did not get much support at the time. This was during the collection discussions about a year ago (link):

Which may be part of the problem with Common, since it is not meant to be implemented and used by itself. I am starting to think that maybe we should change the way how Common is developed and managed. Perhaps Common should not be a standard, but more a registry of building blocks for reuse (within OGC, but also by other API designers) and we would only add building blocks to the "Common registry" once we have more than one OGC resource type using a building block. Make Common something that is really built bottom-up, with time and as concepts prove to be valuable in the real-world, instead of the top-down design process that I currently see.

jerstlouis commented 3 years ago

@cportele While I support the buildings blocks registry approach, my concern is that a building block defined by one group may not take into consideration during its elaboration (and even up to standardization) the input from the different groups for which that building block would make a lot of sense to be harmonized and be part of Common.

Even with a long period for comments, other groups may not have as much incentive to carefully review and consider the implications for their use cases, as if it were something developed in Common with the understanding from the start that this will have a direct impact on their specifications, and with a centralized place where to look for these new Common building blocks under development.

My hope was that Common provides this forum to develop these building blocks flexible enough to support most groups' use cases. I realize it is very difficult to get everybody to agree on something, but I think we have made a lot of good progress? :)

ghobona commented 3 years ago

Regarding Conformance testing...

Many of the Abstract Tests specified in OGC API - Common are implementable by modifying some of the tests already implemented in the OGC API - Features executable test suite.

Regarding document type...

If the SWG decides to change the document type, there is the option of turning the document into an Abstract Specification.

If I recall correctly, DGGS 1.0 was initially developed as an Implementation Standard but was changed to an Abstract Specification at the OAB stage.

ogcscotts commented 3 years ago

Given that the OGC APIs are constructed of building blocks and these blocks have some degree of independence in how they can be implemented, the entire structure of "what is a Standard" is challenged. We can say that each of the resource-based Standards are "conveniences" because they accomplish a certain objective as a collection of building blocks. That still makes sense from a procurement and compliance standpoint. But maybe we need a new formal guidance document type that has the weight of a normative document, but which is continuously updated by consensus of the affected SWGs (in effect, a dynamic Abstract Spec).

cportele commented 3 years ago

+1 to managing a normative registry of API building blocks and calling this OGC API Common. However, I consider the API building blocks as implementation artefacts (specifications of resource schemas, resource representations, operations on resources, query parameters, headers, etc. with associated requirements, recommendations and permissions). That is, they can be used directly in OGC API standards or any HTTP/Web API. They are closely coupled with HTTP, etc. Is this on the Abstract Spec level?

rob-metalinkage commented 3 years ago

Why can't this be handled by specifying the conformance target of ogc common classes to be implementing API specs? This seems to match the intent with no additional gymnastics involved.

cmheazel commented 3 years ago

We already have standards, such as OWS-Common and the SWE Service Model, which are only implemented through inclusion in other standards. API-Common in not unique. It should not be treated as a special case.

cmheazel commented 3 years ago

API-Common is already structured as a collection of building blocks. There are some issues to discuss: 1) what is the granularity of the building blocks? 2) how do we scope the building blocks? 3) how do we minimize dependencies between building blocks? 4) how do we avoid an unmanageable proliferation of conformance classes?

These issues have occupied the SWG for most of the past year. It doesn't matter how you package it. If you don't solve these issues you will not have usable standards.

cmheazel commented 3 years ago

The conformance target for an OGC Web API is the Conformance Class, not the standard. A conformance class is a building block. An OGC Web API Standard is a collection of conformance classes brought together to provide a specific functionality. A standard reuses conformance classes by importing them from other standards (see API-Coverages and API-Records).

Note: There are a lot of standards in the DISR which are only implemented through other standards. This is a flaw in the way the DISR has been managed, not in the standards themselves. There has been some progress in fixing this.

jyutzler commented 3 years ago

@cmheazel Where the conformance targets are does not change the natural tendency for standards to diverge since their timelines are not synchronized. The real question is how the community benefits from OGC adopting this thing as a standard. I have yet to see a satisfactory answer to this question.

cmheazel commented 3 years ago

@jyutzler Conformance Classes are identified by a URI which includes the version of the standard within which they are defined. A change to API-Common will not impact a derivative standard until that SWG chooses to update their standard.

jyutzler commented 3 years ago

That is exactly my point. I'm still waiting for someone to explain who benefits from an action that by definition has no impact.

ghobona commented 3 years ago

@jyutzler I think what @cmheazel meant was that the Conformance Classes in a standard are distinguishable from those in future (or past) versions of the standard by the version number indicated in the URIs of the Conformance Class. See Clause 3.2 of the OGC-NA Name type specification - specification elements (10-103) policy.

jyutzler commented 3 years ago

So?

ghobona commented 3 years ago

So, conformance classes of a derivate standard can reference specific conformance classes in the base standard or elsewhere.

To date, the 10+ OGC API approved and draft specifications share common ways of advertising landing pages, conformance declarations, API definitions, etc. This is a major benefit to the community because developers do not need to implement 10 different ways of invoking similar operations or parsing similar documents. This is a major credit to OGC API - Common, and the patterns first set out by OGC API - Features - Part 1: Core and OGC API - Processes - Part 1: Core.

jerstlouis commented 3 years ago

@ghobona and let's not forget Part 2 which I feel is even more relevant to clients and server code-reuse ;) Features, Coverages, Maps, Tiles, EDR all re-use /collections and /collections/{collectionId} resources, and you can point most clients (including the new unified GDAL OGC API driver) directly to such a collection. The fact that a single GDAL driver can handle 4 different APIs is also a major achievement of Common. Workflows allows to reference one or more of these collections as an input to a process or a chain of processes, which offers a lot more flexibility than a hardcoded href URL (fixed to a particular request).

The value of Common is defining these common building blocks to be re-used and to be the same, as much as the timeline allows.

The exact details of what type of standard Common should be I think should be guided by considerations for publication, CITE and procurement.

But I strongly believe we need something much more concrete than "guidance for the SWGs" to be able to achieve the aforementioned possibilities and interoperability between the different OGC API standards, and so far Part 1 & Part 2 are working great judging by how many APIs are already using them successfully.

jyutzler commented 3 years ago

But I strongly believe we need something much more concrete than "guidance for the SWGs" to be able to achieve the aforementioned possibilities and interoperability between the different OGC API standards

Why? We've already achieved that interoperability without adopting Common as a standard. The process is already working fine.

No one is arguing against the value of Common itself. My problem is with the administrative overhead of the standardization process which is just more work for people who are already over-extended.

I'm still waiting for someone to articulate the value of adopting Common as an OGC standard.

jerstlouis commented 3 years ago

@jyutzler Well I understand "guidance for the SWGs" as something like the OGC API Web Guidelines that were just approved, which are intentionally kept vague and flexible.

Whereas Common Part 1 & Part 2 are well-defined schemas and HTTP operations, with requirements that can be tested, and when you implement those on either a client or a server, you have maybe already implemented 30-50% of Features, Coverages, Maps, Tiles and EDR. And it means that adding support for an additional OGC API in your implementation is much less work. It also means that things feel much better integrated for the end-user.

If you are saying that we can still have those well-defined schemas and HTTP operations that are re-used but we don't need to call them a standard, I am more in agreement, but I would think that still qualifies as a standard (or internal specifications at least), just of a different kind.

cmheazel commented 3 years ago

4/26/21: Homework for the SWG - provide implementable ideas on how a building-block approach to Common would work. How do you do conformance testing? How do you manage the proliferation of building blocks? How does an API advertise to a client which building blocks have been implemented? How do you keep that advertisement to a reasonable size and complexity?

jyutzler commented 3 years ago

I believe this can be done in a straight-forward manner.

cmheazel commented 3 years ago

This topic was discussed at the June 2021 Open OAB meeting. A general approach was agreed upon with OGC Staff to develop policy and API-Common SWG to develop a proof of concept. Common Part 2 is that proof of concept. Common Part 1 is compatible with Part 2 and the general approach.