Add Profiles to Collection Resource response

[hcayless]

This came up in the recent Text APIs workshop at Heidelberg which @mromanello and I attended. If a collection has resources with multiple "views." Imagine HTML with just the text or HTML with a side-by-side image view, for example. Or different plain text derivatives of your sources. Simply switching by media type won't be sufficient for those cases. https://www.w3.org/TR/dx-prof-conneg/ presents the idea of a "profile" for this use case, and I think this would mean:

1. A new optional property profiles for Resources.
2. A new parameter profile that allows the choice between profiles.

The alternative, I guess, would be recommending people fool with the x. prefix to distinguish document responses with the same media type, but that seems weird.

[awagner-mainz]

I think it also came up in a conversation (at the same workshop) about the various entries in a Resources mediaTypes array, where it would allow people to choose between diplomatic and edited/constituted plaintext representations.

IIUC, one of the other presentation was achieving something similar with a type parameter to the media type. But when I then started researching "media type parameters", it quickly became very confusing, at least for me. I can supply links if anyone is interested.

[hcayless]

If I'm reading it rightly, this is part of the HTTP spec, that optional parameters may be included following the media type in the Accept or Content-Type headers. Since that's not part of the media type proper, that feels risky to me.... On the other hand, media type and profile are liable to be linked, and not all profiles may be available for all types. Maybe instead of (or in addition to) a string array mediaTypes should be an object array like:

[
  {"mediaType": "application/xml+tei"},
  {
    "mediaType": "text/html",
    "profiles" ["diplomatic edition", "critical edition"]
  }
]

Of course, if we did that, the mediaTypes name wouldn't really fit anymore. formats maybe?

[PonteIneptique]

I would have profile be a little more complex, such as

{
...
"profiles": [
   {"@id": "diplomatic", "description": "blablabla"}, ...
]
}

As profiles in themselves should probably be documented

[hcayless]

We discussed it this morning and there are two questions to be resolved:

1. Is this a v1.0 blocker, or can/should we wait until after the release to consider it?
2. Do we need to think about the nature of resources? In the current API, there is a mediaType parameter on the Document endpoint, meaning that a Resource can have multiple representations. This is somewhat natural in a TEI context, where you can think of the XML source and, say, an HTML derivation of that source as being in some sense the same thing. The derivation could be a dynamic (even client-side) transformation after all. But perhaps we should be thinking of any differing representation as being its own Resource—that is, we deal with this problem the same way we deal with versioning. A new version is a new Resource (ideally with metadata like dc:replaces pointing to its previous version).

If we were to decide that one Resource == one representation is the solution, we would need to remove the mediaType parameter from the document endpoint because there would only ever be one web resource, of one type, available at a given location. We would also need to modify the documentation. If we retain the mediaType for 1.0, we've taken a definitive step in the other direction, so Resources can have multiple format representations. That decision might be hard to walk back if we change our minds later.

So our charge for the next meeting is to think about these questions.

[lueck]

These optional parameters in the Content-Type or Accept header field are specified in RFC 2045, Sec. 5.1:

content := "Content-Type" ":" type "/" subtype *(";" parameter)
[...]
parameter := attribute "=" value

This was updated in https://datatracker.ietf.org/doc/html/rfc2231#section-7
See also https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/MIME_types#structure_of_a_mime_type

Common use case examples are character set information like in text/html;charset=UTF-8. TextAPI uses it for ContentObject: https://textapi.sub.uni-goettingen.de/page/specs/#content-object Their example is text/html;type=transcription. As I get their specs right, a client should request the server with an according Accept header, if the server offers several content objects under the same URL.

There's nothing obscure in this. The first example for existing standards in the (relatively new?) DX-proof-conneg specs fundamentally builds on content type parameters, too:
https://www.w3.org/TR/2023/WD-dx-prof-conneg-20231002/#using-accept-content-type-together-with-the-profile-parameter

Accept: application/ld+json;q=0.9;profile="urn:example:profile-1", application/ld+json;q=0.7;profile="urn:example:profile-2"

However, the profile is identified by a URI here, not by free token.

That said, there's something unclear in the DTS specs to me: mediaType is passed via the URI as defined in the URI template. The mediaTypes array on the Resource object – is it for the URI template or for the HTTP Accept header or for both? Why bother about the risk of an (obscure?) parameter in the Accept HTTP header, when the information must also be passed to the server via a URL argument?

By switching to profiles, we could gain more clarity here. As URI templates are an essential part of DTS, profiles should be realized with URL Query String Arguments (QSA) approach, not by HTTP headers.

The most important definition in the profiles spec with regard to the future of DTS is in sec. 6.2, https://www.w3.org/TR/2023/WD-dx-prof-conneg-20231002/#profileid :

A client requesting the representation of a resource conforming to a data profile MUST identify the resource by a Uniform Resource Identifier (URI) [RFC3986] and MUST identify the profile either by a URI or a token.

So, even when we switch from mediaType to profile, there will be no fundamental shift in the concept of resource. A resource is not multiplied by its representations.

Anyway, mediaType and profile do not differ so much and chances are, that we find a smooth upgrade path.

[jonathanrobie]

I love the idea, and I would like to see it happen in some form. This is a new feature request, not a problem with the current spec. I have been badly burned by adding this kind of thing at the end of the process - and XML 1.0 namespaces is a great example of the danger.

My advice:

1. Ship 1.0
2. Consider this feature for 1.1
3. Ship 1.1 a LOT faster than our current pace.

That gives us breathing room to think this through and get it right. Ideally, not too much breathing room, it's not a huge feature, and we should make 1.1 happen efficiently. There may be other features like this in 1.1.

[hcayless]

@jonathanrobie Completely agree it's a new feature request. My concern is that implementing the mediaType parameter for 1.0 potentially makes a decision as to which way the feature will have to be implemented later, and maybe we need to back off that for 1.0.

[jonathanrobie]

That's the classic for considering a feature before release - if the current design is not clearly extensible enough.

But in this case, shouldn't profile be orthogonal to media type? The same resource might be available in, e.g., these media types:

• xml
• html
• tei

It might also be available in these editions or profiles:

• with-apparatus
• text-only
• greek-and-latin
• greek-and-english
• diplomatic

So far, those all seem orthogonal to the media type. Am I missing something?