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 one within a set of documents on profiles, edited by the W3C Dataset Exchange Working Group (DXWG). Some of the documents are general whereas others 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 describes how this functionality can be delivered.

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, a catalog may offer a dataset description using alternative representations using [[VOID]], [[VOCAB-DATA-CUBE]] and [[VOCAB-DCAT]]. Furthermore, the [[VOCAB-DCAT]] representation might conform to the [[DCAT-AP]] profile, the [[GeoDCAT-AP]] profile and also an organisation specific profile "MyOrgDCATProfile" which constrains various elements. These profiles may be related - for example "MyOrgDCATProfile" may be a further profile of [[GeoDCAT-AP]]. A request for the information about this dataset description resource may ask for the list of profiles available, or it may ask specifically for a response adhering to, for example [[GeoDCAT-AP]]. 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.

Where documents contain data specifications (specifying requirements for certain types of data) in addition to other content, such as recommendations, annotations, usage notes) then this can be accomodated by publishing explicit identifiers for each section that represents a data specification that can be conformed to. All such specifications can be regarded as profiles, and communities may choose to reference the document as a profile provided that it defines the means to determine conformance to the document as a whole.

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.

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.

Specifications and Profiles embody their own notions of conformance, which are out of scope for this specification.

Profiles for Conformance

This specification includes several profiles of it that may be conformed to by systems claiming to implement a form of this specification. These profiles, given in the table below, are identified by their URIs and conformance to them by Internet resources should be indicated as per this document (use of Content-Profile HTTP header).

The namespace prefix for these profiles used in is:

URI Name Description Usage Note
cnpr:abstract Abstract Model For conformance with the model presented in . Not to be used if a resource also conforms to a more concrete profile (all of the others)
cnpr:http HTTP Realization For conformance with the realization presented in . To be used if a resource conforms to the HTTP Realization
cnpr:qsa QSA Realization For conformance with the realization presented in . To be used if a resource conforms to the QSA Realization using the Query String Arguments _profile and _mediatype as per the recommendations in .
cnpr:qsa-alt QSA Alternate Keywords Realization For conformance with the realization presented in . To be used if a resource conforms to the QSA Realization but uses alternate keywords for the Query String Arguments _profile and _mediatype, as allowed by the recommendations in .
cp:rrd Resource Representation Description For conformance with . To be used if a resource representation is able to indicate which profile(s) it conforms to, in its appropriate realization, as per the abstract specification in .
Profiles of this Content Negotiation by Profile specification to be used by resources and systems to indicate conformance to one or more forms of it.

The namespace used for the above profiles, http://www.w3.org/ns/dx/conneg/profile/, is part of the Dataset Exchange Working Group's reserved W3C namespace, http://www.w3.org/ns/dx/, which is provisioned for all namespace requirements to do with issues addressed by that Working Group. The /profile/ path segment indicates a register of profile objects which currently contains just the 5 instances above from .

If a system wishes to show conformance to this specification, conformance to at least one of the profiles listed in MUST be indicated.

This section's identifications of profiles of this specification exemplifies functional profiles which profile a functional specification, rather than a data profile which profiles a data specification. This specification describes how a system should behave and this section indicates different profiles of that behaviour, rather than content (data).

Definitions

specification

A basis for comparison; a reference point against which other things can be evaluated.

Source: DCMI Metadata Terms [[DCTERMS]]'s definition for a Standard.

data specification

A specification, with human- and/or machine-processable representations, that defines the content and structure of data used in a given context.

Source: deliberations of the DXWG.

data profile

A data specification that constrains, extends, combines, or provides guidance or explanation about the usage of other data specifications.

This definition includes what are sometimes called "application profiles", "metadata application profiles", or "metadata profiles". In this document, these, and "data profiles", are all referred to as just "profiles".

Source: deliberations of the DXWG.

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]]
representation

An abstraction of the current or desired state of a thing in HTTP communications. [[RFC7230]]

