Separation of templated and untemplated links ...

[pvretano]

There is an issue of mixing templated and regular links in the same links section. Clients unaware of templaing will ignore the templated information and try to resolve the href with variables which will fail. This suggests that it might be worth considering splitting out the templated links from regular links.

This issue is cross-cutting and was motivated by a similar issue in Records.

See here: opengeospatial/ogcapi-records#275 for a discussion on the issue in Record.

See also: opengeospatial/ogcapi-features#844

[jerstlouis]

This would be a severe breaking change for Tiles that will break existing client implementations like GDAL.

I am much, much more concerned about clients aware of the particular standard in use that does understand the "templated" : true and expects a templated link using particular variables and to find it alongside the other links in the links property, than a generic clients trying to follow a templated URL.

I really am not keen on the idea of this change.

It also means tons of software changes on both client and server implementations.
Trying to handle the links in both locations: huge mess.

I vote NO on this change.

[m-mohr]

The current implementation was a mistake as the way Commons was extended is not valid (Liskov substitution principle).
Repeating this mistake over and over again in the other specs would really scratch OGCs image, I think.
It would for example lead to a derivation in downstream specifications such as openEO and STAC (and I'd argue also Features), these specs would need a 2.0 if templated gets added as it's a breaking change. Both openEO and STAC are to be submitted as OGC community standards, too.

As such a soft change could be implemented:

• Deprecate the existing behavior in Tiles (but still allow it to not break things)
• Add the linkTemplates as recommended way to expose link templates and adopt it throughout all specs.

This way you can softly fade out the "mistake", you don't need a breaking change.

I vote YES!

[jerstlouis]

The current implementation was a mistake as the way Commons was extended is not valid (Liskov substitution principle).

I wouldn't go as far as saying not valid, but you are most likely right that is breaks the Liskov substitution principle (though that might be debatable... depending on whether we argue that a templated link is in fact a link).

This way you can softly fade out the "mistake", you don't need a breaking change.

For Tiles, it really is a breaking change.

A new revision of the Standard would need to be released with Requirement 8 E and G moved to a permission or a recommendation.

It would also affect the 2DTMS schemas:

https://schemas.opengis.net/tms/2.0/json/link.json

Then all OGC API - Tiles clients, most of which do rely on that requirement, will break on implementations that do conform to the new revision but do not implement the recommendation or permission.
This would require an OGC API - Tiles 2.0, I don't see any any way around it.

We had no intent to release a version 2.0 at any point in time, let alone such a short time after the release of 1.0.

The implications of this breaking change far outweight any negative impact of breaking the Liskov substitution principle in this case.

In the case of Features at least, there was no use of a templated link at any point.
So adding new links that extend the Link object with a templated : true -- I do not believe that requires a version 2.0 bump in that case.

Not sure about STAC and openEO. But for Tiles, moving the lnk to templatedLinks is most definitely a breaking 2.0 change.

[m-mohr]

I described above how it can be implemented as a non-breaking change. The old way is still allowed (but discouraged), the new way is added and recommended. This doesn't need a 2.0 and is not breaking.

On the other hand, all other specifications that add templated and did not had it before need a 2.0 because any client that expects a dereferencable link, may not get one afterwards. That IS breaking!

[jerstlouis]

@m-mohr I described above how that is breaking, unless I misunderstand the concept of a breaking change.

If something becomes "optional" for a server, and a client relies on that now "optional" thing, these clients break for servers that do not implement that option.

On the other hand, if templated is only added to "new" links that existing clients previously did not need, adding "new" links which are templated should not cause any major problem. It might fail to dereference the new links if it curiously tries to do so, but the links it previously relied on will keep on working.

For Tiles, the clients will simply no longer find the link to the tiles if the link is moved to "templatedLinks". The client will completely stop working with those servers that follow this change without implementing the backward compatibility option with version 1. There is no way this change is not a breaking 2.0 change.

[m-mohr]

It does NOT get optional, I just said "deprecated". You still provide templated links as before, but also add them to linkTemplates. Nothing breaks. It's a bit annoying for some time, but better one spec is a bit annoying compared to multiple standards that need a 2.0 (Commons, Features, openEO, STAC, ...).

On the other hand, if templated is only added to "new" links that existing clients previously did not need, adding "new" links which are templated should not cause any major problem.

Unless you read all links, e.g. render a HTML page with tags, which don't understand templated links. Breaking change.

[jerstlouis]

It does NOT get optional, I just said "deprecated". You still provide templated links as before, but also add them to linkTemplates.

Deprecating a requirement while keeping the requirement seems somewhat contradictory.

Potentially a 1.1 revision could add a requirement to add the links at this new place, while preserving the requirement 8 E and G up until a 2.0 change. I don't think "deprecated" would be the proper way to qualify this though.

e.g. render a HTML page with tags, which don't understand templated links. Breaking change.

It would still need to deal with the templated links from Tiles implementations as long as Tile is at version 1.x.
But if the problem is with the HTML output, that seems a separate issue than the presence of the link in the JSON "links" property?

[m-mohr]

Potentially a 1.1 revision could add a requirement to add the links at this new place, while preserving the requirement 8 E and G up until a 2.0 change.

Great, I'm supporting it.

Deprecating a requirement while keeping the requirement seems somewhat contradictory. [...] I don't think "deprecated" would be the proper way to qualify this though.

Why? Deprecated just means "to be removed in the next major version (i.e. 2.0), please migrate to the alternative behavior".

It would still need to deal with the templated links from Tiles implementations as long as Tile is at version 1.x.

Yes, that's the status quo which we can't solve, but at least it would not mandate the mistake to all other specs.

But if the problem is with the HTML output, that seems a separate issue than the presence of the link in the JSON "links" property?

No, HTML was just an example.

[jerstlouis]

In summary:

• We don't have any immediate plan for a Tiles 2.0 where we could change the behavior and remove the templated property
• We don't have any immediate plan for even a Tiles 1.1 where we could potentially add a requirement for an additional "new way" where the link is found in the templateLinks instead (assuming the other SWG decide to go this way). Unlikely we would release a new minor revision only for this change that requires more work to conform.
• If the other SWGs decide to go with this templatedLinks approach, Tiles could make the change if / when a new minor or major revision happens.

My own preference would still be to stick to the current "templated" boolean and staying inside links, and I would hope there is a way to make these clients deal with templated links inside "links" realizing that they are templates with {variables}, hopefully not suffering any major breakage.

If the change is really necessary, then those other specs will move to templatedLinks, but Tiles will only be able to follow completely at a 2.0 release, which hopefully will never be necessary.

[jerstlouis]

I would also like to point out that EDR is another published OGC standard that also uses "templated": true , while also adding a whole bunch of things to the Link object, which appears primarily when used with a singular "link" property (which I personally find a lot more problematic, the variables in particular, which are not the template variables, but rather a whole bunch of details about the query, which I think would really have fit better "outside" the link object):

https://docs.ogc.org/is/19-086r5/19-086r5.html#toc63

[m-mohr]

Yeah, this just makes it more obvious that the OGC WGs should collaborate more closely on central components.

Just adding new properties is not an issue, but modifing (relaxing) the behavior of existing properties (as templated does with href) is a problem.

[jerstlouis]

Yeah, this just makes it more obvious that the OGC WGs should collaborate more closely on central components.

I strongly support that idea :) We are planning to resume the OGC API - Common meetings starting at the Singapore OGC API track on September 27.
I personally wish we did more of the development all together under the umbrella of that Common SWG, even if we had to meet multiple times a week, perhaps with specific topics on a given day of the week.

Unfortunately, there is still too much of a "our group" and "that other group" associated with the different OGC API SWGs, meaning that different decisions might be taken as a solution to address the same problem, and a different group of people (facing the same problems) showing up at one meeting vs. the other. This also means having to attend more meetings to try to stay on top of everything and trying to avoid that exact problem of divergence :)