Clarify the use of Content Negotiation and the `f` query expectations

[fmigneault]

Detail

While browsing the OGC API - Processes - Part 1: Core draft, I noticed that the ?f= query is not that well-defined in terms of expected requirements.

There are some examples using it, such as the 7.2.2. Response - Landing Page Example or 7.10.2. Response - Process List Example 2.
There are also some mentions in the extra note under 7.3.2. Retrieve an API definition - Response and 10. Requirements classes for encodings.

However, beside those, it is not really indicated explicitly (a permission or recommendation) that it may be supported.

Also, there are not many cross-links applied when mentioning "content negotiation" in general in some descriptions, so one as to somewhat land on these notes by chance to be aware of them.

Furthermore, 10. Requirements classes for encodings (which could also be better cross-linked when mentioning "Content Negotiation" across the text) mostly refers to:

• https://datatracker.ietf.org/doc/html/rfc2616#section-12
• https://www.rfc-editor.org/rfc/rfc9110.html#name-content-negotiation-fields

Both of these references are mostly referring to Accept, Accept-Encoding, Accept-Language, etc. Therefore, it is still not that obvious that ?f= could apply as well, or that 7.7. Content negotiation by profile might also be involved.

In certain cases, like for 7.3.2. Retrieve an API definition - Response, the plain text "content negotiation" without any cross-reference might actually be misleading since Accept, etc. are not obviously indicated, and the note just after it quickly highlights the (IMO, less-preferred than header) alternatives using a file extension or accept/f queries.

Actions

I recommend:

• adding cross-references explicitly to 10. Requirements classes for encodings anywhere "content negotiation" is mentioned
• adding an explicit recommendation or permission about ?f= somewhere under 10. Requirements classes for encodings
• adding a cross-reference to the above ?f= item when mentioning such alternatives

[pvretano]

@fmigneault if you check out the Features and Fecords neither define "f" since it is not part of the standard content negotiation mechanism of HTTP. They only mention f in the context of implementations having to mint encoding-specific URIs in order to express links. From that perspective, I don't think we should formatlly define or recommend f. An impementation should be free to mint content-specific URIs any way it likes. Using f is just one approach for doing this.

[fmigneault]

I agree about not having a requirement since it is not standard, but isn't the point of recommendations to hint toward commonly employed method that servers are free to implement or not? If not a recommendation to avoid taking that stance, then a permission could be used to at least have a common reference to point at? At the very least, the current section 10. Requirements classes for encodings pushes toward Accept, so it is somewhat ambiguous whether f (or other) alternatives are even allowed.

[jerstlouis]

@fmigneault

so it is somewhat ambiguous whether f (or other) alternatives are even allowed.

What is important to emphasize (for all OGC APIs), is that clients can only rely on Accept:.
Servers can implement any other mechanism(s) they want, but they need to understand the Accept: header, and that is what clients need to rely upon.

Avoiding mentioning f in the document avoids the potential confusion that clients could think they can rely on it being implemented.

[fmigneault]

@jerstlouis

I fully agree that Accept header MUST be supported, but even that is not made explicit. The requirement must be stated in the standard to make sure of it.

When actually going through the document, there are actually more hints against it, because alternatives are indicated while Accept header isn’t. There are even hints telling queries SHOULD be supported.

Section 10 has in the note (emphasis mine):

NOTE 2: Any server that supports multiple response encodings (JSON or HTML defined in this Standard or other encodings not specified in this Standard) will have to support a mechanism to mint encoding-specific URIs for resources in order to express links, for example, to alternate representations of the same resource.

Section 10.2 also mentions (emphasis mine):

NOTE: Responses from the execution endpoint /processes/{processID}/execution may or may not generate JSON depending on the process being executed, the negotiated execution mode, the negotiated response format (specified using the HTTP Accept header or the f query parameter) and the number of requested outputs.

And 7.3.2 lists alternatives that should override the header, which makes it questionable if it even needs to be supported :

If multiple API definition formats are supported by a server, use content negotiation to select the desired representation.

NOTE: Two common approaches are:

• An additional path for each encoding of each resource (this can be expressed, for example, using format specific suffixes like “.html”);
• An additional query parameter (for example, “accept” or “f”) that overrides the Accept header of the HTTP request.

Everywhere that says "content negotiation" broadly without mention of ˋAccept header is not actually enforcing implementations to support it since [HTTP content negotiation rules](https://datatracker.ietf.org/doc/html/rfc2616#section-12) itself does not *require* using or respecting ˋAccept header, as it is only user preferences amongst many possible approaches. It is a "best effort" at most, which we must clarify explicitly.

[jerstlouis]

@fmigneault

will have to support a mechanism to mint encoding-specific URIs for resources in order to express links

Good catch on that. I think this is problematic, because servers should be able to use the same format-agnostic URI and rely on the Accept header (not including a "type": in this case).

I think all those cases you highlighted can and should rely primarily on the Accept: header, and for all the mention of alternatives it should be clear that the server can implement them, but which clients cannot rely on them being available.

[pvretano]

@jerstlouis @fmigneault

1. We have a dependency on HTTP and so I don't think need to say anything more about Accept. We certainly cannot say that server MUST support it since HTTP does not say server must support it.
2. We could, however, recommend that server should honour Accept.
3. The sections that @fmigneault cited are wrong. The use of f, etc. specified here should be removed completely. f, etc. should only be mentioned in the context of minting content-specific URIs. Period. That is my mistake so I will fix that in the PR that I am working on. Each of these sentences should simple say that HTTP content negotiation can be used to request desired representations.
4. We are not forcing servers to support content-specific URIs. We are simply pointing out that if they want content-specific URIs (for use with "rel=alternate" for example), then they will have to implement something to support that.