In this specification, representations are of resources.

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 an abstract, functions-based, model for content negotiation by profile and gives both the HTTP header realization and also a recommended query string argument-based realization too. The query string approach provides a "fall back" required by the Dataset Exchange Working Group's Charter (Section 2.3). Other query string or REST-based realizations are considered possible but are not given here. In general, existing APIs that support specification of alternative profiles for resource representations may support this model too by implementing its functions.

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.

Abstract Model

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

Realizations of this abstract model MUST implement its functions, but how they do this will be environment-specific.

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 specific details 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 resource representations
  2. get resource by profile
    a client requests a representation of the requested resource represented conforming to a particular profile

A server adhering to this specification MUST respond to each request with the following responses.

  1. list profiles
    a server responds to a client with the list of URIs of 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

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 may only be 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.

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 anything that the profile profiles (a more general specification or profile), perhaps transitively.

A server SHOULD set a Content-Profile header in HTTP response to the profile identifier (URI) that the Client requested, not the identifier of any narrower profile that is also applicable since the client might not understand the narrower profile identifier.

# a request for Resource a according to Profile x is made

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

---

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

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

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

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

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

When a resource is returned that conforms to two or more profiles not within a profile hierarchy (i.e. none of the multiple profiles the resource conforms to is a profiles of another), the server MUST indicate all profiles individually within the Content-Profile header as such:

Content-Profile: <PROFILE_1>, <PROFILE_2>

For example, a response from a server that conforms to both [[?GeoDCAT-AP]] and also [[?statdcat-ap]], given that neither profiles the other and thus no single indication of conformance will suffice for both, (note they both do profile [[?DCAT-AP]], see the DCAT-AP Hierarchy example in [[PROF]]), using profile URIs for [[?GeoDCAT-AP]] and [[?statdcat-ap]] could be:

Content-Profile: <https://joinup.ec.europa.eu/release/geodcat-ap-v10>, <https://joinup.ec.europa.eu/release/statdcat-ap/101>

Realizations

This section describes realizations of the abstract model which are implementations of it in different environments.

This document provides onw two realizations however it is expected that implementers of content negotiation by profile may implement further realizations in other environments.

Implementers of Content Negotiation by Profile need not implement multiple realizations of the Abstract Model. They need only implement the realizations relevant to them - either those defined in this document or new ones they define, however each realization MUST accord with the Abstract Model.

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]].

Although servers are free to implement negotiation as they see fit, if the User Agent sends an Accept-Profile header, they SHOULD consider representations not conforming to any of the listed profiles as non-interpretable by the client. This means that a representation that conforms to a listed profile, but has a low preference score on other dimensions, SHOULD be considered as more desired than a representation with a higher preference score on other dimensions but that does not conform to any listed profile. If no Accept-Profile header preference is given, the profile dimension SHOULD be ignored for negotiation purposes. Nonetheless, in all cases, the server's response SHOULD contain a Content-Profile header listing the URIs of all profiles to which it knows the representation conforms.

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 conforming to 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/resource/a 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:x and urn:example:profile:y.

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

In , for each of the different Media Type / Profile combinations, the URI of the resource remains unchanged and it is the Accept and Accept-Profile headers for Media Type and Profile respectively that alter the returned response.

A server MAY use Content-Location HTTP headers to indicate direct links to representations of the resource according to Media Type / Profile combinations and, if it does so, it may replace the unchanged URI in the Link header with those direct URIs, as per example .

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:x is mapped to token px and URI
# and the Profile with URI http://example.org/profile/y is mapped to py

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

---

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

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 /resource/a HTTP/1.1
Accept: text/turtle;q=0.8, application/xml;q=0.5
Accept-Profile: urn:example:profile:x;q=1.0,urn:example:profile:y;q=0.6
[more request headers]

---

