Update templated links to support both aware and unaware clients.

[pvretano]

Closes #275

This is just a draft pending discussion in the SWG about templated links.

The gist of the PR is that client who know nothing about templated links should still be able to resolve the link.

This is accomplished by converting the templated member from a boolean to a string that supplies the text of the parameterized URL. If it is present then the href member simply contains an example or representative URL created by picking valid substitution values from the dictionary of substitution variables.

Aware clients can ignore the href value and generate a new resolvable URL using the dictionary of substitution variables.

Unaware clients can ignore all the templated stuff and simply use the value of the href member.

[m-mohr]

I'd prefer to use variables instead of varBase (or combine them). The additional HTTP request for links is not a good ideas in web UIs.

[m-mohr]

@cportele That's also a good option, I think. My main point is really just that templated links should not interfere with the links in a way that it breaks if clients (or servers) are not aware of it.

[pvretano]

@cportele @m-mohr ok, I updated this draft PR to separate links and templated links into different objects.

[cportele]

@pvretano - You have added the link templates in the links array, which does not resolve the issue. Clients that expect only links in that array will run into issues, if the encounter an object without a href member.

Also, varBase is not consistent with the Link-Template ID (see my earlier comment).

[m-mohr]

Interesting, I understood this a bit differently. I had thought we keep the new object out of the links and ideally create a new property.

Simplified Example:

"links": [
  { "href": "example.json", "rel": "example" }
],
"linkTemplates": [
  {
    "href": "example.json?q={var}",
    "rel": "example",
    "variables": {
      "var": { "type": "string" }
    }
  }
]

Edit: Yeah, exactly what @cportele said :-)

[pvretano]

@cportele wouldn't they simply ignore what they don't understand? We still want to use link templates in the links section ... no? In the current approach, they would see "href" containing substitution variables, they would try to resolve that without doing the substitutions and it would fail. At least now, they will see an object that does not have an href and ignore it.

Also, where are you seeing "varBase"? I through I renamed all those to "var-base" with the last commit.

[pvretano]

@m-mohr that was not my understand at all so I may have missed that. I really don't live that approach at all! ... but I am open to being convinved otherwise! :)

[m-mohr]

@pvretano No, because in code they would expect that the href is there, because it is defined in several specs (Common, Feature, STAC) that href is required and the array consists of Link Objects only.

I know people do stuff like (pseudo code):

link = links.find(l =>l.rel == 'abc')
http.get(link.href)

If you want them in links, my initial proposel would be back in the game ;-)

[cportele]

@pvretano - If they would be able to identify objects in the array that are not links, they would not have problems with templated. Every link must have a href property with a URI as the value. The templated approach violates the "URI as the value" aspect, the link-template approach violates that href is required.

Regarding varBase: I used varBase instead of var-base since the OGC API convention is to use lowerCamelCase for JSON keys and kebab-case for query parameters. The value of var-base in the ID is a base URI to which you append the variable name to get the URI to resolve to get more information about a particular variable. See the draft.

[pvretano]

@m-mohr, @cportele please review ... not that we are going to merge this until we get general concensus but review to make sure I got it right this time around.

[pvretano]

05-JUL-2023: Need to a requirement that says that the information returned by resolving a URI composed of the varBase and the variable name SHALL be JSON-Schema. @pvretano will make this addition and then merge this PR.

[m-mohr]

We've also had a larger discussion during FOSS4G about this. General consensus was that templates links should be separate unless we add templated to Common, Features and STAC. Otherwise, variables + varBase look good enough.

