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
First Public Working Draft.
This document is intended to become a W3C Recommendation.
Publication as a
First Public 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 part of a set of documents on profiles, edited by the W3C Dataset Exchange Working Group (DXWG).
Some of the documents are general while some are technology-specific:
[PROF-GUIDANCE] the top-level general profiling guidance document giving an overview of all other documents
[PROF-ONT] a document describing a formal ontology for describing objects related to profiles
[PROF-CONNEG] this document, including 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 addresses this functionality.
When online information about a resource adheres to one or more profiles, methods described here allow
clients to list those profiles and request content according to one or more of them in order of preference.
For example, information about an online book might adhere to the Dublin Core Terms [DCTERMS] metadata
specification with each field of information, such as title, description, author etc.,
being defined and formatted according to various Dublin Core elements (dct:title,
dct:description & dct:creator, respectively). Then, a request for the information about this
book may ask for the list of profiles according to which the metadata is available, or it may ask specifically for a response adhering to the
Dublin Core Terms. When no profile or an unsupported profile is requested, a server returns default content, that
is, content conforming to the default profile supported by the server.
When selecting a content negotiation mechanism, an Internet client may use the HTTP protocol but it may also use
other methods for providing instructions to a server,
such as URI Query String Arguments (QSAs).
QSAs are
established as useful for humans and machines for situations where negotiation via HTTP is not practical, such
as when manually entering requests into web browsers. This document also provides guidance for both HTTP and non-HTTP methods
of content negotiation and ensures they all adhere to a single functional specification, ensuring their functional equivalency.
Guidance for the creation of profiles is provided in the [PROF-GUIDANCE] document created
by the Dataset Exchange Working Group (DXWG).
Describing the parts of profiles and their relation to other profiles is the function of the Profiles Ontology
[PROF-ONT], 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
Currently the definitions sections for the Guidance & Ontology docs need updating and the Conneg doc is updated but now different and probably needs further updating.
We need to solicit feedback in the FPWDs on the granularity of definitions and, when we have a result, ensure that the same definitions are used in all 3 docs.
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 content negotiation based on profiles using HTTP protocol. It introduces HTTP headers and
non-HTTP methods, such as via QSAs, and defines a general QSA Application Programming Interface
(API).
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.
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.
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.
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.
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.
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.
6. Abstract Model
This section describes an abstract conceptual model for content negotiation by profile, independent of any
realizations of it within a specific environment.
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 specifics about client, server, resource,
metadata, request or response.
if we use URIs for profiles but the profile definition changes, how will clients know? Do we need to make strong statements about versions and URI uniqueness?
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 third request type is given that is expected not to apply to all realizations of this abstract model
and not all clients adhering to this specification need implement it.
list profiles tokens
a client requests the list of tokens that the server uses for profiles and for which the
server is able to deliver resource representations that conform to the profile. The server also provides a mapping from tokens to
profile URIs
A server adhering to this specification MUST respond to each request with the following
responses. The first two types are required, handling the third depends on the realization environment.
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
list profiles tokens
a server responds with the list of profile tokens for which it is able to deliver
conformant resource representations and the mapping of the tokens to profile URIs.
It might be possible to have a single function, list profiles in place of the currently proposed 2: list profiles & list profiles tokens.
Two factors at least need to be considered:
whether all Realizations can support a single function
we suspect that HTTP cannot support delivery of a dictionary
whether it's clearest expressed as one or two functions
this is qualitative thing
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 is 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 structures or formats provided that the profiles representations
conforming to the request are unambiguously identified either by URI or a token mappable to a URI.
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.
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 mappable 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.
A client/server pair of agents MAY refer to profiles by identifiers other
than URIs, token, as long as both the client and server are able to
deterministically map that token to a profile's URI. This is due to the known requirement for
profiles to be able to be referred to within other URIs, such as those of resources and other
situations where referring to the profile itself by a URI is not possible.
A server responding to a list profiles tokensrequestMUST provide
token/URI mappings that list tokens and URIs, either of which can be used for get resource by
profilerequests within the same realization.
7. Realizations
This section describes realizations of the abstract model in multiple implementation domains.
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].
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
Listing profiles for a resource using HTTP can be done in two ways.
The use of HTTP OPTIONS is discouraged
since the responses are not cacheable.
The first one is to issue an OPTIONS request against the resource.
In this case a server implementing content negotiation by profile
SHOULD return a Content-Profile header
listing all profiles the requested resource conforms to.
Example 1: Using HTTP OPTIONS to list available profiles
OPTIONS /some/resource HTTP/1.1
---
HTTP/1.1 200 OK
Content-Profile: urn:example:profile:1;q=0.8,http://example.org/profiles/2;q=0.5
[More headers for this resource]
7.1.1.2 Using a HTTP Link header field
The second way is to issue an GET or HEAD against the resource. In this
case a server implementing
content negotiation by profile SHOULD return a HTTP Link header containing information about the
default representation of that resource (i. e. the representation that will be returned after any
content negotiation has been performed) and information about any alternate representations of that
resource. 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 a request/response pair would look as follows:
Example 2: Using a Link-header to point to a list of available profiles
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 3: 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.
7.1.3 list profiles tokens
Currently, there is no proposed way to implement this function using HTTP.
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.
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.
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.
A Query String Argument (QSA) realization of the Abstract Model
is presented here. Unlike the HTTP realization,
which is the subject of an independent document [PROF-IETF],
this realization is fully specified here
and this document is considered normative for the QSA realization.
This realization does not preclude other QSA specifications for profile and content negotiation.
A query string is a part of a URI which assigns values to specified parameters. QSAs are commonly used within
web browsers by humans and in other client/server situations to deliver extra information to a
server.
Key naming
When content negotiation by profile is to take place using QSAs, the requests and responses
of the Abstract ModelMUST be implemented.
However there is some flexibility in how this may be done:
QSA key/value pairs must be implemented but the specific key terms may be changed.
In this realization, _profile and _mediatype are used
to indicate a single profile or a list of
preference-ordered profiles or Media types respectively with profiles or Media Types indicated by either URI or
token.
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
un-sustainable in the long-term, given the likely numbers of profiles to be established.
For this reason, the QSA realization allows either URIs or tokens for profiles to be used and it is expected,
though not mandated here, that QSA realizations will also allow URIs or tokens for Media Types and other
content negotiation dimensions, such as language. There are already several initiatives that have created URIs
for Media Types based on the IANA register's tokens.
Resource URI
Resource URIs for which QSA-based profile negotiation is taking place MUST NOT themselves be QSA values
of other resource URIs in any QSA-based realization. Such mechanics may be used but must be transparent to the
realization's client applications.
Example 4: Resource URIs must not, themselves, be parameters of other URIs
For the representation of Resource X, according to Profile Y, in Media Type Z:
NOT ALLOWED:
GET /single/endpoint?resource=http://example.org/resource/X&_profile=Y&_mediatype=Z HTTP/1.1
ALLOWED:
GET /resource/X?_profile=Y&_mediatype=Z HTTP/1.1
7.2.1 list profiles
A QSA with a fixed value MUST be supported by a server to allow a client to
make a list profilesrequest.
The QSA key/value pair _profile=listSHOULD be used however the serverMAY
make available an equivalent pair as long as this is discoverable. This is to cater for APIs that alreadly
implement a similar function using QSA key/value pairs such as _view=alternates.
The complete request for the profiles to which a resource's representations conform can be
communicated in a single URI like thus:
Example 5: Requesting a list of profiles for a resource by QSA
GET /a/resource?_profile=list HTTP/1.1
where /a/resource is the URI of the resource for which the list of available profiles is
requested
A client making this requestMAY negotiate for particular formats of the response by
using a QSA equivalent to the HTTP Accept header to indicate a Media Type. A serverSHOULD implement a _mediatype QSA for this but MAY implement an alternative, such
as _format as long as this is dicoverable,
An example profile listing for a resource in HTML would look like:
Example 6: 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 SHOULD allow the
requester to indicate preferences. This SHOULD be done by allowing the QSA indicating the desired
profile, usually _profile, to have a comma-separated list as its value so, for a
client desiring representations of /a/resource according to profiles with tokens
aaa, bbb & ccc we have:
Example 7: Requesting a list of profiles for a resource by QSA in HTML
GET /a/resource?_profile=aaa,bbb,ccc HTTP/1.1
Servers MAY support any combination of profile URIs or tokens for this
(e.g. aaa,http://example.org/profile-x,bbb).
However, in this situation, profile URIs containing commas must escape them.
Similarly, a server implementing multiple Media Type return formats for profile listing SHOULD
allow a client to specify a preference order for Media Types and also for other dimensions of content
negotiation, such as language. When using a QSA-only API, Media Type preferences (and language and others in a
similar fashion) MAY be specified in a comma-separated list form, most preferred to least such that
a client requesting profil
7.2.3 list profiles tokens
Issue: To be completed
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 use of HTTP to negotiate and transport implies that all privacy and security issues
that are relevant for that protocol are also relevant for profile negotiation. E. g.,
information such as user agent, accept-headers, IP address etc. can potentially be used as
identifying information, and particularly, the IP address adds information about geolocation
and institutional membership. Apart from that, there are no known security or privacy impacts
of this feature.
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_URI + ?_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:
I believe that any submission to the IETF for the processing rules around content negotiation for profiles that includes query parameters as a mechanism rather than the proposed Accept-Profile header will be rejected, as it conflicts with base W3C and IETF architectural constraints.
The query component contains non-hierarchical data that, along with data in the path component (Section 3.3), serves to identify a resource [...]
Meaning that the query parameter is included in the URI for determining the identity of the resource. Thus foo?_profile=p1 is a different resource (in RDF terms) from foo or foo?_profile=p2. This would make it not content negotiation at all, just separate resources.
Content negotiation refers to the practice of making available multiple representations via the same URI.
Combined with the above, makes _profile not count as "content negotiation", as the URI is different because the query component of the URI is part of the opaque URI string.
And etc. I'm sure that @RubenVerborgh can provide further supporting documents.
This is NOT to say that the WG cannot specify such an approach, but that it must be separate from the formal content negotiation deliverable.
This is an expansion of #74 (comment), and proposed clarification as to the scope.
RESPONSE FOR Req. 263
The IETF submission in the DXWG Family of Documents [PROF-IETF] does not address content negotiaiton by
profile query param patterns: it is limited to HTTP specification-based negotiation only.
Recommendations for content negotiation by profile via query param patterns (Query String Arguments) are
given in the Profile Guidance [PROF-GUIDANCE] document where an API for this is defined.
(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.