Templated links conflict with OGC API - Common?!

m-mohr commented 1 year ago

In OGC API - Records I recently found the chapters about "Templated links with variables":

I think the addition of templates links with variables is not correctly extending OGC API - Common and is actually in conflict with it (also with STAC).

If I understand Common, ch. 6.3 correctly, the href must be a valid IRI/URI according to RFC 8288.

This implies to me that with a client, all hrefs should be resolvable and if I render them e.g. in a HTML document as href parameter in an a tag, user can click the link without issues and end up at a "valdid" page.

The way Records adds templated links, I think this would break clients that are not aware of templated links. If I understand correctly, that templated must be set to true and then href is containing variables. As such the href won't resolve without specifying the values for the variables and my HTML example with the a tag won't work anymore.

A simplified example from Records:

{
  "rel": "item",
  "type": "image/png",
  "title": "World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations",
  "href": "https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs={crs}",
  "templated": true,
  "variables": {
    "crs": {
      "description": "...",
      "type": "string",
      "enum": [
        "EPSG:4326",
        "EPSG:3857"
      ]
    }
  }
}

The href as such doesn't work in a naive (non-template-aware) client. The templated property basically weakens the href requirements, which is basically against the Liskov Substitution Principle.

I think Records has to extend Common in a different way. It must provide a default href that works (with defaults for the variables) and then add variables on top for clients that are aware of this functionality. It could look like this for example:

{
  "rel": "item",
  "type": "image/png",
  "title": "World Ozone and Ultraviolet Radiation Data Centre (WOUDC) stations",
  "href": "https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs=EPSG:4326",
  "templated": "https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs={crs}",
  "variables": {
    "crs": {
      "description": "...",
      "type": "string",
      "enum": [
        "EPSG:4326",
        "EPSG:3857"
      ],
     "default": "EPSG:4326"
    }
  }
}

In addition to all this, are templates variables really needed in the core?

pvretano commented 1 year ago

@m-mohr I think you are right. I will create a PR to modify the definition of templated links accordingly as a basis for futher discussion in the SWG.

pvretano commented 1 year ago

In addition to all this, are templates variables really needed in the core?

We discussed this is the SWG extensively and it was decided that because of the need to still access old-style OGC web services we needed templated links in the core ... since those old-style services require all kinds of parameters in order to create a resolvable URL (e.g. request=, service=, version=, layers=, etc.).

cportele commented 1 year ago

I see the argument, but it is more complex than that. templated has been used in OGC API standards for many years now. It should have been added to Common, but for some reason that did not happen. There is an old issue about adding templated to the Link object in Common, actually started by Records: https://github.com/opengeospatial/ogcapi-common/issues/187.

The original design came from the Vector Tiles Pilot which followed the approach in HAL. See also this issue.

OGC API Tiles eventually added the templated and varBase parameters to the Link object in their schemas: https://schemas.opengis.net/ogcapi/tiles/part1/1.0/openapi/schemas/common-core/link.yaml. varBase has been added based on https://www.ietf.org/archive/id/draft-ietf-httpapi-link-template-01.html. Since Tiles has been approved I think that implies that Common should be updated (at least as long something like Common is managed).

So, I think that Common is what has to be updated.

pvretano commented 1 year ago

@cportele oh crap! That means that I should probable update records to use the varBase stuff which I actually think is bad since it forces another redirection on the client to get the information necessary to resolve the link.

I think @m-mohr has it right. href is always a resolvable URL. If the templated property (as a string rather than a boolean) is specified then templated-aware clients can consider href an example URL and either use it to get a resource OR generate a new resolvable URL by making the appropriate substitutions based on their knowledge of the substitution vairables from varBase. Non-templated aware clients, on the other hand, will simply ignore all that and use href as normal. Win-win in my mind!

Just my $0.25 worth ... but that still leave open what I should do in records. I guess, since it is already being used in tiles I should adopt the varBase approach for getting info about the substitution variables instead of including that information inline as is currently done in Records.

Sigh!

m-mohr commented 1 year ago

Thanks for the comments.

Just my 2cts:

I don't think that because one of the specs has made a mistake we should repeat it. The templated approach as it is breaks with Common, with Features, with STAC. All the clients will get issues with such templated URIs.
The varBase as default looks like a bad idea for Web UIs. Not sure alignment is required as the use cases may look different. varBase is good if you have a lot of repetitive schemas (as in Tiles), variables from Records is better is you have a a lot of variability. To be compliant with Tiles (if required), you could also to define both in Common and the underlying specs (or implementer) can choose one approach. I could see STAC adopt the templated as string + variables approach, we also need templated links, but we can't adopt the boolean templated approach for sure.

cportele commented 1 year ago

As I said, I see the point that a client expecting a de-referenceable URI in href could have a problem.

But there was the decision some years ago to follow the HAL practice to use a templated property , which has been discussed several times in various forums, approved by the membership, and no one has raised an issue until now. So, clients should be prepared to receive URI templates in the href of an OGC Link object, too.

If we think this is an error, then this should be discussed quickly (probably in the session tomorrow) so that a different approach is agreed for Records, Features, etc. But at least for the two standards OGC API Tiles and OGC Two Dimensional Tile Matrix Set and Tile Set Metadata it is too late anyhow.

pvretano commented 1 year ago

@cportele I was planning to make this an agenda item in the Records portion tomorrow since this is cross cutting and we need a quick discussion and decision.

m-mohr commented 1 year ago

It's impossible to oversee all OGC APIs so it's difficult if an APIs imply changes to other APIs. I see myself pretty close to various OGC APIs, but I've just discovered this recently, I assume others that are less close to it, would only find it even later. I also assume others don't see this as a big issue if they don't have a lot of existing implementations like STAC has. And I'm biased of course towards STAC. When is the session tomorrow? I'm not on location, but could try to join the discussion remotely.

Thanks Peter for making this an agenda item.

cportele commented 1 year ago

When is the session tomorrow? I'm not on location, but could try to join the discussion remotely.

Records starts at 11:15am Huntsville time.

m-mohr commented 1 year ago

Thanks. I have a conflict, sorry. But I think I made the point clear enough here. Hope for a fruitful discussion tomorrow.

pvretano commented 11 months ago

07-AUG-2023: Pinged @ghobona for a status update. In the meantime another option was proposed for discussion when we discuss this in the bigger group (see here: https://github.com/opengeospatial/ogcapi-records/pull/290#issuecomment-1667814439). @cportele if we think this is a problem (which is not completely obvious right now) then splitting would be the prefered solution. @kalxas proposes that we take out templated links if we can't come to a decision about templated links before we plan to publish records. That way we won't break backward compatability.

ghobona commented 10 months ago

@pvretano I think the issue should be discussed and resolved within the OGC API - Common SWG.

There is a GitHub Issue on the topic or similar at https://github.com/opengeospatial/ogcapi-common/issues/187

pvretano commented 8 months ago

30-OCT-2023: The Architecture DWG has its meeting and the concensus was to use a separate "templatedLinks" section as we have done in PR #290. @pvretano will update the PR to make sure that the link tempate object match the draft Link Temaplte RFCs (its for headers but we can adopt for JSON objects). https://github.com/ietf-wg-httpapi/link-template

opengeospatial / ogcapi-records

Templated links conflict with OGC API - Common?! #275