(stac_folks didn't like the camelCase, but we run into these issues anyway with numberReturned etc, so ignore it for now.)

How should the response for the varBase URI should look like? Should there be an example?

[pvretano]

10-JUL-2023: OGC API Tiles, an adopted specification, already uses templated links without separating them into two sections (links, linkTemplates). Features does the same. In both cases they follow the IETF standard and use varbase for getting information about the variable. So, if we don't merge this PR and remove the ability to specify the variable descriptions in-line then Tiles, Features and Records would be aligned. @pvretano and @kalxas think this is probably the best approach for Records. We probably need a broader discussion in OGC about whether we need to have separate sections for links and linkTemplates but so far, at least for Tile and Features, that does not seem to be a problem. @pvretano will ask @ghobona about the best forum for that discussion.

[m-mohr]

@pvretano Where can I find this in Features? I don't see it being mentioned in Part 1 (or in any other released part) and if it's not in there, the issues discussed above with extensibility also applies there.

[cportele]

@m-mohr - It is currently at "Unresolved directive in clause_7_core.adoc - include::recomendations/core/REC_fc-md-item-link-templates.adoc[]" :wink: I just pushed a fix, it should be included in the Editor's draft tomorrow.

The direct link to the recommendation is here: https://github.com/opengeospatial/ogcapi-features/blob/master/core/standard/recomendations/core/REC_fc-md-item-link-templates.adoc

[pvretano]

Converting to drafts because of this discussion.

[m-mohr]

@cportele Thanks for the pointer. So this is going to be Features 2.0? Strictly speaking this is a breaking change, I'd say:

1. In theory, you are now allowed to specify variables for e.g. next or self links, which are not necessarily dereferencable with variables.
2. The html conformance class says all links should be available in <a> tags, but this doesn't allow variables (afaik)
3. Links should be provided as HTTP Links, but RFC8288 (which Features references to), doesn't allow templates (afaik)

To me this looks like OGC made a mistake in Tiles, but now instead of fixing it (that's certainly possible in a non-breaking way in Tiles), it repeats the mistake again.

[cportele]

@m-mohr - That's why we said that we need to have a broader discussion across the OGC API groups. I think that the best approach is to introduce a separate array linkTemplates for the link templates as in this PR, but this should not just be a Features or Records decision / approach given that Tiles was the first to use link templates and decided to use a different approach.

[m-mohr]

@cportele Thanks, I missed that. Where is this discussion taking place?

[cportele]

@m-mohr - We don't know yet. From the meeting comment:

@pvretano will ask @ghobona about the best forum for that discussion.

[pvretano]

Another approach might be the following:

1) We use the existing schema for a link. 2) We add a template member that contains the template of a link using substitution variables. 3) Since the href is mandatory, its value -- in the case of a templated link -- is simply an "example" (but live) link. 4) We also add the varbase and/or variable members as before.

So, a clients sees something like this:

{
   "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&bbox=-180,-90,180,90&layers=stations&width=640&height=480&format=image/png"
   "template": "https://geo.woudc.org/ows?service=WMS&version=1.3.0&request=GetMap&crs={crs}&bbox={bbox}&layers=stations&width={width}&height={height}&format=image/png",
   "varBase": "https://...."
}

The template-unaware client simply ignores the template and varbase members and resolves the "example" link. The template-aware client would see the template and varBase members and would proceed accordingly (i.e. ignore href and use the template and varables instead to formulate a resolvable link).

Just thinking out loud here ...

[pvretano]

13-NOV-2023: @pvretano will resolve the merge conflicts. The consensus of the SWG is that we remove the ability to specify variable definition in-line and simply stick with the RFC which only defines varbase. @pvretano will check with @tomkralidis if removing the inline option is OK and if it is @pvretano will merge. If not, will discuss at the next SWG meeting.

[tomkralidis]

+1/fine with me to removing inline option.

[m-mohr]

Not overly happy with removing inline as it may lead to quite a number of additional requests. Resolving a link will not be self-contained, which I feel adds quite a bit of complexity. What were arguments for removing it?

[pvretano]

SWG meeting 11-DEC-2023: @cportele will review and @pvretano will ammend/merge one @cportele's review has been received.

[jerstlouis]

@pvretano @cportele Since this affects all the SWGs, could we adopt someting else than link-template because that does not follow the decision to avoid hyphens - in JSON property names. The Common guidance was to use camelCase for JSON property names, kebab-case for query parameters, although the final decision was not fully documented in this issue.

Potentially something shorther like tref or just template could be considered too, since this is already inside a template object? In DGGS we used tref so far:

https://github.com/opengeospatial/ogcapi-discrete-global-grid-systems/commit/59b2a1c9972eb5e19d06cba53c0313bf3e724a1d