Skip to content

Commit

Permalink
Merge remote-tracking branch 'origin/conneg-fpwd-edits' into gh-pages…
Browse files Browse the repository at this point in the history 
…-connegfpwd-ra
  • Loading branch information
@rob-metalinkage
rob-metalinkage committed Nov 16, 2018
2 parents f971514 + 4008a4c commit 21ef841
Show file tree
Hide file tree
Showing 8 changed files with 602 additions and 87 deletions.
2 changes: 1 addition & 1 deletion conneg-by-ap/config.js
View file
Expand Up @@ -63,7 +63,7 @@ var respecConfig = {
date: "2018-12-31",
status: "W3C Editor's Draft"
},
"PROF-GUIDE": {
"PROF-GUIDANCE": {
editors: [
"Rob Atkinson",
"Karen Coyle",
Expand Down
64 changes: 33 additions & 31 deletions conneg-by-ap/index.html
View file
Expand Up @@ -14,14 +14,6 @@ <h2>Abstract</h2>
<em>profiles</em>. This is distinct from negotiating by Media Type or Language: the <em>profile</em> is expected
to specify the content of information returned, which may be a subset of what the responding server contains.
</p>
<p>
For details about what a <em>profile</em> is, see the [[PROF-GUIDE]] recommendation published by the producers
of this document.
</p>
<p>
For the formal ontology describing <em>profile</em>s, their parts and relations to other profiles and
specifications, see the [[PROF-ONT]] recommendation, also published by this document's publisher.
</p>
</section>
<section id="sotd">
<!-- The "Status of This Document" section is generated by config.js -->
Expand All @@ -32,7 +24,7 @@ <h3>Overview of DXWG documents on profiles</h3>
Some of the documents are general while some are technology-specific:
</p>
<ul>
<li>[[PROF-GUIDE]] the top-level general profiling guidance document giving an overview of all other documents</li>
<li>[[PROF-GUIDANCE]] the top-level general profiling guidance document giving an overview of all other documents</li>
<li>[[PROF-ONT]] a document describing a formal ontology for describing objects related to profiles</li>
<li><strong>[PROF-CONNEG] this document, including specific guidance on how to negotiate for Internet resource content using profiles</strong></li>
<li>[[PROF-IETF]] an
Expand All @@ -48,8 +40,9 @@ <h1>Introduction</h1>
<p>
Content delivered by dereferencing Internet identifiers can be negotiated for in different
ways. When using the HTTP protocol [[RFC7230]], a client may set an <code>Accept</code> header specifying
preferred Media Types which the server may or may not supply. For example, resources available in different languages
may be requested by setting an HTTP <code>Accept-Language</code> header. However, clients have not had a
preferred Media Types which the server may or may not supply or it may set an <code>Accept-Encoding</code>.
header to request that a specific content encoding system be used. Resources available in different languages
may be also requested by setting an HTTP <code>Accept-Language</code> header. 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 <a>profile</a> - and this document addresses this functionality.
</p>
Expand All @@ -61,7 +54,8 @@ <h1>Introduction</h1>
being defined and formatted according to various Dublin Core elements (<code>dct:title</code>,
<code>dct:description</code> &amp; <code>dct:creator</code>, 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 a non-existent or unsupported profile is requested, a server returns default content.
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.
</p>
<p>
When selecting a content negotiation mechanism, an Internet client may use the HTTP protocol but it may also use
Expand All @@ -72,6 +66,14 @@ <h1>Introduction</h1>
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.
</p>
<p>
Guidance for the creation of <a>profile</a>s is provided in the [[PROF-GUIDANCE]] document created
by the Dataset Exchange Working Group (DXWG).
</p>
<p>
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.
</p>
</section>
<section id="conformance">
<p>
Expand Down Expand Up @@ -160,10 +162,6 @@ <h2>Motivation</h2>
</section>
<section id="relatedwork" class="informative">
<h2>Related Work</h2>
<p>
Guidance for the creation of <a>profile</a>s is provided in the [[PROF-GUIDE]] document created
by the Dataset Exchange Working Group (DXWG).
</p>
<p>
The standardization of the content-negotiation HTTP headers is the purview of the IETF. A first proposal
for an <a href="https://profilenegotiation.github.io/I-D-Accept--Schema/I-D-accept-schema">Internet Draft
Expand All @@ -183,10 +181,6 @@ <h2>Related Work</h2>
or other HTTP headers for this use
will be listed and discussed here.
</p>
<p>
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.
</p>
<div class="issue" data-number="383"></div>
<div class="issue" data-number="516"></div>
<div class="issue" data-number="384"></div>
Expand Down Expand Up @@ -277,6 +271,7 @@ <h3>Requests and Responses</h3>
conformant <em>resource</em> representations and the mapping of the tokens to <em>profile</em> URIs.
</li>
</ol>
<div class="issue" data-number="587"></div>
<p>More detailed descriptions of these requests and their responses are given next.</p>
<section id="listprofiles">
<h4>list profiles</h4>
Expand All @@ -287,7 +282,7 @@ <h4>list profiles</h4>
<em>resource</em> representation is made.
</p>
<p>
The <strong>list profiles</strong> <em>request</em> MAY be an independent request or part of another
The <strong>list profiles</strong> <em>request</em> MUST be either an independent request or part of another
realization's request.
</p>
<p>
Expand Down Expand Up @@ -316,11 +311,12 @@ <h4>get resource by profile</h4>
<em>resource</em> representation conforming to one of any number of <em>profile</em>s with its preference
expressed in a some form of list ordering.
</p>
<div class="issue" data-number="588"></div>
</section>
<section id="listprofilestokens">
<h4>list profiles tokens</h4>
<p>
A <em>client</em>/<em>server</em> pair of agents MAY refere to <em>profile</em>s by identifiers other
A <em>client</em>/<em>server</em> pair of agents MAY refer to <em>profile</em>s by identifiers other
than URIs, <em>token</em>, as long as both the <em>client</em> and <em>server</em> are able to
deterministically map that token to a <em>profile</em>'s URI. This is due to the known requirement for
<em>profile</em>s to be able to be referred to within other URIs, such as those of <em>resources</em> and other
Expand All @@ -347,12 +343,6 @@ <h3>Hypertext Transfer Protocol Headers</h3>
<code>Accept-Profile</code> and <code>Content-Profile</code>
that are to be defined in an upcoming Internet-Draft [[PROF-IETF]].
</p>
<p>
Content negotiation by profile adds a further dimension to the already existing HTTP content
negotiation dimensions, namely media type (<code>Accept</code>/<code>Content-Type</code>), encoding
(<code>Accept-Encoding</code>/<code>Content-Encoding</code>) and language
(<code>Accept-Language</code>/<code>Content-Language</code>).
</p>
<div class="issue" data-number="500"></div>
<section id="listprofileshttp">
<h3>list profiles</h3>
Expand Down Expand Up @@ -469,6 +459,17 @@ <h3>list profiles tokens</h3>
</section>
<section id="qsa">
<h2>URI Query String Arguments</h2>
<p class="issue" data-number="544">
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.
</p>
<div class="issue" data-number="511"></div>
<div class="issue" data-number="538"></div>
<p>
Expand Down Expand Up @@ -533,6 +534,7 @@ <h4>list profiles</h4>
A QSA with a fixed value MUST be supported by a <em>server</em> to allow a <em>client</em> to
make a <strong>list profiles</strong> <em>request</em>.
</p>
<div class="issue" data-number="589"></div>
<p>
The QSA key/value pair <code>_profile=list</code> SHOULD be used however the <em>server</em> MAY
make available an equivalent pair as long as this is discoverable. This is to cater for APIs that alreadly
Expand Down Expand Up @@ -683,7 +685,7 @@ <h2>Requirements</h2>
specific solution should not be any different from the general case.
</p>
<div class="note" title="">Profile definition and constraints on properties are not addressed here. See
[[PROF-GUIDE]].</div>
[[PROF-GUIDANCE]].</div>
<p>
This requirement is taken to mean "create a way to list the profiles implemented by a Internet resource for
<em>humans</em> and <em>machines</em> to use". For the former (humans), the options are:
Expand All @@ -692,7 +694,7 @@ <h2>Requirements</h2>
<li>
discovery via HTML representation
<ul>
<li>see [[PROF-GUIDE]]</li>
<li>see [[PROF-GUIDANCE]]</li>
<li>an approach suggested is to provide an <em>alternate view</em> resource for the original
resource located at <code>RESOURCE_URI + ?_view=alternates</code> which lists, at a minimum, the
<em>profiles</em>, <em>media types</em> (formats) &amp; <em>languages</em> available, as per the
Expand Down Expand Up @@ -761,7 +763,7 @@ <h2>Requirements</h2>
</p>
<p>
Recommendations for content negotiation by profile via query param patterns (Query String Arguments) are
given in the Profile Guidance [[PROF-GUIDE]] document where an API for this is defined.
given in the Profile Guidance [[PROF-GUIDANCE]] document where an API for this is defined.
</p>
</div>
<div class="issue" data-number="264"></div>
Expand Down

0 comments on commit 21ef841

Please sign in to comment.