Open tomkralidis opened 3 years ago
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.)
WE decided that we will take no action on this before going for public comments.
Another issue that proposes extension of the Links object is https://github.com/opengeospatial/connected-systems/issues/2
Another issue that proposes extension of the Links object is https://github.com/opengeospatial/ogcapi-records/issues/275
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
As I raised this issue first in https://github.com/opengeospatial/ogcapi-records/issues/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:
Status quo:
templated
propertytemplated
property.templated
property has been added to at least OGC API - EDR and OGC API - Tiles, which both (claim to properly) extend OGC API - CommonIssues identified:
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".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:
templated
and ignore that it's breaking (with all negative consequences downstream, e.g. decrease of trust regarding stability)templated
in EDR / Tiles and find a way that extends Common properly (e.g. see the related issues for proposals, e.g. in Tiles)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.
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.
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.
@ghobona Do you announce the meeting date/time here?
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 .
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.
The telecon will be on Thursday 19th October at 10:00 AM EDT.
The Gotomeeting details are on the OGC Portal here.
@ghobona Is the decision from the meeting documented somewhere?
Would be good to document it here, and in https://github.com/opengeospatial/ogcapi-features/issues/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.
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.
@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!
@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
Thanks for the clarification @cportele . It is now captured in this issue at least! :)
Made the change in OGC API - DGGS:
and in our implementation.
A Motion was passed in the Architecture DWG telecon on 19 October 2023. Please see the recording (at 42:00 minutes) referenced by https://github.com/opengeospatial/ogcapi-common/issues/187#issuecomment-1801307536
@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.
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?
Originating from https://github.com/opengeospatial/ogcapi-records/issues/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 templatedhref
values. We have articulated this in OGC API - Records, but it would be valuable to have this address upstream in OGC API - Common.