HTTP/1.1 200 OK
Content-Type: text/turtle
Content-Profile: <urn:example:profile:x>
[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.

URL Query String Arguments

QSA Realization description

While the HTTP Realization's approach to profile negotiation enables fully automated content negotiation by profile, the motivating use cases for this specification included human actionable negotiation. Also, as related in , previous and existing systems already allow for human-actionable content negotiation by profile by a number of means.

To both allow for human-actionable content negotiation by profile and also to show how mechanics similar to existing systems might fulfill all aspects of this specification's Abstract Model, here we present a Query String Argument (QSA) Realization of the Abstract Model. This Realization is functionally equivalent to the HTTP Realization in that all required functions of the Abstract Model are supported however it is not mutually exclusive of the HTTP, or any other, Realization: a server may implement multiple Realizations in parallel as long as each Realization fully supports the Abstract Model.

Unlike the HTTP-header Realization which is also the subject of an independent IETF document [[PROF-IETF]], this QSA Realization is fully specified here. Two forms of this QSA approach are presented too: the first is the fixed keyword "QSA Realization" and the second is the "QSA Alternate Keywords Realization" according to which servers may implement any keywords they choose. These two forms, the Abstract Model and the HTTP Realization are all identified in .

QSA URI description

A query string is a part of a URL 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. Query string key/value pairs are separated from the scheme, authority and path of a URI by a question mark symbol, ?, and consist of key/value pairs connected by an equals symbol, =, and separated from each other key/value pair by an ampersand symbol, &, as per [[RFC3986]].

An example URI with profile negotiation by QSA demonstration elements is:

http://example.com/path/to/resource/a?_profile=prof-01&_mediatype=text/turtle

In the example URI with QSA above, the profile requested for the resource representation is indicated by the token prof-01 and the Media Type is RDF (turtle) indicated by the IANA Media Types list token text/turtle. As per 's allowance, a token is used here to identify the profile - prof-01 - but that token MUST be mappable to a URI within one particular client/server session and mechanics for that are described below.

If Query String Arguments may use URIs (or URLs) to convey important information, implementers should ensure that the total length of the total requesting URI within which the QSAs using URIs/URLs exist does not exceed length restrictions. [[RFC7230]]'s §3.1.1 recommends that senders and recipients support request lines of at least 8,000 octets. Some client and server implementations, however, cannot accept URLs longer than 2,000 characters, for example, the Sitemap protocol which has a length limit of 2,048 characters in a URL. Cf. this question on stackoverflow for a longer discussion of issues related to URL length.
Key naming

This Realization includes two different profiles of this specification that describe two different conformance targets which are differentiated by the QSA key naming. The two profiles are the "QSA Realization" and "QSA Alternate Keywords Realization" (see ).

To conform to the "QSA Realization" profile, the QSA key _profile MUST be used to indicate a profile token or URI and _mediatype MUST be used to indicate a resource representation's Media Type.

When conforming to the profile "QSA Alternate Keywords Realization", any key values to indicate profile and Media Type MAY be used, however this profile requires that a mechanism to discover what keys are used MUST be supplied and this is detailed below in .

Token and URI use

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 and this specification indicates that implementers SHOULD use tokens from that list for Media Type identifiers.

There is no proposal to create a central register of profiles, as this is thought by these authors to be unsustainable in the long term, given the likely numbers of profiles to be established and likely community- specific nature of profiles (individual communities will create profiles for their own needs that will not be widely relevant).

For this reason, the QSA Realizations of this specification allow universally unique and un-registered (no central registry) identifiers to be used for profiles. These identifiers MAY be either URIs or tokens. If tokens are used, there MUST exist a 1:1 mapping per resource and session between profile tokens and profile URIs that is discoverable by clients.

Several initiatives exist that have created URIs for Media Types, such as conneg.info based on IANA's tokens. As per the URI or token allowance for profiles, these URIs MAY be used to indicate Media Types.

Resource URL

Resource URLs for which QSA-based profile negotiation is taking place SHOULD NOT themselves be QSA values of other resource URIs in any QSA-based realization. Such mechanics may be used internally and are used by legacy systems for profile negotiation but are best hidden from to the client applications to make conformance to these QSA profiles more recognizable. shows this.

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

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

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

list profiles

For conformance to the "QSA Realization Profile", the _profile QSA key SHOULD be supported by the server to allow a client to make a list profiles request. For this request, the reserved token all SHOULD be used, e.g. _profile=all.

For conformance to the "QSA Alternate Keywords Realization", other key/value pairs MAY be used, such as _view=alternates but then the implementing server MUST supply a means of discovering that key, as per .

The server's response to a list profiles request SHOULD be to present a list of all profiles that it supports representations of the resource for and optionally also supported Media Types for those representations.

The server SHOULD represent the alternate profiles information in the HTTP header of the response, as per the HTTP Realization (using a Link header) and it MAY also represent the information in the response body in place of the default profile representation of a resource. This body content allowance is to enable humans to read alternate profile-conformant representation options for a resource easily in a web browser without having to view lower-level HTTP information.

Where a server does provide alternate profiles information in an HTTP body, the server MAY allow clients to negotiate for particular Media Types of the response by using the same Media Type negotiation method used for the get resource by profile function below.

An example request for the alternate profile representations of a resource to be delivered as HTTP body content as well as HTTP header content in the JSON format could look like

GET /resource/a?_profile=all&_mediatype=application/json HTTP/1.1

---

# The response shows that representations of the resource can be delivered according
# to two profiles identified by the tokens profile-x & profile-y
# and that profile-x-conformant representations are available in XML & JSON
# where as profile-y-conformant representations are only available in XML

# The content in the JSON body of the response is equivalent to that of the Link header

# Both the Link header and the JSON body include profile URI/token mappings

HTTP/1.1 200 OK
Content-Type: application/json
Content-Profile: <http://www.w3.org/ns/dx/conneg/profile/qsa>
Link:
  <http://example.org/resource/a?_profile=profile-x&_mediatype=application/json>;
          rel="self"; type="text/html";
          profile="http://otherexample.org/profile/x",
  <http://example.org/resource/a?_profile=profile-x&_mediatype=text/xml>;
          rel="alternate";
          type="text/xml";
          profile="http://otherexample.org/profile/x",
  <http://example.org/resource/a?_profile=profile-y&_mediatype=text/xml>;
          rel="alternate";
          type="text/xml";
          profile="http://otherexample.org/profile/y"

{
    "resource": "http://example.org/resource/a",
    "profiles": [
        {
            "token": "profile-x",
            "uri": "http://otherexample.org/profile/x",
            "media_types": ["application/json", "text/xml"]
        },
        {
            "token": "profile-y",
            "uri": "http://otherexample.org/profile/y",
            "media_types": ["text/xml"]
        }
    ]
}
        

get resource by profile

To be conformant with the "QSA Realization" profile of this specification, a server MUST allow clients to request resources according to profiles they identify with a _profile query string. Since either tokens or URIs may be used to identify a profile, servers MUST accept either. Servers MAY accept both encoded and un-encoded URIs but MAY also only accept one or the other.

To be conformant with the "QSA Alternate Keywords Realization" profile of this specification, a server MUST allow clients to request resources according to profiles they identify with a key of the server implementor's choosing but then the server MUST also supply a means of discovering that key, as per .

A QSA server implementing get resource by profile SHOULD allow a client to indicate profile preferences by allowing ordered profile identifiers in the QSA key/value pair for profiles. For example, a client preferring profile-z but also accepting profile-y and profile-x, in that preference order, could make a request using comma separation of the profile tokes, such as GET /resource/a?_profile=profile-z,profile-y,profile-x.

Servers SHOULD support any combination of profile URIs or tokens for this (e.g. profile-z,http://example.org/profile/x,profile-y) and SHOULD return resource representations according to preference. Servers MUST indicate the profile actually returned by including a Content-Profile HTTP header in the response and MAY also indicate the returned profile in other ways. Servers SHOULD support escaped URIs and MAY also support un-escaped URIs identifying profiles, or both.

A server implementing multiple Media Type formats for its resource representations SHOULD allow a client to specify a preference order for them in a similar way.

QSA key discovery

This function is only relevant for servers claiming conformance to the "QSA Alternate Keywords Realization" profile of this specification.

Servers claiming conformance to the "QSA Alternate Keywords Realization" MUST implement methods to allow clients to discover the QSA keys used in place of the "QSA Realization" profile's _profile and _mediatype and also the equivalent of the _profile=all key/value combination. This allows clients with little knowledge of the server to discover how to create list profile and get resource by profile requests.

A server responding to any request for a resource for which "QSA Alternate Keywords Realization" is supported SHOULD include HTTP headers that indicate alternate profiles and Media Types, as per the HTTP Realization. They MAY instead, or in addition, provide HTTP body content indicating the same information. If they do, such information SHOULD be present in the default response to a URI request, i.e. in response to a request without any QSAs. A series of example requests is given in .

# A client makes a request for Resource A not knowing if any Content
# Negotiation by Profile is supported. It supplies an Accept-Profile
# header just in case. For extra efficiency, the client could have
# made a HEAD request instead of a GET

GET /resource/a HTTP/1.1
Accept-Profile: http://example.org/profile/x

# The server does not understand the HTTP Get Resource By Profile
# request (doesn't support the HTTP Realization) but is able to
# supply an HTTP Link header indicating alternate profiles. It can be
# seen from the Link header that keys other than _profile &
# _mediatype are in use - view & format - thus this is QSA Alt, not a
# QSA Realization-conformant system

# The resource representations available conform to profile-x & profile-y.
# The profile-y-conformant representation is only available in XML

HTTP/1.1 200 OK
Link:
  <http://example.org/resource/a?view=profile-x>;
          rel="self";
          type="text/html";
          profile="http://otherexample.org/profile/x",
  <http://example.org/resource/a?view=profile-y&format=text/xml>;
          rel="alternate";
          type="text/xml";
          profile="http://otherexample.org/profile/y",

# Note that here the server does not directly indicate the profile served
# (there is no Content-Profile header present) but this can be inferred
# by the link header with rel="self"
        

While the Link header response above communicates all the information that a list profiles request does, it is not visible directly in a web browser. While shows a requests/response pair that include equivalent Link header and HTTP body information listing profiles, the latter of which is visible in a browser, it is dependent on a client knowing that the QSA key/value pair _profile=all is used to trigger this response as opposed to the server's default resource representation.

To communicate to a client what QSA key/value pair is used for list profiles when the "QSA Alternate Keywords Realization" is conformed to, a server SHOULD...

Nick: it appears we are dependent on an identifier for the "profile of a resource that lists all others profiles". This is analogous in content to the Link header response for list profiles and is exactly what the existing QSA systems respond with when asked for ?_view=alternates and what is given above as ?_profile=all. So it's a URI that is equivalent to the QSA Realization profile's token of all.

If we had such a URI, I would be able to say something like a Link header response should include this to indicate how a client can show how to trigger ?_profile=all (list profiles):

Link:
    <http://example.org/resource/a>;
      rel="self";
      type="text/turtle";
      profile="urn:example:profile:x",
    <http://example.org/resource/a>;
      rel="alternate";
      type="text/turtle";
      profile="http://example.org/profile/alternates",
    <http://example.org/resource/a>;
      rel="alternate";
      type="text/turtle";
      profile="urn:example:profile:y",
    <http://example.org/resource/a>;
      rel="alternate";
      type="application/xml";
      profile="urn:example:profile:x",
    <http://example.org/resource/a>;
      rel="alternate";
      type="application/xml";
      profile="urn:example:profile:y",
    <http://example.org/resource/a>;
      rel="alternate";
      type="text/html"
            

The bolded part of the Link header above is the alternate profile for the resource that lists other profiles which we know since the profile identifier is http://example.org/profile/alternates in some format (here text/turtle.

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.

Acknowledgements

The editors gratefully acknowledge the contributions made to this document by all members of the Dataset Exchange Working Group, especially Annette Greiner.

The editors would also like to thank the following non-Working Group people for supplying comments which were used to improve this document: Erik Wilde, Gregg Kellogg & Irene Polikoff.

Special thanks must be given to Kam Hay Fung for his most extensive comments and suggestions which found and fixed issues for us.

Finally, the editors thank the chairs of the Dataset Exchange Working Group: Peter Winstanley & Karen Coyle.

Changes

Changes since the 18 December 2018 Working Draft are:

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. Further, offering a list of acceptable profiles at the beginning of a negotiation process can reveal information about the user's interests that could be used to add such information to a user profile.

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. 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. 261

RESPONSE FOR Req. 265

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

RESPONSE FOR Req. 266

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. 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

Issue Summary

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: