Abstract

This document describes how Internet clients may negotiate for content provided by servers according to profiles. This is distinct from negotiating by Media Type or Language: the profile is expected to specify the content of information returned, which may be a subset of the information the responding server has about the requested resource, and may be structured in a specific way to meet interoperability requirements of a community of practice.

Overview of DXWG documents on profiles

This document is part of a set of documents on profiles, edited by the W3C Dataset Exchange Working Group (DXWG). Some of the documents are general while some are technology-specific:

Introduction

Content delivered by dereferencing Internet identifiers can be negotiated for in different ways. When using the HTTP protocol [[RFC7230]], a client may set one or more headers:

However, clients have not had a defined way to negotiate for content based on its adherence to an information model - a standard, a specification or a profile - and this document addresses this functionality.

When online information about a resource adheres to one or more profiles, methods described here allow clients to list those profiles and request content according to one or more of them in order of preference. For example, information about an online book might adhere to the Dublin Core Terms [[DCTERMS]] metadata specification with each field of information, such as title, description, author etc., being defined and formatted according to various Dublin Core elements (dct:title, dct:description & dct:creator, respectively). Then, a request for the information about this book may ask for the list of profiles according to which the metadata is available, or it may ask specifically for a response adhering to the Dublin Core Terms. When no profile or an unsupported profile is requested, a server returns default content, that is, content conforming to the default profile supported by the server.

When selecting a content negotiation mechanism, an Internet client may use the HTTP protocol but it may also use other methods for providing instructions to a server, such as URI Query String Arguments (QSAs). QSAs are established as useful for humans and machines for situations where negotiation via HTTP is not practical, such as when manually entering requests into web browsers. This document also provides guidance for both HTTP and non-HTTP methods of content negotiation and ensures they all adhere to a single functional specification, ensuring their functional equivalency.

Guidance for the creation of profiles is provided in the [[PROF-GUIDANCE]] document created by the Dataset Exchange Working Group (DXWG).

Describing the parts of profiles and their relation to other profiles is the function of the Profiles Vocabulary [[PROF]], also produced by the DXWG.

For the purpose of compliance, the normative sections of this document are Section 3, Section 6, Section 7 and Section 8.

Definitions

specification

An act of identifying something precisely or of stating a precise requirement. - Oxford English Dictionary

One form of a specification is a standard which is a "basis for comparison; a reference point against which other things can be evaluated" - [[DCTERMS]]

profile

A named set of constraints on one or more identified base specifications, including the identification of any implementing subclasses of datatypes, semantic interpretations, vocabularies, options and parameters of those base specifications necessary to accomplish a particular function.

This definition includes what are often called "application profiles", "metadata application profiles", or "metadata profiles".

Source: deliberations of the DXWG. See ProfileContext wiki page.

client
A program that establishes a connection to a server for the purpose of sending one or more HTTP requests [[RFC7230]]
server
A program that accepts connections in order to service HTTP requests by sending HTTP responses. [[RFC7230]]
resource
The entity that is identified by a URI. Familiar examples include an electronic document, an image, a source of information with a consistent purpose. [[RFC3986]]
metadata
Information that is supplied about a resource [[RFC3986]]
request
A message sent over the Internet, from a client to a server, for a information about a resource [[RFC7230]]
response
A message sent over the Internet, from a server to a client answering a request for information about a resource [[RFC7230]]
token
A short name identifying something, in the context of this document a profile

Motivation

In many cases, there are several ways to describe a resource within the scope of a single Media Type. For instance, XML documents, while conforming to the text/xml Media Type, may adhere to one of several DTDs or XML Schemas. RDF documents, with a choice of Media Type serializations such as text/turtle, application/rdf+xml and others, have a large number of vocabularies (classes and properties) available to use for their content's information model. When a client initiates a request for an Internet resource, such as an HTTP GET to retrieve a resource or an HTTP PUT to create or replace a resource, the client and server must have a standardized way to exchange information on how the transmitted resource will be structured according to DTDs, XML Schema, vocabularies or other standards, specifications or profiles. When using non-HTTP content negotiation, various methods such as URIs with Query String Arguments have been implemented previously, such as the OAI-PMH [[OAI-PMH]] and OGC's CSW [[CSW]] protocols.

