Compatibility with OGC API - Common - Part 1: Core

[cportele]

The OGC API Common SWG is planning to move the current draft of Part 1 (Core) to OAB/public review soon. Since the general idea is that future revisions of OGC API Features would normatively reference that document, we should check, if any incompatibilities exist, that would prohibit this - and discuss the way forward, if necessary.

I have opened this issue so that we can collect potential problems and discuss them.

[cportele]

I did a review of the requirements in the current draft. I found two issues; maybe there are more, but these are the two that I found so far:

• The title element is required on the landing page in Common, but it is not required in Features.
  • A reminder why we have not made the title mandatory in Features: Making that element mandatory will not result in useful API titles and titles are not necessary for interoperability. I can still assign some cryptic string as a title, just to conform to the spec, and this will be as good as no title in many cases. And it does not break anything, the API mechanics will still work with no title or a cryptic title.
• The link relation types conformance, data and items have been converted to URIs, e.g. http://www.opengis.net/def/rel/ogc/1.0/conformance.
  • This is the result of Link relation types in OGC API standards ogcapi-common#76.

If we would simply update Features Core in a revision to align with Common Core (if it stays this way), we would make existing implementation non-compliant, which I do not consider an option. I see two ways forward:

1. Features Core will not add a normative dependency to Common Core. This may not be as bad as it sounds. We can add text about this and point out that implementations that also meet the additional Common Core requirements (title on landing page and links with both link relation types, the URI and the non-URI variant) can also add the Common Core conformance classes to the conformance declaration.
2. Common Core also supports the Features Core requirements, but
   a. deprecates the link relation types conformance, data and items;
   b. changes title from required to recommended.

Any other ideas? @cmheazel?

[cportele]

I think I have found another one: Common Core now seems to require that query parameters with numeric values accept INF, -INF and NaN as numeric literals.

Features does not require this - and I don't think that it should. These special values may be valid in XML, but they are not valid in JSON, for example, and the OpenAPI type for every numeric parameter would be a union of a number and a string with three enums. I hope this is not something we will have to worry about eventually, but that this can be changed in Common Core. I will add a comment in Common.

Update 2021-01-25: It was clarified in the Common SWG call that the requirement is not a requirement to support the three literals. It provides a guidance how to encode the values, if needed. Since we don't need this in Features, this is not applicable and a non-issue for Features.

[cportele]

An update:

• title is no longer required, so the only breaking change is the requirement to use http://www.opengis.net/def/rel/ogc/1.0/conformance instead of just conformance.
• I am still concerned about "importing" requirements like the requirements in the section Parameter Encoding. To me these requirements are more for OGC API building blocks (which would be a different standardization target than "Web API"), but we should not require that every API that implements Features uses, for example, inf for infinite everywhere in the API, in particular for query parameters that have nothing to do with OGC API building blocks.

My proposal for supporting Common Part 1 in a future revision of Features Part 1 would be to add an additional req/conf class for Common Part 1. Implementations that support all Common Core requirements (the updated link relation type, other API requirements) in addition to the Features Core requirements could declare this through that additional conformance class.