Media Types | Agents || Home | About | Content Negotiation by Profile

Content Negotiation by Profile implementation

Table of Contents

§ Introduction

This system implements the functions of the W3C's Content Negotiation by Profile specification. That specification "describes how Internet clients may negotiate for content provided by servers based on data profiles to which the content conforms".

The Content Negotiation by Profile (ConnegP) specification includes several Functional Profiles of its abstract specification that indicate how to implement it in specific environments and all implementations of the specification need to conform to one or more of these, or elsewhere defined, Functional Profiles. This system implements several Functional Profiles of ConnegP, in fact all of those listed in the specification.

In addition to implementing Functional Profiles, this system also implements the HTTP Link header attributes used to associate profile tokens with profile URIs and it also demonstrates indication of conformance to Functional Profiles.

Documentation Style

Quoting from Content Negotiation by Profile

Where text is quoted directly from the Content Negotiation by Profile specification, it is indicated like this:

This document describes how Internet clients may negotiate for content provided by servers based on data profiles to which the content conforms.

Demonstration Commands

Where an HTTP request that includes headers or other commands difficult to type into browser address bars is needed to demonstrate ConnegP functions, the function calls given here use the cURL program. cURL is a command line tool available on many platforms for making HTTP requests.

An example request is this one for obtaining the Turtle format response from URI http://example.org/eg where '$' indicates teh command prompt:

$ curl --header 'Accept: text/turtle' http://example.org/eg

The following cURL command follows any redirects and retrieves just HTTP header information:

$ curl -IL --header 'Accept: text/turtle' http://example.org/eg

The redirect following is necissary since all URIs from https:/w3id.org/mediatype/ redirect to this system.

§ Functional Profiles implemented

This system fully implements the following ConnegP Functional Profiles described in ConnegP's § 7.2 Conformance to Functional Profiles:

  1. HTTP Headers Functional Profile
  2. QSA Functional Profile
  3. QSA Alternate Keywords Functional Profile
  4. Resource Representation Description

The following sections describe the implementation, per Functional Profile.

1. HTTP Headers Functional Profile

The functions list profiles & get resource by profile are implemented as follows:

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

For a request for any Media Type, e.g. Notation-3 https://w3id.org/mediatype/text/n3, a Link header with the following information is returned:

      <https://w3id.org/mediatype/text/n3?_view=mt>; rel="self"; type="text/html"; profile="https://w3id.org/profile/mediatype",
      <https://w3id.org/mediatype/text/n3?_view=mt>; rel="alternate"; type="text/turtle"; profile="https://w3id.org/profile/mediatype",
      <https://w3id.org/mediatype/text/n3?_view=mt>; rel="alternate"; type="application/rdf+xml"; profile="https://w3id.org/profile/mediatype",
      <https://w3id.org/mediatype/text/n3?_view=mt>; rel="alternate"; type="application/ld+json"; profile="https://w3id.org/profile/mediatype",
      <https://w3id.org/mediatype/text/n3?_view=mt>; rel="alternate"; type="text/n3"; profile="https://w3id.org/profile/mediatype",
      <https://w3id.org/mediatype/text/n3?_view=mt>; rel="alternate"; type="application/n-triples"; profile="https://w3id.org/profile/mediatype",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="text/html"; profile="https://w3id.org/profile/alternates",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="application/json"; profile="https://w3id.org/profile/alternates",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="text/turtle"; profile="https://w3id.org/profile/alternates",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="application/rdf+xml"; profile="https://w3id.org/profile/alternates",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="application/ld+json"; profile="https://w3id.org/profile/alternates",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="text/n3"; profile="https://w3id.org/profile/alternates",
      <https://w3id.org/mediatype/text/n3?_view=alternates>; rel="alternate"; type="application/n-triples"; profile="https://w3id.org/profile/alternates"
              

Here the returned representation is be identified by rel="self" and other representations by rel="alternate", as required. The target URIs (the first part of the Link headers above) are the URIs of the item requested + a query string. HTTP content negotiation with or without those query strings works for get resource by profile but they are included as they work for other Functional Profile implementations.

This style of response works for the following resource types handled by this server:

  1. Media Type - e.g. https://w3id.org/mediatype/text/n3
  2. Agent - e.g. https://w3id.org/mediatype/agent/W3C
  3. Register - the Register of Media Types and the Register of Agents
  4. Dataset - this system as a whole can be considered to contain a dcat:Dataset for which list profiles can be obtained at https://conneg.info/mediatypes/.