This document describes content negotiation based on profiles using HTTP protocol. It introduces HTTP headers and non-HTTP methods, such as via QSAs, and defines a general QSA Application Programming Interface (API).

Related Work

The standardization of the content-negotiation HTTP headers is the purview of the IETF. A first proposal for an Internet Draft for Negotiating Profiles in HTTP [[PROF-IETF]] is available but has not yet been submitted to the IETF. The current version of the IETF draft (-00) is expected to be completely re-written in parallel work with this document and should not be seen as anything but work-in-progress.

Existing standards for transporting profile information in HTTP headers

Using Accept/Content Type together with the profile parameter

The HTTP Accept and Content-Type header fields [[RFC 7231]] allow a client to specify acceptable media types (Accept) and a server to indicate the media type of the payload (Content-Type). A media type registration can also specify an optional list of media type parameters. Some media type registrations (e. g. application/ld+json) have specified the use of a media type parameter named "profile" that could be used to signal the profile the payload of the message conforms to.

GET /some/resource HTTP/1.1
Accept: text/turtle;q=0.9;profile="urn:example:profile-1",
	text/turtle;q=0.7;profile="urn:example:profile-2"

HTTP/1.1 200 OK
Content-Type: text/turtle;profile=<urn:example:profile-2>

During TPAC 2018 in Lyon, the DXWG had a longer discussion with the JSON-LD WG and it was concluded that the “profile” parameter in the Accept and Content-Type headers should be seen to convey profiles that are specific to the media-type, such as the JSON-LD profiles "expanded" (http://www.w3.org/ns/json-ld#expanded) or "flattened" (http://www.w3.org/ns/json-ld#flattened). In order to signal the use of media-type-independent profiles, the http header fields Accept-Profile and Content-Profile are to be used.

Using a Link-header with rel=”profile” (RFC 6906)

The HTTP Link header field [[RFC 8288]] relates a web resource (Link Context) to a target resource (Link Target by specifying the relation between the two resources. One of the relation types is “profile” as defined in [[RFC 6906]]. RFC 6906 defines a profile as "additional semantics that can be used to process a resource representation […] that do not alter the basic media type semantics," and specifically states that "creators and users of profiles MAY define and manage them in a way that allows them to be used across media types," so that the "profile" relation seems like a suitable way to transport information about acceptable profiles (request) and payload profile (response).

HEAD /some/other/resource HTTP/1.1
Accept: text/turtle;q=0.9,application/rdf+xml;q=0.5
Link: <http://example.com/profile-1>; rel="profile"

HTTP/1.1 200 OK
Content-type: text/turtle
Link: <http://example.com/profile-1>; rel="profile"
    

There is, however, no possibility to convey quality information (q-values) using the “profile” relation.

Using the Prefer/Preference-Applied header fields (RFC 7240)

The http Prefer and Preference-Applied header fields [[RFC 7240]] can be used to convey information about profile preferences. A client could use the Prefer header to tell the server about its preference for a payload conforming to a specific profile. If the server sends a Preference-Applied header field in the response, the client will know that the preference was honoured.

GET /some/resource HTTP/1.1
Accept: text/turtle
Prefer: profile=<urn:example:schema>

HTTP/1.1 200 OK
Content-Type: text/turtle
Preference-Applied: profile=<urn:example:schema>
    

This approach has two disadvantages. The first is - as with the Link header, that there is no possibility to work with q-values. The second one is that the only way for a server to state that it ignored the preference stated by the client is to omit sending a Preference-Applied header field. For the client - however - it is not clear if the Preference-Applied header is absent because the server did not honour the preference, or if it is because the server did not understand the Prefer header in the first place. This could be solved by making it mandatory to send a Link: rel=profil header when answering to a request with a Prefer: profile='' header in it. That solution requires that a client evaluates two different headers in order to find a response to its request for a specific profile, which would make client implementation more complicated.

The Internet-Draft for the registration of Accept-Profile and Content-Profile is currently work-in progress. When that work is completed, the above text will be adjusted accordingly or deleted.

Previous uses of Accept-* headers or other HTTP headers for this use will be listed and discussed here.

Abstract Model

This section describes an abstract conceptual model for content negotiation by profile, independent of any realizations of it within specific environments.

Context

All content negotiation takes place between a client and a server over the Internet with the former requesting a representation of a resource or a resource's metadata through a request and receiving it via a response. In some cases, a server may have to make a request of a client and receive a response.

An Internet resource may have many aspects over which a client/server pair of agents might negotiate for content. These aspects are to be treated independently so content negotiation for a resource involving negotiation by profile and any other aspects of a resource will not affect each other. For this reason, other than a directive to maintain independence, no further discussion of negotiation by profile and the relations to other forms of negotiation are given. Specific realizations might require special handling of profile and other forms of negotiation.

A client requesting the representation of a resource conforming to a profile MUST identify the resource by a Uniform Resource Identifier (URI) [[RFC3986]] and MUST identify a profile either by a URI or a token that unambiguously identifies the profile for the server within that request/response session.

In this abstract model, we don't assume any specifics about client, server, resource, metadata, request or response.

If a URI is used for profile identification, it is recommended that it be an HTTP URI that dereferences to a description of the profile. Other kinds or URIs, e. g. URNs MAY also be used however systems will need to provide means to describe such profiles for a given URN. When a token is used, the server is responsible for declaring the context within which the token may be mapped to a unique profile identifier, such as an HTTP namespace.

Requests and Responses

There are two main types of request that a client might make of a server regarding content negotiation by profile. A client wishing to negotiate for content via a profile adhering to this specification MUST be able to implement these two request types.

  1. list profiles
    a client requests the list of URIs of profiles for which a server is able to deliver conformant resources
  2. get resource by profile
    a client requests a representation of the requested resource represented conforming to a particular profile

A third request type is given that is expected not to apply to all realizations of this abstract model and not all clients adhering to this specification need implement it.

  1. list profiles tokens
    a client requests the list of tokens that the server uses for profiles and for which the server is able to deliver resource representations that conform to the profile. The server also provides a mapping from tokens to profile URIs

A server adhering to this specification MUST respond to each request with the following responses. The first two types are required, handling the third depends on the realization environment.

  1. list profiles
    a server responds to a client with the list of profile URIs for the profiles for which it is able to deliver conformant resource representations
  2. get resource by profile
    a server responds with either a specific profile for a resource conforming to a requested profile identified by the client or it responds with a default profile
  3. list profiles tokens
    a server responds with the list of profile tokens for which it is able to deliver conformant resource representations and the mapping of the tokens to profile URIs.

More detailed descriptions of these requests and their responses are given next.

list profiles

A client wishes to know for which profiles a server is able to deliver conformant representations of a resource. The content of the list can be known either before a request for a particular resource representation is made or it is known after an initial request for a resource representation is made.

The list profiles request MUST be either an independent request or part of another realization's request.

The list profiles request MAY result in a response in one of a number of formats provided that the profiles representations of resources conform to are unambiguously identified either by URI or a token which MUST be mappable to a URI within one particular client/server session.

A server MUST NOT list profiles that resource representations conform to if it is unable to deliver those representations when presented with a get resource by profile request.

Token listing

If, in addition to providing references to profiles via URI, a server wishes to provide tokens that map to URIs, it MUST provide a way of listing token/URI mappings to clients via the list profiles request.

get resource by profile

The most basic request of content negotiation by profile is for a client to request a representation of a resource that is claimed to conform to a profile.

A client executing a get resource by profile request MUST identify the profile with either a URI or a token mapping unambiguously within a session to a URI.

A client executing a get resource by profile MAY request a resource representation conforming to one of any number of profiles with its preference expressed in a some form of list ordering.

The server should attempt to reply with a profile that best matches the client request. The order of preference a server MUST follow to determine a best matching profile is: an exact match, followed by a profile (perhaps transitively) of the requested profile.

If a client requests a profile but gets a narrower profile, the Server should set its responses Content-Profile header to the profile identifier that the Client requested, not the identifier of the narrower profile as the client might not understand the narrower profile identifier.

# a request for Resource 1 according to Profile A is made

GET http://example.org/resource/1 HTTP/1.1
Accept-Profile: http://example.org/profile/A
[more request headers]

---

# the server IS NOT able to respond with a representation
# of Resource 1 conforming to Profile A

# the server IS able to respond with a representation of
# Resource 1 according to Profile B which it knows is a
# profile of Profile A

# the server indicates the response conforms to Profile A,
# not Profile B so the client is assured of conformance

HTTP/1.1 200 OK
[other response headers]
Content-Profile: http://example.org/profile/A
[more response headers]

[content according to Profile B and thus Profile A which it profiles]
          

Realizations

This section describes realizations of the abstract model in multiple implementation domains.

Hypertext Transfer Protocol Headers

A realization of the Abstract Model using Hypertext Transfer Protocol (HTTP) headers is presented here. This implementation is based on HTTP content negotiation and uses two new HTTP headers, Accept-Profile and Content-Profile that are to be defined in an upcoming Internet-Draft [[PROF-IETF]].

list profiles

The preferred way to retrieve a list of profiles the server supports for a specific resource is to issue a GET or HEAD request for that resource. In either case, a server implementing content negotiation by profile SHOULD return an HTTP Link header containing information about the default representation of that resource and information about any alternate representations of that resource that that conform to potentially other profiles. The returned representation will be identified by rel="self", other representations by rel="alternate".

As an example, consider the resource http://example.org/a/resource available in the Media Types application/xml, text/html and text/turtle. The text/html representation has no profile, whereas the application/xml and text/turtle representations are both available in the profiles urn:example:profile:1 and urn:example:profile:2.

All representations of /a/resource have Content-Location URLs. This results in the following matrix:

Media Type / Profileurn:example:profile:1urn:example:profile:2
text/htmlhttp://example.org/a/resource.htmlhttp://example.org/a/resource.html
text/turtlehttp://example.org/a/resource.prof1.ttlhttp://example.org/a/resource.prof2.ttl
application/xmlhttp://example.org/a/resource.prof1.xmlhttp://example.org/a/resource.prof2.xml

Assuming that a request without an Accept-Profile header per default delivers content conforming to urn:example:profile:1, an HTTP request/response pair would look as follows:

HEAD /a/resource HTTP/1.1
Accept: text/turtle
[more request headers]

---

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Location: http://example.org/a/resource.prof1.ttl
Content-Profile: urn:example:profile:1
Link: <http://example.org/a/resource.prof1.ttl>; rel="self"; type="text/turtle"; profile="urn:example:profile:1",
  <http://example.org/a/resource.prof2.ttl>; rel="alternate"; type="text/turtle"; profile="urn:example:profile:2",
  <http://example.org/a/resource.prof1.xml>; rel="alternate"; type="application/xml"; profile="urn:example:profile:1",
  <http://example.org/a/resource.prof2.xml>; rel="alternate"; type="application/xml"; profile="urn:example:profile:2",
  <http://example.org/a/resource.html>; rel="alternate"; type="text/html"
[more response headers]
        

Optional response content

While the server SHOULD return the canonical list of profiles in the response's Link headers, it MAY also supply the list in response content and if it does so, content negotiation by Media Type CAN be used to request one of the following formats:

text/uri-list

A basic, unordered list of profile URIs to which representations of the resource conform - both the 'self' and 'alternate' profiles.

Comment lines - lines starting with # - indicating 'self' and 'alternative' may be supplied above each URI

application/ld+json or RDF data serialized in any format

A serialization of profile information and resource/profile associations formalised using the Profiles Vocabulary [[PROF]].

text/html
A human-readable version of Profiles Vocabulary content.

The example below shows the same information conveyed according to the three different response content Media Types listed above.

# request for /a/resource

GET http://example.org/a/resource HTTP/1.1

---

# header response

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Location: http://example.org/a/resource.prof1.ttl
Content-Profile: urn:example:profile:1
Link: <http://example.org/a/resource.prof1.ttl>; rel="self"; type="text/turtle"; profile="urn:example:profile:1",
  <http://example.org/a/resource.prof2.ttl>; rel="alternate"; type="text/turtle"; profile="urn:example:profile:2",
  <http://example.org/a/resource.prof1.xml>; rel="alternate"; type="application/xml"; profile="urn:example:profile:1",
  <http://example.org/a/resource.prof2.xml>; rel="alternate"; type="application/xml"; profile="urn:example:profile:2",
  <http://example.org/a/resource.html>; rel="alternate"; type="text/html"
[more response headers]

# response content according to the text/uri-list Media Type, with comments

-
# self
urn:example:profile:1
# alternate
urn:example:profile:2
-

# response content according to the application/ld+json Media Type (JSON-LD)

-
{
  "@context": {
    "dct": "http://purl.org/dc/terms/",
    "prof": "http://www.w3.org/ns/dx/prof/",
    "rdfs": "http://www.w3.org/2000/01/rdf-schema#",
  },
  "@graph": [
    {
      "@id": "http://example.org/a/resource.prof2.xml",
      "dct:conformsTo": {
        "@id": "urn:example:profile:2"
      },
      "dct:format": {
        "@id": "https://w3id.org/mediatype/application/xml"
      },
      "rdfs:comment": "alternate"
    },
    {
      "@id": "http://example.org/a/resource.prof1.ttl",
      "dct:conformsTo": {
        "@id": "urn:example:profile:1"
      },
      "dct:format": {
        "@id": "https://w3id.org/mediatype/text/turtle"
      },
      "rdfs:comment": "self"
    },
    {
      "@id": "http://example.org/a/resource.prof2.ttl",
      "dct:conformsTo": {
        "@id": "urn:example:profile:2"
      },
      "dct:format": {
        "@id": "https://w3id.org/mediatype/text/turtle"
      },
      "rdfs:comment": "alternate"
    },
    {
      "@id": "http://example.org/a/resource.prof1.xml",
      "dct:conformsTo": {
        "@id": "urn:example:profile:1"
      },
      "dct:format": {
        "@id": "https://w3id.org/mediatype/application/xml"
      },
      "rdfs:comment": "alternate"
    }
  ]
}
-

# response content according to the text/html Media Type

-
<html>
  <head>[head information]</head>
  <body>
    <h1>Alternative Profile information for Resource http://example.org/a/resource</h1>
    <table>
      <tr>
          <th>Media Type / Profile</th>
          <th>urn:example:profile:1</th>
          <th>urn:example:profile:2</th>
      </tr>
      <tr>
          <th>text/html</th>
          <td>http://example.org/a/resource.html</td>
          <td>http://example.org/a/resource.html</td>
      </tr>
      <tr>
          <th>text/turtle</th>
          <td>http://example.org/a/resource.prof1.ttl</td>
          <td>http://example.org/a/resource.prof2.ttl</td>
      </tr>
      <tr>
          <th>application/xml</th>
          <td>http://example.org/a/resource.prof1.xml</td>
          <td>http://example.org/a/resource.prof2.xml</td>
      </tr>
    </table>
  </body>
</html>
-
          

Token mappings

If HTTP servers wish to allow clients to identify profiles via token, in addition to the the mandatory identification of profiles via via URI, the servers will need to provide a token / URI mapping via this list profiles function. In this HTTP realization, this may be implemented in a number of ways. The preferred way is to add "token" parameters to the HTTP Content-Profile and Link HTTP headers.

# The Profile with urn:example:profile:1 is mapped to token p1 and URI
# and the Profile with URI http://example.org/profile/2 is mapped to p2

HEAD /a/resource HTTP/1.1
Accept: text/turtle
[more request headers]

---

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Location: http://example.org/a/resource.prof1.ttl
Content-Profile: urn:example:profile:1;token=p1
Link: <http://example.org/a/resource.prof1.ttl>; rel="self"; type="text/turtle"; profile="urn:example:profile:1;token=p1",
  <http://example.org/a/resource.prof2.ttl>; rel="alternate"; type="text/turtle"; profile="http://example.org/profile/2;token=p2",
  <http://example.org/a/resource.prof1.xml>; rel="alternate"; type="application/xml"; profile="urn:example:profile:1;token=p1",
  <http://example.org/a/resource.prof2.xml>; rel="alternate"; type="application/xml"; profile="http://example.org/profile/2;token=p2",
  <http://example.org/a/resource.html>; rel="alternate"; type="text/html"
[more response headers]
          
Nick: I don't think profile="urn:example:profile:1;token=p1" will work within the Link header (too many layers of structured text) however I believe that where ever a profile URI is quoted, the token must be also thus it's necessary.

There are several methods that many be used to convey URI / token mappings including the recommended method described and exemplified above.

Option 1: token parameters (recommended)

"token" parameters are added to Content-Profile & Link profile= HTT headers.
Pros: self-contained,flexible, explicit.
Cons: potential redundancy in URIs if many offered

Option 2: registered tokens

Tokens are registered in a global registry and servers may use them in place of a URI
Content-profile: token1, URI2 Pros: compact
Cons: a global registry for profiles not manageable when many systems define profiles and such a registry limits other capabilities of profile description by forcing generic profiles

Option 3: allow namespace declarations

As per the use of CURIEs [[CURIE]] whose specification "...defines a generic, abbreviated syntax for expressing URIs.", within JSON-LD [[JSON-LD]], a token may be indicated for use in place of a URI within a namespacing context. In this method, key/value pairs of tokens/URIs are defined within an HTTP header such as Content-Profile like this:

Content-Profile: @:http://example.org/profiles/,@w3c:http://w3.org/knownprofiles#, :token1, w3c:token2

Where the first key/value pair of token/URI is key: <nothing>, value: http://example.org/profiles/ and the second, is key: <w3c>, value:http://w3.org/knownprofiles#.

Pros: compact, no registry requirement
Cons: clients have more parsing to do
Note: could easily be a JSON-LD payload
(alternative syntax using parameter ns2;ns=http://example.org/profiles/)

Option 4: namespace header

In this method, a new HTTP header could be introduced to specifically convey token/URI profile key/value pairs. If Content-Profile-Namespaces is to be the new HTTP header, then a server may respond to a request with the following pair of headers:

Content-Profile-Namespaces: :http://example.org/profiles/,w3c:http://w3.org/knownprofiles#
Content-Profile: :token1, w3c:token2

get resource by profile

Getting a resource representation conforming to a specific profile is done by issuing an HTTP GET request against the resource and specifying the desired profile URI in an Accept-Profile header. It is possible to specify a range of acceptable profile URIs and also to indicate preferences by using quality indicators (q-values).

GET /a/resource HTTP/1.1
Accept: text/turtle;q=0.8, application/xml;q=0.5
Accept-Profile: urn:example:profile:1;q=1.0,urn:example:profile:2;q=0.6
[more request headers]

---

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Profile: urn:example:profile:1
[more response headers]
        

Having performed content negotiation and returned a resource representation, it is RECOMMENDED that the server also include a Link header indicating the availability of alternate resources encoded in other media types and conforming to other profiles, as described above.

URI Query String Arguments

There is a question within the working group regarding the advisability of specifying an alternative method of content negotiation conducted via query strings rather than HTTP headers. We have a requirement to show how datasets with different profiles can be made discoverable by humans, but there is disagreement whether this requirement extends to implementing the same negotiation scheme used in HTTP headers.

A Query String Argument (QSA) realization of the Abstract Model is presented here. Unlike the HTTP realization, which is the subject of an independent document [[PROF-IETF]], this realization is fully specified here and this document is considered normative for the QSA realization. This realization does not preclude other QSA specifications for profile and content negotiation.

A query string is a part of a URI which assigns values to specified parameters. QSAs are commonly used within web browsers by humans and in other client/server situations to deliver extra information to a server.

Key naming

When content negotiation by profile is to take place using QSAs, the requests and responses of the Abstract Model MUST be implemented. However there is some flexibility in how this may be done: QSA key/value pairs must be implemented but the specific key terms may be changed. In this realization, _profile and _mediatype are used to indicate a single profile or a list of preference-ordered profiles or Media types respectively with profiles or Media Types indicated by either URI or token.

Currently, the convention in HTTP content negotiation by media type uses tokens for Media Types, such as text/html or application/ld+json with the tokens registered at IANA's Media Types list.

There is no proposal yet to create a central register of profiles as this is thought by the authors to be un-sustainable in the long-term, given the likely numbers of profiles to be established.

For this reason, the QSA realization allows either URIs or tokens for profiles to be used and it is expected, though not mandated here, that QSA realizations will also allow URIs or tokens for Media Types and other content negotiation dimensions, such as language. There are already several initiatives that have created URIs for Media Types based on the IANA register's tokens.

Resource URI

Resource URIs for which QSA-based profile negotiation is taking place MUST NOT themselves be QSA values of other resource URIs in any QSA-based realization. Such mechanics may be used but must be transparent to the realization's client applications.

For the representation of Resource X, according to Profile Y, in Media Type Z:

NOT ALLOWED:
GET /single/endpoint?resource=http://example.org/resource/X&_profile=Y&_mediatype=Z HTTP/1.1

ALLOWED:
GET /resource/X?_profile=Y&_mediatype=Z HTTP/1.1
      

list profiles

A QSA with a fixed value MUST be supported by a server to allow a client to make a list profiles request.

The QSA key/value pair _profile=list SHOULD be used however the server MAY make available an equivalent pair as long as this is discoverable. This is to cater for APIs that alreadly implement a similar function using QSA key/value pairs such as _view=alternates.

The complete request for the profiles to which a resource's representations conform can be communicated in a single URI like thus:

GET /a/resource?_profile=list HTTP/1.1
        

where /a/resource is the URI of the resource for which the list of available profiles is requested

A client making this request MAY negotiate for particular formats of the response by using a QSA equivalent to the HTTP Accept header to indicate a Media Type. A server SHOULD implement a _mediatype QSA for this but MAY implement an alternative, such as _format as long as this is dicoverable,

An example profile listing for a resource in HTML would look like:

GET /a/resource?_profile=list&_mediatype=text/html HTTP/1.1
        

get resource by profile

Expressing profile preference

A server implementing profile listing for resources SHOULD allow the requester to indicate preferences. This SHOULD be done by allowing the QSA indicating the desired profile, usually _profile, to have a comma-separated list as its value so, for a client desiring representations of /a/resource according to profiles with tokens aaa, bbb & ccc we have:

  GET /a/resource?_profile=aaa,bbb,ccc HTTP/1.1
        

Servers MAY support any combination of profile URIs or tokens for this (e.g. aaa,http://example.org/profile-x,bbb). However, in this situation, profile URIs containing commas must escape them.

Similarly, a server implementing multiple Media Type return formats for profile listing SHOULD allow a client to specify a preference order for Media Types and also for other dimensions of content negotiation, such as language. When using a QSA-only API, Media Type preferences (and language and others in a similar fashion) MAY be specified in a comma-separated list form, most preferred to least such that a client requesting profil

Test Suites

This section includes links to software tools to be used for testing the adherence of implementations to the realizations given in this document.

Apache JMeter

An Apache JMeter implementation of a test suite is maintained at: https://github.com/CSIRO-enviro-informatics/prof-conneg-jmeter-test-suite

Implementations

This section includes implementations of the realizations given in this document and their conformance test results. The tools used for conformance testing are listed in the section above.

Security and Privacy

The use of HTTP to negotiate and transport implies that all privacy and security issues that are relevant for that protocol are also relevant for profile negotiation. E. g., information such as user agent, accept-headers, IP address etc. can potentially be used as identifying information, and particularly, the IP address adds information about geolocation and institutional membership. Apart from that, there are no known security or privacy impacts of this feature.

For a more complete view of those issues, cf. the Privacy and Security Questionnaire for this deliverable.

Appendices

Requirements

This section lists, and then addresses, individual requirements that the Dataset Exchange Working Group considered important for content negotiation by profile.

Responses to individual requirement Issues listed here are, at the time of the First Public Working Draft of this document, for demonstration only; to indicate the logic of answers to individual requirements.

These requirement responses may not survive in their current form in later drafts of this document nor may individual listings of requirements; they may be subsumed into the flowing txt of the document.

RESPONSE FOR Req. 72

RESPONSE FOR Req. 73

This requirement is addressed by suggesting how an Internet resource in general, rather than specifically a dcat:Dataset or dcat:Distribution should list profiles it implements. A DCAT- specific solution should not be any different from the general case.

Profile definition and constraints on properties are not addressed here. See [[PROF-GUIDANCE]].

This requirement is taken to mean "create a way to list the profiles implemented by a Internet resource for humans and machines to use". For the former (humans), the options are:

  • discovery via HTML representation
    • see [[PROF-GUIDANCE]]
    • an approach suggested is to provide an alternate view resource for the original resource located at RESOURCE_URI + ?_view=alternates which lists, at a minimum, the profiles, media types (formats) & languages available, as per the alternate views guidance.

For the latter (machines):

  • discovery via HTTP
    • see [[PROF-IETF]]
    • HTTP mechanics are described that allow clients to negotiate with servers for profile listings
  • discovery via RDF graph
    • see [[PROF]]

RESPONSE FOR Req. 74

This requirement is the focus of the IETF RFC in the DXWG Family of Documents [[PROF-IETF]].

In summary, a series of new HTTP headers are added to the HTTP specification allowing for HTTP negotiation via profile in a manner similar to negotiation via Media Type or Language.

RESPONSE FOR Req. 86

RESPONSE FOR Req. 217

RESPONSE FOR Req. 261

RESPONSE FOR Req. 263

The IETF submission in the DXWG Family of Documents [[PROF-IETF]] does not address content negotiaiton by profile query param patterns: it is limited to HTTP specification-based negotiation only.

Recommendations for content negotiation by profile via query param patterns (Query String Arguments) are given in the Profile Guidance [[PROF-GUIDANCE]] document where an API for this is defined.

RESPONSE FOR Req. 264

RESPONSE FOR Req. 265

This requirement is met by [[PROF-IETF]].

RESPONSE FOR Req. 266

RESPONSE FOR Req. 267

RESPONSE FOR Req. 284

(assuming wording of "a profile must have an identifier")

Profiles must be identified by an HTTP URI.

Short codes (tokens) for profiles that map to HTTP URIs for them may be used in systems that ensure the tokens map deterministically. This allows for the use of simple strings in places where URIs are impractical yet preserves the guarantee that every profile has an HTTP URI.

RESPONSE FOR Req. 285

RESPONSE FOR Req. 286

RESPONSE FOR Req. 288

This requirement is met by [[PROF]].

RESPONSE FOR Req. 289

This requirement is met by [[PROF-IETF]].

RESPONSE FOR Req. 290

Additional Issues

This section will be removed in a later version of this document.

Additional Issues related to this document and not yet placed within it are listed at the: