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.
Status of This Document
This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at https://www.w3.org/TR/.
This document was published by the Dataset Exchange Working Group as
a Working Draft.
This document is intended to become a W3C Recommendation.
Publication as a Working Draft does not imply endorsement by the
W3C Membership. This is a draft document and may be updated, replaced or
obsoleted by other documents at any time. It is inappropriate to cite this
document as other than work in progress.
This document was produced by a group
operating under the
W3C Patent Policy.
W3C maintains a
public list of any patent disclosures
made in connection with the deliverables of
the group; that page also includes
instructions for disclosing a patent. An individual who has actual
knowledge of a patent which the individual believes contains
Essential Claim(s)
must disclose the information in accordance with
section 6 of the W3C Patent Policy.
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:
[PROF-GUIDANCE] the top-level general recommendations and guidance on profiling.
It gives an overview of all DXWG documents on profiles and is the recommended starting point
[PROF] an RDF vocabulary that describes profiles and related resources
[PROF-CONNEG] this document, specific guidance on how to negotiate for Internet resource content using profiles
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:
an Accept header specifying preferred Media Types which the server may or may not supply
an Accept-Encoding header to request that a specific content encoding system be used
an Accept-Language header to indicate a preferred language
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, information about an online book might adhere to the Dublin Core Terms [DCTERMS] metadata
specification with each field, 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.
2. Conformance
As well as sections marked as non-normative, all authoring guidelines,
diagrams, examples, and notes in this specification are non-normative.
Everything else in this specification is normative.
The key words MAY, MUST, MUST NOT, RECOMMENDED, and SHOULD
are to be interpreted as described in
[RFC2119].
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".
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
4. Motivation
This section is non-normative.
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.
5. Related Work
This section is non-normative.
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.
5.1 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 [RFC7231]
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.
Example 1: Using the profile parameter in an Accept header together with the Accept-Profile header
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 [RFC8288] 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 [RFC6906].
[RFC6906] 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).
Example 2: Using a Link header with a profile parameter
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 [RFC7240]
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.
Example 3: Using a Link header with a profile parameter
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.
5.2 Archival Resource Key (ARK)
ARK (Archival Resource Key) [ARK] is an identifier scheme
for the persistent identification of information objects.
ARK identifiers can contain an optional qualifier
"that extends the base ARK in order to create a kind of service entry point
into the object named by the NAA [sc. Name Assigning Authority]."
Through a qualifier, any NMA (Name Mapping Authority, a service provider offering ARK resolution)
can supply access to variants of that object.
The set of qualifiers is open and any ARK NAA or NMA can invent its own.
The ARK specification lists versions, languages and formats as examples of qualifiers (§2.5)
and a profile name could be used as a qualifier
to refer to a representation of an information object conforming to that specific profile.
For example, the URI https://api.istex.fr/ark:/67375/6GQ-MLC8GRWC-5/
lists different XML encodings of metadata for the resource identified by the ARK 67375/6GQ-MLC8GRWC-5,
according to different XML vocabularies, including "MODS", the Library of Congress'
Metadata Object Description Schema.
This issue was created in the Conneg by Profile document and is listed in it. Once consensus on addressing it is reached here in comments below, the results will be added to the document and the issue closed.
5.3 Linked Data APIs
Several Linked Data API tools provide access to different representations of resources, identified by URI, via
use of Query String Arguments (QSAs). Two examples are the
ELDA tool by Epimorphics, an
implementation of the Linked
Data API specification created by the government of the United Kingdom, and the pyLDAPI Python
Linked Data API implementation by CSIRO. Both of these tools allow the
listing of views and formats available for a resource by dereferencing the URL created by
adding the QSA _view=alternates to the resource URI. The
view named alternates is a special view available for all resources.
What these tools call a view is analogous to a profile and a format to an HTTP Media Type.
This issue was created in the Conneg by Profile document and is listed in it. Once consensus on addressing it is reached here in comments below, the results will be added to the document and the issue closed.
5.4 OAI-PMH
The Open Archives Initiative Protocol for Metadata Harvesting [OAI-PMH] "...provides an
application-independent interoperability framework based on metadata harvesting." In doing this, OAI-PMH
specifies Query String Argument-based "Protocol Requests and Responses" that allow clients of
Data Providers to: retrieve the metadata formats available from a repository
(ListMetadataFormats); retrieve metadata for an identified record (GetRecord),
according to an identified metadata profile; perform a number of other repository interrogation tasks; and to
harvest collections of record's metadata, filtered by parameters such as modified date.
OAI-PMH requires that representations of all resources in a repository are available according to the same set
of profiles. It is also entirely XML-based so that profiles, or "metadata formats" as they are called in OAI-PMH, must
all be presented in XML and the content of an XML representation of a resource is presented within an XML
envelope that always identifies the record, the profile, the OAI-PMH method used, the request time and other
common metadata.
This issue was created in the Conneg by Profile document and is listed in it. Once consensus on addressing it is reached here in comments below, the results will be added to the document and the issue closed.
5.5 Catalogue Service for the Web (CSW)
[CSW] is the OGC standard used world-wide by the geospatial community to implement a machine-actionable interface
to catalog services, providing access to metadata about datasets, geospatial services ([WMS], [WFS], etc.),
as well as other types of resources. Besides supporting common functions such as free-text and faceted search, CSW supports the retrieval of metadata according to a given metadata schema and format, indicated respectively by using outputSchema and outputFormat query parameters. Commonly supported metadata schemas are [DC11], and [ISO-19115], and the default format is XML. A given CSW instance's supported metadata schemas and formats are described in the service "capabilities" -- a machine-readable description of the service interface, that is returned via a GetCapabilities request.
Notably, CSW theoretically supports HTTP content negotiation for the metadata format, and the specification defines a conflict resolution mechanism for requests where this information is specified both via HTTP Accept headers and the outputFormat parameter (see Section 6.2 of the OGC CSW 3.0 specification - HTTP Protocol Binding).
6. 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.
6.1 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 clientrequesting the representation of a resource conforming to a profileMUST 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.
6.2 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.
list profiles
a client requests the list of URIs of profiles for which a server is able to deliver
conformant resources
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.
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
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.
6.2.1 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 profilesrequestMUST be either an independent request or part of another
realization's request.
The list profilesrequestMAY 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 serverMUST NOT list profiles that resource representations conform to if
it is unable to deliver those representations when presented with a get resource by profilerequest.
Issue 602: Explore whether list_profiles operation could be provided by an external component profile-negotiation
Many existing systems that support use of alternative information profiles do not provide an explicit list. However, external catalogues or other sources of metadata may provide this list, and the server may perform negotiation over a specific request.
Feedback is sought on whether this should be deemed mandatory.
6.2.2 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 profilerequestMUST
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 profileMAYrequest 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.
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.
Example 4: Get resource by profile, narrower profile response (HTTP realization)
# 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]
We were unsure what to make of "inheritance", as we are not aware of any generalized notion of inheritance that would make sense across implementation technologies. It would be helpful to motivate this with a testable use case, e.g., a server implementation which responds to Accept-Profile by calculating the "best" response for processing a Profile Ontology description. A test of inheritance would include the notion that inheriting imposes further constraints, and that the entity being inherited from may in turn inherit from something else. ShEx shape inheritance has this behavior.
7. 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.
Note: Realization requirements
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.
7.1 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].
Issue 500: Consider requirements for specifying the order in which content negotiation is performed profile-negotiation
It would appear that it will necessary to negotiate for profile before language or content-type. Memento specifies that time-based negotiation MUST take place before any other negotiation.
7.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 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 / Profile
urn:example:profile:1
urn:example:profile:2
text/html
http://example.org/a/resource.html
http://example.org/a/resource.html
text/turtle
http://example.org/a/resource.prof1.ttl
http://example.org/a/resource.prof2.ttl
application/xml
http://example.org/a/resource.prof1.xml
http://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:
Example 5: Using a Link-header to point to a list of available profiles
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.
Example 6: HTTP headers with profile URI / token mappings using 'token' parameters
# 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]
Note: Multiple ways of conveying URI / token mappings
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:
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:
In 7.1.3 (https://www.w3.org/TR/dx-prof-conneg/#listprofilestokenshttp), if the QSA approach is aimed at reducing the use of HTTP headers for humans, in what shape and form (e.g. media type) would a list of profiles be returned for a QSA based query instead of using HTTP headers? Should there be a convention?
7.1.2 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).
Example 7: Requesting a representation conforming to a specific profile using HTTP 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.
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.
If the QSA realisation of the profile conneg Abstract Model (https://w3c.github.io/dxwg/conneg-by-ap/#abstractmodel) doesn't mandate the use of particular QSA keys (such as _profile & _mediatype) then it needs to provide a way for users to discover what QSA keys are used.
While the HTTP-header approach to profiles enables fully automated retrieval of data conforming
to a desired profile, it is also advisable to enable humans to select data by profile without
requiring direct manipulation of request header content. This can be accomplished by existing
web development methods where an API supports a graphical interface. The user can be presented
with a list of available profiles and given the choice of which to retrieve for the dataset of
interest. They can even be asked to indicate a ranked choice of possible profiles, which could
then be used to retrieve multiple resources' data matching a query.
As one example of how an API for such a service can be implemented, a Query String Argument (QSA)
realization of the Abstract Model is presented here. Unlike the HTTP-header
realization, which is also the subject of an independent IETF document [PROF-IETF], this realization
is fully specified here but it is not normative. This realization does not preclude other URL schemes,
or even other QSA schemes, for profile negotiation, the general requirement being that any scheme
implements the functions of the Abstract Model. Whatever specific scheme is used, it should be fully
documented and discoverable.
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.
Note: Maximum length of URLs
Since Query String Arguments use URIs (or URLs) to convey important information,
implementers should ensure that the total length of the URL
does not exceed possible length restrictions.
[RFC7230] §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
and e. g. the Sitemap protocol 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.
Many systems use query string argument (QSA) to control profiles of representations to be returned - even when not using this terminology. whilst much of this is ad-hoc, standard API specifications may include canonical parameter names for these concepts. The specification proposed here is a recommendation in the absence of an alternative. The implication however is that a canonical means to discover mappings between other APIs and the Abstract Model is required.
When content negotiation by profile is to take place using QSAs, the requests and responses
of the Abstract Model can be implemented by using key/value pairs using key terms of the implementer's choosing.
In this realization, _profile and _mediatype are used
to indicate a single profile or a list of
preference-ordered profiles, or one or more Media types, respectively, with profiles or Media Types indicated by either URI or
token.
Note: Current use of tokens for negotiation by Media Type
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
unsustainable in the long term, given the likely numbers of profiles to be established.
For this reason, this QSA realization allows either URIs or tokens for profiles to be used, and it is expected that other URL-based 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 registry's tokens.
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 but are best kept transparent to the
realization's client applications.
Example 8: Resource URLs must not, themselves, be parameters of other URLs
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
7.2.1 list profiles
A QSA with a fixed value such as _profile=list should be supported by the server to allow a client to
make a list profilesrequest.
Other QSA key/value pairs can be used, such as _view=alternates, as long as this is discoverable.
The complete request for the profiles to which a resource's representations conform can thus be
communicated in a single URL like thus:
Example 9: Requesting a list of profiles for a resource by QSA
GET /a/resource?_profile=list HTTP/1.1
where /a/resource is the URL of the resource for which the list of available profiles is
requested
It's possible for a client making this request to negotiate for particular formats of the response by
using a QSA equivalent to the HTTP Accept header to indicate a Media Type. The server
would implement a _mediatype QSA for this but might offer an alternative, such
as _format, as long as this is discoverable.
An example profile listing for a resource in HTML would look like:
Example 10: Requesting a list of profiles for a resource by QSA in HTML
GET /a/resource?_profile=list&_mediatype=text/html HTTP/1.1
7.2.2 get resource by profile
Issue: To be completed
Expressing profile preference
A server implementing profile listing for resources could allow the
requester to indicate preferences by allowing the QSA indicating the desired
profile, e.g., _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:
Example 11: Requesting a list of profiles for a resource by QSA in HTML
GET /a/resource?_profile=aaa,bbb,ccc HTTP/1.1
Servers can 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 would need to be escaped.
Similarly, a server implementing multiple Media Type return formats for its 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) can be specified in a comma-separated list form, most preferred to least, such that
a client requesting profiles as aaa,bbb,ccc will receive a resource that meets the requirements of profile
aaa if it is available, else one that meets profile bbb if that is available, and so on.
8. 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.
This issue was created in the Conneg by Profile document and is listed in it. Once consensus on addressing it is reached here in comments below, the results will be added to the document and the issue closed.
9. Implementations
This section is non-normative.
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.
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.
Added a not about length restrictions in URLs to the QSA section.
(Issue 592)
12. Security and Privacy
This section is non-normative.
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.
This section lists, and then addresses, individual requirements that the Dataset Exchange Working Group
considered important for content negotiation by profile.
Note
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.
Create a sufficiently wide definition of an application profile to address declaration of interoperability profiles data may conform to, and through this mechanism provide the means for DCAT instances and collections to also declare the profiles of DCAT they conform to.
These Use case specific requirements apply to the required scope of this definition. Where appropriate these are also captured as additional requirements.
Clarify any relationship between profiles and validation languages
Profiles have URI identifiers that resolve to more detailed descriptions
Each application profile needs to be documented, preferably by showing/reusing what is common across profiles
Profiles should provide both machine and human readable views.
Profiles may inherit clauses from one or more parent profiles
Profiles must support a view that includes all inherited constraints clearly identifying the parent profile the constraint is defined in.
Profiles may be used to describe the metadata standard a description conforms to, the standards to which the resource described (e.g. dataset) and the standards each distribution conforms to.
Conceptually, profiles can extend other vocabularies or profiles, or can be refinements of other vocabularies or profiles (#ID37)
Responses can conform to multiple, modular profiles (#ID3)
Create a way to list the profiles implemented by a dataset or a specific distribution
Some subset of profile metadata that can be included in a DCAT context should have a canonical set of properties recommended. Initial requirements are 1) short definition 2) input and editing guidance. Links should be consistent with#RPFRP
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.
Note
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:
an approach suggested is to provide an alternate view resource for the original
resource located at RESOURCE_URL + ?_view=alternates which lists, at a minimum, the
profiles, media types (formats) & languages available, as per the
alternate views guidance.
This issue was created in the Conneg by Profile document and is listed in it. Once consensus on addressing it is reached here in comments below, the results will be added to the document and the issue closed.
Is DCAT expecting to implement a profile of ProfileDesc or a DCAT-aligned set of terminology or will it follow the vocabulary as-is?
In the draft version of the conneg document, the Requirement #73 is answered by addressing the general case (profile listing of a resource) and then notes are given on the DCAT-specific answer given that the Requirement gives DCAT listing of profiles as the motivation.
If DCAT is to adopt the general, ProfileDesc mechanics of profile listing, no special menthoin needs to be made.
If DCAT is to adopt specialised terminology (profileing ProfileDesc) then what reference, if any from DCAT to ProfileDesc needs to be made?
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.
Some media types already have a profile parameter, such as JSON-LD. The profile negotiation deliverable should define how conflicts between it's syntax and profiles specified in the media type are handled.
For example, a server would need to deterministically handle:
Suggested re-wording: a profile must have an identifier
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.
Issue 289: When requesting a representation, a client must be able to specify which profile it prefers the representation to adhere to. This information about the requested profile is not a replacement for content type (e. g. application/xml), language (e. g. zh-Hant) or any other negotiated dimension of the representation. [ID5] (5.5) ON HOLD profile-guidanceplenary-approvedrequirementrequires discussion
Entered from Google Doc.
Suggested re-wording: "When requesting a representation, a client must be able to specify which profile it prefers the representation to adhere to. This information about the requested profile is not a replacement for content type (e. g. application/xml), language (e. g. zh-Hant) or any other negotiated dimension of the representation."
Issue 602: Explore whether list_profiles operation could be provided by an external component
Issue 748: Add an example of a Client/Server scenario demonstrating profile inheritence
Issue 500: Consider requirements for specifying the order in which content negotiation is performed
Issue 290: A short token to specify a profile may be used as long as there is a discoverable mapping from it to the profile's identifying URI [ID5] (5.5)
Issue 904: Decide on a way of conveying URI / token mappings
Issue 261: Define conneg interaction with media types that have a profile param
Issue 265: Enable the ability to negotiate the data profile via http, similar to the negotiation of data formats today. [ID30] (5.30)
Issue 266: There need to be an http-based mechanism to point to representations conforming to other profiles [ID30] (5.30)
Issue 284: A profile must have an identifier that can be served with a response to an API or http request. [ID2] (5.2)
Issue 286: There should be a way to look up additional information about a profile - this may be machine readable for run-time mediation or used to develop or configure a client [ID2] (5.2)
Issue 288: Profiles offered by a service must be discoverable through a machine-readable graph of metadata that describes what is offered and how to invoke the offered profiles. [ID5] (5.5)
Issue 289: When requesting a representation, a client must be able to specify which profile it prefers the representation to adhere to. This information about the requested profile is not a replacement for content type (e. g. application/xml), language (e. g. zh-Hant) or any other negotiated dimension of the representation. [ID5] (5.5)
Issue 290: A short token to specify a profile may be used as long as there is a discoverable mapping from it to the profile's identifying URI [ID5] (5.5)
A.3 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: