add templated property to links object

[tomkralidis]

Originating from opengeospatial/ogcapi-records#13, the following link schemas:

https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.yaml
https://github.com/opengeospatial/ogcapi-common/blob/master/core/openapi/schemas/link.json
https://github.com/opengeospatial/ogcapi-common/blob/master/collections/openapi/schemas/link.yaml
https://github.com/opengeospatial/ogcapi-common/blob/master/collections/openapi/schemas/link.json

Would benefit from having a templated boolean to be able to identify link objects having templated href values. We have articulated this in OGC API - Records, but it would be valuable to have this address upstream in OGC API - Common.

[joanma747]

This is a suggestion for maximum compatibility (this maintains the meaning href as a resolvable URL) while adding the template.

{
    "rel" : "item",
    "type" : "application/vnd.mapbox-vector-tile",
    "title" : "Mapbox vector tiles; the link is a URI template where {tileMatrix}/{tileRow}/{tileCol} is the tile based on the tiling scheme {tileMatrixSetId}",
    "href" : "https://services.interactive-instruments.de/t15/daraa/collections/TransportationGroundCrv/tiles/1/3/7?f=mvt",
    "template" : "https://services.interactive-instruments.de/t15/daraa/collections/TransportationGroundCrv/tiles/{tileMatrixSetId}/{tileMatrix}/{tileRow}/{tileCol}?f=mvt",
}

(json schema uses "uri-template": for the name of the format).
(This is consistent with what was done in OWS Context where there are no templates but jut examples of resolvable urls for WMTS links.)

[joanma747]

WE decided that we will take no action on this before going for public comments.

[ghobona]

Another issue that proposes extension of the Links object is opengeospatial/ogcapi-connected-systems#2

[ghobona]

Another issue that proposes extension of the Links object is opengeospatial/ogcapi-records#275

[ghobona]

This issue will be discussed at the 127th OGC Member Meeting in the Architecture DWG session on Tuesday 26th September 2023 at 1:30 PM SGT (Singapore time).

Register for the OGC Member Meeting at https://ogcmeet.org

[m-mohr]

As I raised this issue first in opengeospatial/ogcapi-records#275 but might not be able to join the meeting as it's 1:30am for me I want to explain my thoughts on this upfront:

Assumptions:

• If I understand Common, ch. 6.3 correctly, the href of a link must be a valid IRI/URI according to RFC 8288.
• A templated link with placeholders is not a valid IRI/URI according to RFC 8288. Instead it's a URI Template according to RFC 6570.

Status quo:

• OGC API - Common doesn't have a templated property
• OGC API - Features implements Common and doesn't implement a templated property.
• Other OGC APIs such as OGC API - Records seek for a way to express URI Templates.
• A templated property has been added to at least OGC API - EDR and OGC API - Tiles, which both (claim to properly) extend OGC API - Common
• Other specifications such as STAC, openEO (both may soon be a OGC community standards) implement OGC API - Common and OGC API - Features, STAC also seeks alignment with OGC API - Records

Issues identified:

• Adding a templated property that changes the definiton of an href is against the Liskov Substitution Principle. It states that "objects of a superclass should be replaceable with objects of its subclasses without breaking the application". The templated property "breaks the application" though as it allows the href to be templated.
  Example: A client that doesn't know the templated property creates an HTML page with <a href="..."> links for all links found. All links should be "clickable" and resolve. This does not work with URI Templates, the application is "broken".
• Adding a templated property to the links is strictly speaking a breaking change. That means OGC API - Common, OGC API - Features, STAC, openEO and others can't implement the templated property as defined in EDR / Tiles without going to 2.0 (SemVer). 2.0 is a rather big step and should be avoided in specifications (in my opinion). To keep in the 1.x version range, these standards would need to adopt a different templating strategy than EDR / Tiles. This is obviously also not ideal. Maybe exceptions can be made, not sure.

Potential solutions:

• Adopt templated and ignore that it's breaking (with all negative consequences downstream, e.g. decrease of trust regarding stability)
• Deprecate templated in EDR / Tiles and find a way that extends Common properly (e.g. see the related issues for proposals, e.g. in Tiles)
• Diverge in OGC APIs (i.e. Tiles/EDR use what they have, Features/Records use something else)
• ...?

Remark:
The templated links are a relatively minor thing and the effect on implementations may be low. Maybe exceptions can be made and the templated property will get pushed through all specs (including not-yet OGC specs). The main point here is the general handling of extensibility. OGC should make sure that OGC APIs have a broader dicuscussion about central concepts and ensure that implementing specs extend Common and other specifications in a "valid" way, following the Liskov Substitution Principle. I think the templated links are not the only thing where this occured in the past / will occur in the future, e.g. the itemType in Features was also just barely rescued.

