Media types for openEO

[m-mohr]

For some cases it might be good to have specific media types for openEO responses or links, e.g. when combining openEO and OGC API - Processes.

I'd propose to use something like application/vnd.openeo+json with a type parameter: application/vnd.openeo+json; type=X where X could be:

• openEO process: process, i.e. application/vnd.openeo+json; type=process
• openEO process list: processes
• openEO batch job list: batchjobs
• etc.

[soxofaan]

In case someone is wondering what vnd means (like myself): it stands for "vendor" (e.g. see https://en.wikipedia.org/wiki/Media_type#Vendor_tree)

Do I understand correctly we have to register that vnd.openeo prefix somewhere?

[m-mohr]

At some point we should register the individual media types at IANA if we think this gets more commonly used. But we can start without reigistratrion...

[soxofaan]

FYI this discussion seems to become relevant in context of APEx: ESA-APEx/apex_algorithms#67 (cc @JanssenBrm )

To verify: combined with the "remote process definition" (from #538 / #540 ):
the proposal is to link to such a "remote process definition" with media type application/vnd.openeo.process+json?

[m-mohr]

Currently the media type is always application/json.

The primary issue with a different media type is that many clients don't do propert media type checks, e.g. they just do something like type == 'application/json' or similar. As such for many clients an alternative media type such as application/vnd.openeo.process+json or application/json; profile=openeo-process will not be recognized and lead to issues/errors.

• application/vnd.openeo.process+json would be the way to do it that is IANA compliant, but will likely lead to issues in our tooling
• An alternative that requires less registrations at IANA (preferrable) would be application/vnd.openeo+json; type=process but has otherwise the same issues as above - this might be the preferred approach, so I updated the original post above.
• application/json; profile=openeo-process could potentially be parsed a bit more easily, but is not officially allowed by IANA (no profile parameter registered for application/json and can't officially be added by us - we could use it inofficially though as it's done for COGs for example).

My take/recommendation for openEO servers and clients is currently to try to use application/json as much as possible, potentially in combination with specific relation types in links. Adding a new media type could be considered breaking (for clients), leading to openEO API 2.0.
If you are in a controlled context, you might be able to use different media types. I do it internally in the Web Editor, too, but it's just internal usage and no one else except the Wed Editor needs to know about it.
We could potentially define a list of such media types as a preview for 2.0, but without a guarantee that IANA would accept them as such and may change.

Similar discussions are also happening in OGC for OGC APIs, by the way:

• Clarify media-type and format negotiation of Part 3 collections opengeospatial/ogcapi-processes#427
• Other process encodings? opengeospatial/ogcapi-processes#325
• More specific content negotiation for GET /processes opengeospatial/ogcapi-processes#481
• Part 4: application/json as media type? opengeospatial/ogcapi-features#943
• RFC: Don't register a separate media type opengeospatial/ogc-feat-geo-json#129
• etc.

[m-mohr]

Originally written in ESA-APEx/apex_algorithms#67 (comment)

I'd propose to NOT use application/vnd.openeo.process+json anymore.

The new proposal above 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.