Align on the usage of the relationships in the links section

[JanssenBrm]

We should clearly define and align the relationship type in the links section used for openEO and OGC Processes. This would help streamline the visualization of the record in the Algorithm Catalogue.

Currently, we are using the following. Some of them have a mixed usage:

rel	type	description
openeo-process	application/json	URL to the UDP
service	application/json	Link to the openEO backend or to the OGC API Processes endpoint
example	application/json	Example output in STAC format or used as examples for input parameters
example	applicaiton/netcdf	Example output in NetCDF
application	application/cwl+yaml	URL to CWL file
order	text/html	Link to the HTML page to order the service (custom/NoR)
license	application/pdf	Link to the license file
preview	image/png	Example screenshot of the output
documentation	text/html	Link to the technical documentation

A suggestion (open to feedback):

rel	type	description
application	application/vnd.openeo.process+json	URL to the UDP
application	application/cwl+yaml	URL to CWL file
service	application/json	Link to the openEO backend or to the OGC API Processes endpoint
example-output	application/json	Example output in STAC format
example-output	application/netcdf	Example output in NetCDF
example-input	application/json	Example of input parameters
preview	image/png	Preview images to use in the visualization
order	text/html	Link to the HTML page to order the service (custom/NoR)
license	application/pdf	Link to the license file
about	text/html	Link to the technical documentation
webapp	text/html	Link to the web application for executing the service

[JanssenBrm]

Tagging @jdries @soxofaan @p3dr0 @HerveCaumont to get your feedback on this.

[JanssenBrm]

Some considerations to take into account regarding the examples:

• Size of the output examples
• The mime type should be more specific. JSON can represent a STAC item or a plain JSON file
• The expectations should be matched as the service might not generate STAC item.
• The availability of examples - this could be solved by uploading the examples to GitHub.

[JanssenBrm]

I've made some final updates to the relationship types. Unless there are any big objections, I suggest implementing them to close this topic.

[soxofaan]

about this part of the proposal:

rel=application type=application/json URL to the UDP

this obfuscates the fact that it's a link to an openEO UDP (originally/currently it's "rel=openeo-process"). Is this intentional, e.g. to make it generic/flexible?

Note there are not really standard indicators that a json doc is intended to be an openEO UDP representation, so by removing that information from the relationship, things might get quite fuzzy and muddy

[JanssenBrm]

Thank you for the feedback @soxofaan!

this obfuscates the fact that it's a link to an openEO UDP (originally/currently it's "rel=openeo-process"). Is this intentional, e.g. to make it generic/flexible?

Correct, we want to align the relationship types to make them more generic and flexible. The details should be more reflected in the MIME type. However, you have a valid comment that json might be a bit too generic. Would it be an option to use application/udp+json (similar to application/cwl+yaml for OGC API Processes)?

[soxofaan]

related discussion:

• Media types for openEO Open-EO/openeo-api#532

So with current state of that ticket I think we could go for application/vnd.openeo.process+json to link to a "UDP" (or more generically: a remote openEO process definition" )

[m-mohr]

Please consider Open-EO/openeo-api#532 (comment) before moving forward.

General feedback:

• I find that output and input are a bit weird. They feel to generic for its purpose as examples.
• Why is license required to be PDF? text/plain or text/html could be potential alternatives that are commonly used. Generally, across all rel types the media types seem pretty restrictive?!
• docs should potentially be about, which I've seen used for documentation and is also used in openEO: https://api.openeo.org/#section/API-Principles/Web-Linking

[JanssenBrm]

I find that output and input are a bit weird. They feel to generic for its purpose as examples.

This was also something we were talking about. Initially this was set to output-example but it contained two words. Do you have any suggestions from your experience?

Why is license required to be PDF? text/plain or text/html could be potential alternatives that are commonly used. Generally, across all rel types the media types seem pretty restrictive?!

The types are just examples based on the current content of the catalogue. The goal is to restrict the rel values but allow more flexibility on the type.

docs should potentially be about, which I've seen used for documentation and is also used in openEO: https://api.openeo.org/#section/API-Principles/Web-Linking

Good suggestion

[m-mohr]

Two words are fine, even offical IANA rel types have multiple words, e.g. terms-of-service. See https://www.iana.org/assignments/link-relations/link-relations.xhtml
OGC even uses URIs (sic!) such as http://www.opengis.net/def/rel/ogc/1.0/queryables as relation types.

[p3dr0]

regarding the mime types as @JanssenBrm mentioned we were considering this "as examples" for all relations but this reminds me that we forgot to consider their cardinality
should we explicitly allow (and also support this on the APEx GUI) to have multiple entries with the same relation but different mime-type ?

[soxofaan]

Please consider Open-EO/openeo-api#532 (comment) before moving forward.

I understand your concern about the risks of confusion in existing clients when deviating from application/json for JSON documents, but in this case we are developing new documents and new tools around that, so why not get it right from the start?

[m-mohr]

I don't know the exact context and the plans (i.e. didn't know about "developing new documents and new tools"), I just want to ensure we don't face issues in the core openEO tooling. :-)

[JanssenBrm]

I think your point is valid @m-mohr to take the openEO tooling into account. However, we are currently not interacting with any openEO tools (AFAIK), so it could make sense to update our catalogue for now with the suggestion and come back to this if openEO tooling would be required or the final decision on the type has been made.

[m-mohr]

Fair enough. I'd propose to NOT use application/vnd.openeo.process+json though.

The new proposal in Open-EO/openeo-api#532 (comment) is much easier to register with IANA as it just requires one registration instead of multiple registrations. So instead of application/vnd.openeo.process+json better use application/vnd.openeo+json; type=process. If we don't care about IANA, we could also do application/json; profile=openeo-process. This would have the benefit that a "well-behaved client" (one that parses media types correctly) could already support the new media type without changes. Any thoughts or preferences?

I just want to ensure that we think about this enough before locking in on anything that may be an issue later.