1.2 get resource by profile

...issuing an HTTP GET request against the resource and specifying the desired profile URI in an Accept-Profile header. URIs MUST be enclosed in angled brackets, '<' & '>'. It is possible to specify a range of acceptable profile URIs and, when using multiple URIs, they MUST be delimited by a comma be in separate Accept-Profile headers. Preferences may be indicated by using quality indicators (q-values) as an ordering mechanism separated from the URI by a semi-colon, ';'. An example of a URI (in this case a URN) with a q-value is <urn:example:profile:x>;q=1.0, where the URI is <urn:example:profile:x> and the q-value is q=1.0."

For any of the following types, this server will handle get resource by profile as per this specification:

  1. Media Type - e.g. https://w3id.org/mediatype/text/n3
    • to get the "Media Types" profile:
    • $ curl -L --header 'Accept-Profile: <https://w3id.org/profile/mediatype>' https://w3id.org/mediatype/text/n3
  2. Agent - e.g. https://w3id.org/mediatype/agent/W3C
    • to get the "Alternates View" profile in the Turtle format:
    • $ curl -L --header 'Accept-Profile: <https://w3id.org/profile/alternates>' --header 'Accept: text/turtle' https://w3id.org/mediatype/agent/W3C
  3. Register - e.g. Media Types register https://w3id.org/mediatype/
    • to get the "Registry Ontology" profile in JSON-LD:
    • $ curl -L --header 'Accept-Profile: <http://purl.org/linked-data/registry>' --header 'Accept: application/ld+json' https://w3id.org/mediatype/
    • to get the default profile, which is the "Registry Ontology" profile in RDF/XML:
    • $ curl -L --header 'Accept: application/rdf+xml' https://w3id.org/mediatype/
  4. Dataset - (this whole system's content) https://conneg.info/mediatypes
    • to get the "VOID Ontology" profile in text/turtle or, if not supplied, the "DCAT Vocabulary" profile in text/turtle:
    • $ curl -L --header 'Accept-Profile: <http://rdfs.org/ns/void>, <http://www.w3.org/ns/dcat>' --header 'Accept: text/turtle' https://conneg.info/mediatypes
      • you will get the VOID content, since it;s available
    • to get the "Registry Ontology" profile in text/turtle or, if not supplied, the "DCAT Vocabulary" profile in text/turtle but with preference indicate not by order but by q values (with Registry Ontology higher):
    • $ curl -L --header 'Accept-Profile: <http://rdfs.org/ns/void>;q=0.5, <http://www.w3.org/ns/dcat>;q=0.1, <http://purl.org/linked-data/registry>;q=0.9' --header 'Accept: text/turtle' https://conneg.info/mediatypes
      • you will get the VOID content, since it;s available

2. Query String Arguments Functional Profile

2.1 list profiles

For conformance to the "QSA Functional 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.

Implementations of this specification according to the QSA Functional Profiles MUST communicate their alternate representations information as per the Alternate Representations Data Model. They MAY do so using HTTP Link headers, as per the HTTP Functional Profile, or they MAY use other approaches.

As per the HTTP list profiles implementation, this functionality is supported for all four resource types delivered by this system: Media Type, Agent, Register, Dataset.

  1. An example request for list profiles for the Media Type resource text/n3 is:
  2. An example request for list profiles for the whole Dataset in the application/ld+json format (Media Type) is:

2.2 get resource by profile

To be conformant with the "QSA Functional Profile" 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. URIs MUST be enclosed in angled brackets, '<' & '>'.

  1. An example request for the Media Type text/n3 Alternate Views-conformant representation is:
    • https://w3id.org/mediatype/text/n3&_profile=alternates
    • Note that the Content-Profile header gives a value of https://w3id.org/profile/alternates which is indeed the URI for the profile indicated by the token alternates and this can be cross-checked with the Link header's profile token/URI mappings
  2. An example request for the Media Type text/n3 specifying a q-value-weighted list of profile identifiers, some tokens, some URIs, is:

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

  1. An example request for the Media Type text/n3 Alternate Views-conformant representation, in the allpication/rdf+xml Media Type (format) is:

3. Query String Arguments Alternative Keywords Functional Profile

When conforming to the profile "QSA Alternate Keywords Functional Profile", any key values acceptable within the specification of [RFC3986] MAY be used to indicate the desired profile.

3.1 list profiles

  1. An example request for list profiles for the Media Type resource text/n3 using the alternate keyword and value _view in place of _profile, but still using the value all is:
    • https://w3id.org/mediatype/text/n3?_view=all
    • Note that this response's HTTP header conforms to the Alternate Representations Data Model, as per the HTTP Functional Profile, which is allowed for the QSA Alternate Keywords Functional Profile.
  2. An example request for list profiles for the whole Dataset in the application/ld+json format (Media Type) using _view=all and _format in place of _mediatype is:

3.2 get resource by profile

  1. An example request for the Media Type text/n3 Alternate Views-conformant representation using the keyword _view in place of _profile is:
    • https://w3id.org/mediatype/text/n3&_profile=alternates
    • Note that the Content-Profile header gives a value of https://w3id.org/profile/alternates which is indeed the URI for the profile indicated by the token alternates and this can be cross-checked with the Link header's profile token/URI mappings
  2. An example request for the Media Type text/n3 specifying a q-value-weighted list of profile identifiers, some tokens, some URIs, using the alternate profile-identifying keyword _view is:

3.3 key discovery

...servers conforming to this functional profile additionally MUST present a mechanism to allow clients to discover what value is used, as detailed below in § 7.4.4 QSA key discovery.

Servers claiming conformance to the "QSA Alternate Keywords Functional Profile" MUST implement methods to allow clients to discover the QSA key used in place of the "QSA Functional Profile"'s _profile and also the equivalent of the _profile=all that is required to be implemented by any 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 Functional Profile" is supported SHOULD include HTTP headers that indicate alternate profiles and Media Types, as per the HTTP Functional Profile.

  1. An example request for a resource is:
    • https://w3id.org/mediatype/text/n3
    • The HTTP headers of the response to this request do indicate alternate profiles and Media Types, as per the HTTP Functional Profile
    • Note that the HTTP Link headers include Query String Arguments within the target URIs like this:
      • <w3id.org/mediatype/text/n3?_view=alternates&_format=application/json>; rel="alternate"; type="application/json"; profile="https://w3id.org/profile/alternates",
    • This means the QSA _format can be understood to be being used in place of _mediatype, since it is indicateing the Media Type value ("type=""") and the QSA _view can be understood to be be being used in place of _profile, since it is indicating a token that is mapped, via other Link headers, to the profile URI ("profile=""")

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.

  1. For the example request above, https://w3id.org/mediatype/text/n3:
    • The default HTTP body content is for the so-called "Media Types" profile and contains HTML content stating: "Alternate Representations. See this content according to other profiles/views and Media Type/formats: Alternates View"
    • NOTE: this content is not present in non-default profile responses nor in non-default Media Type responses for the default profile.

Servers SHOULD also allow clients to discover the QSA keys used to indicate Media Type and other content negotiation dimensions.

  1. For the example request above, https://w3id.org/mediatype/text/n3:
    • Media Type (QSA keyword _mediatype) is indicated to be using _format in HTTP Link headers as well as in the Alternates View (an HTML rendering of the Alternate Representations Data Model)
    • The Alternates View also lists the _lang QSA as supplying negotiation by language.

To communicate to a client what QSA key/value pair is used for list profiles when the "QSA Alternate Keywords Functional Profile" is conformed to, a server SHOULD, following the methods above for list profiles communication, indicate that a representation of the resource is available that conforms to the Alternate Profiles Data Model...

  1. For the example request above, https://w3id.org/mediatype/text/n3:
    • Representations of the resource conforming to the Alternate Profiles Data Model is listed in the list profiles Link header response like this:
      <https://w3id.org/mediatype/text/n3?_view=all&_format=text/html>; rel="alternate"; type="text/html"; profile="http://www.w3.org/ns/dx/conneg/altr",
      <https://w3id.org/mediatype/text/n3?_view=all&_format=application/json>; rel="alternate"; type="application/json"; profile="http://www.w3.org/ns/dx/conneg/altr",
      <https://w3id.org/mediatype/text/n3?_view=all&_format=text/turtle>; rel="alternate"; type="text/turtle"; profile="http://www.w3.org/ns/dx/conneg/altr",
      <https://w3id.org/mediatype/text/n3?_view=all&_format=application/rdf+xml>; rel="alternate"; type="application/rdf+xml"; profile="http://www.w3.org/ns/dx/conneg/altr",
      <https://w3id.org/mediatype/text/n3?_view=all&_format=application/ld+json>; rel="alternate"; type="application/ld+json"; profile="http://www.w3.org/ns/dx/conneg/altr",
      <https://w3id.org/mediatype/text/n3?_view=all&_format=text/n3>; rel="alternate"; type="text/n3"; profile="http://www.w3.org/ns/dx/conneg/altr",
      <https://w3id.org/mediatype/text/n3?_view=all&_format=application/n-triples>; rel="alternate"; type="application/n-triples"; profile="http://www.w3.org/ns/dx/conneg/altr"
                                
    • The Alternate Profiles Data Model is identified by the profile URI http://www.w3.org/ns/dx/conneg/altr, as per § 7.4.4 QSA key discovery

4. Resource Representation Description

To be used if a resource representation is able to indicate which profile(s) it conforms to, in its appropriate functional profile, as per the abstract specification in § 6.3.2 get resource by profile.

  1. For all previous examples, every response returns a Content-Profile HTTP Link header that indicates the profile the resource representation conforms to.

§ Link Header - Token

This system makes use of tokens to identify profiles, both in get resource by profile requests and also in responses from the server, such as HTML versions of the Alternate Representations Data Model content for resources.

As per ConnegP's § 8. Link Attributes:

When used in a Link header field, the attribute token is used to specify a token that a client MAY use as an alternative to the full profile URI given in the anchor attribute.

It should be noted that the use of the token as an alternative to the profile URI is per default limited to the current resource (i. e. the resource identified by the current request URI). Servers MAY use a larger scope for their this but clients should not depend on that unless the server documentation explicitly gives other instructions through some other means.

A request for any resource delivered by this system returns a number of Link HTTP headers, including token headers.

  1. An example is that for a GET request for https://w3id.org/mediatype/text/n3, for the Media Type text/n3, the token Link is:
    <http://www.w3.org/ns/dx/prof/Profile>; rel="type"; token="all"; anchor=<http://www.w3.org/ns/dx/conneg/altr>, \
    <http://www.w3.org/ns/dx/prof/Profile>; rel="type"; token="alternates"; anchor=<https://w3id.org/profile/alternates>, \
    <http://www.w3.org/ns/dx/prof/Profile>; rel="type"; token="mt"; anchor=<https://w3id.org/profile/mediatype>
    Each of the three profiles for which conformant representations are available of the resource https://w3id.org/mediatype/text/n3 is available is given a Link header line with the tokens 'all', 'alternates' & 'mt' which map to the profiles, identified by URI http://www.w3.org/ns/dx/conneg/altr, https://w3id.org/profile/alternates & https://w3id.org/profile/mediatype respectively.

§ Indicating Conformance to Functional Profiles

This system advertises the Functional Profiles of ConnegP to which it conforms. As per ConnegP's § A.2 Demonstrating system conformance to Functional Profiles:

...it is possible for systems to show conformance to the this specification or any of the profiles by using mechanisms recommended in [PROF]. PROF's recommendation is that any resource, for example <http://example.org/resource/a>, wishing to claim conformance to a specification or a functional profile use the [DCTERMS] dct:conformsTo predicate like this:

<http://example.com/resource/a> dct:conformsTo <SPEC_OR_PROFILE_URI> .

Where [PROF] is The Profiles Vocabulary and [DCTERMS] is DCMI Metadata Terms.

Code Listing 2 in ConnegP shows an imaginary dcat:DataService indicating conformance to the QSA Alternate Keywords Functional Profile in this way.

  1. Resolving the top-level resource for this system, the service as a whole with URI https://conneg.info/mediatypes, and receiving it's default representation, conformant to DCAT 2, the following RDF can be obtained:
    <https://conneg.info/mediatypes>
        dct:conformsTo
            <http://www.w3.org/ns/dx/conneg/profile/http> ,
            <http://www.w3.org/ns/dx/conneg/profile/qsa> ,
            <http://www.w3.org/ns/dx/conneg/profile/qsa-alt> ,
            <http://www.w3.org/ns/dx/conneg/profile/rrd> ;
    This system claims conformance to all Functional Profiles listed in ConnegP's specification document.