[jbants]

2.0 is a rather big step and should be avoided in specifications (in my opinion).

It may not decrease trust. I like it when specs get updated to fix gaps. We've had to support clients on WMS 1.1 and WMS 1.3, and it's annoying. The x and y coordinates changed positions, which was a breaking geospatial change.

We are building downstream applications and community standards around OGCAPI-common, and these specs and standards are ideally loaded through inheritance. Any spec users should know it as OGCAPI-Common and not OGCAPI-Common Vx.x.x. I lean more toward Geo than Computer Science, but I prefer parent documents following best practices and ideas from computer science.

If I had to choose a solution, It would be something like deprecating existing templated solutions in EDR / Tiles and finding a way that extends Common properly.

[ghobona]

Agreement in Singapore is to arrange a dedicated telecon during the month of October.

All SWGs are requested to document their proposed solution options in this GitHub Issue before October 15th.

[m-mohr]

@ghobona Do you announce the meeting date/time here?

[ghobona]

Here is the Doodle poll.

Please find below a link to a Doodle poll for scheduling a discussion on templated links.
https://doodle.com/meeting/participate/id/epzwRgVb
Please enter your availability by 09:00 AM EDT this Thursday 12th October .

[nmtoken]

The x and y coordinates changed positions, which was a breaking geospatial change.

They didn't change positions.

WMS 1.1.1 ~ attributes minx, miny, maxx, maxy indicate the edges of the bounding box in units of the specified SRS

WMS 1.3.0 ~ The value of the BBOX parameter in a GetMap request is a list of comma-separated real
numbers (see 6.5) in the form "minx,miny,maxx,maxy". These values specify the minimum X, minimum Y,
maximum X, and maximum Y values of a region in the Layer CRS of the request. The units, ordering and direction
of increment of the x and y axes are as defined by the Layer CRS

the definition of x and y was clarified/corrected.

[ghobona]

The telecon will be on Thursday 19th October at 10:00 AM EDT.

The Gotomeeting details are on the OGC Portal here.

[jerstlouis]

@ghobona Is the decision from the meeting documented somewhere?

Would be good to document it here, and in opengeospatial/ogcapi-features#844 , and the other repos.

From what I overheard, it seems that the decision is my least favorite option.

Unfortunately, as indicated in the doodle poll, I was not able to attend at that time due to a conflict with Styles & Symbology SWG meeting.

[ghobona]

As it was an Architecture DWG meeting, the resolution had to be forwarded to the OGC Architecture Board (OAB) for an OGC-wide policy/directive. So the meeting passed a Motion that recommends that the OAB makes an OGC-wide policy/directive for all SWGs developing OGC API Standards to keep link objects as they are and to create a new object for link templates.

The Motion and the recording are in this folder https://portal.ogc.org/index.php?m=projects&a=view&project_id=131&tab=2&artifact_id=106433

The action to arrange an OAB discussion on the topic is with the OAB Chair.

[jerstlouis]

@ghobona @cportele @pvretano Are there any documented update on the decision of how to define these linkTemplates?

OGC API - Records has defined it as such:

https://github.com/opengeospatial/ogcapi-records/blob/master/core/openapi/schemas/linkTemplate.yaml

where the template goes into a uriTemplate property.

Is that the agreed upon schema which everyone should now follow?

In OGC API - DGGS right now we have tref in the YAML and href in the example.

Should we change all that to uriTemplate? Thanks!

[cportele]

@jerstlouis - I think we agreed on uriTemplate as part of the discussion, but I am not sure where/if this has been captured. uriTemplate is also what is also used in Features:

https://github.com/opengeospatial/ogcapi-features/blob/master/core/openapi/schemas/linkTemplate.yaml

[jerstlouis]

Thanks for the clarification @cportele .
It is now captured in this issue at least! :)

Made the change in OGC API - DGGS:

opengeospatial/ogcapi-discrete-global-grid-systems@d4fe87e

and in our implementation.

[ghobona]

A Motion was passed in the Architecture DWG telecon on 19 October 2023. Please see the recording (at 42:00 minutes) referenced by #187 (comment)

[jerstlouis]

@ghobona the motion does not specify the details of what exactly that link template object consists of.

"based on the draft Link-Template header" does not imply a particular schema for a JSON object.

Perhaps we can clarify here that the Records schema will become the Common link template object.

[gbuehler]

From the OAB Issue, there was a follow on motion:

Move to draft policy post in OGC Guidance, once published return to approve as policy
Motion: Chris
Second: Michael
Discussion: Who will write it? Peter will help write the policy and bring to OAB with Records review.
NOTUC: motion passes

@pvretano Do you have wording we can use for the overall policy?