Skip to content

Commit

Permalink
Merge branch 'gh-pages' into prof-definitions
Browse files Browse the repository at this point in the history
  • Loading branch information
@nicholascar
nicholascar committed Jul 29, 2019
2 parents 2046ec4 + 807d2fe commit 12f3585
Showing 1 changed file with 53 additions and 49 deletions.
102 changes: 53 additions & 49 deletions conneg-by-ap/index.html
View file
Expand Up @@ -50,13 +50,13 @@ <h2>Introduction</h2>
<p>
When online information about a resource adheres to one or more profiles, methods described here allow
clients to list those profiles and request content according to one or more of them in order of preference.
For example, a catalog may offer a dataset description using alternative representations using [[VOID]],
[[VOCAB-DATA-CUBE]] and [[VOCAB-DCAT]]. Furthermore, the [[VOCAB-DCAT]] representation might conform to the
[[DCAT-AP]] profile, the [[GeoDCAT-AP]] profile and also an organisation specific profile "MyOrgDCATProfile"
which constrains various elements. These profiles may be related - for example "MyOrgDCATProfile" may be a
further profile of [[GeoDCAT-AP]]. A request for the information about this dataset description resource may
ask for the list of profiles available, or it may ask specifically for a response adhering to, for example
[[GeoDCAT-AP]]. When no profile or an unsupported profile is requested, a server returns default content,
For example, a catalog may offer a dataset description using alternative representations using [[VOID]],
[[VOCAB-DATA-CUBE]] and [[VOCAB-DCAT]]. Furthermore, the [[VOCAB-DCAT]] representation might conform to the
[[DCAT-AP]] profile, the [[GeoDCAT-AP]] profile and also an organisation specific profile "MyOrgDCATProfile"
which constrains various elements. These profiles may be related - for example "MyOrgDCATProfile" may be a
further profile of [[GeoDCAT-AP]]. A request for the information about this dataset description resource may
ask for the list of profiles available, or it may ask specifically for a response adhering to, for example
[[GeoDCAT-AP]]. When no profile or an unsupported profile is requested, a server returns default content,
that is, content conforming to the default profile supported by the server.
</p>
<p class="issue" data-number="990">
Expand All @@ -71,10 +71,12 @@ <h2>Introduction</h2>
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>
<!--
<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>
-->
<p>
Describing the parts of profiles and their relation to other profiles is the function of the Profiles Vocabulary
[[PROF]], also produced by the DXWG.
Expand All @@ -93,52 +95,54 @@ <h2>Introduction</h2>
<section id="definitions">
<h2>Definitions</h2>
<dl>
<dt><dfn>specification</dfn></dt>
<dt><dfn data-lt="specification">specification</dfn></dt>
<dd>
<p>
An act of identifying something precisely or of stating a precise requirement. - <a href="https://en.oxforddictionaries.com/definition/specification">Oxford English Dictionary</a>
A basis for comparison; a reference point against which other things can be evaluated.
</p>
<p>
<em>Source: DCMI Metadata Terms [[DCTERMS]]'s definition for a <a href="http://www.dublincore.org/specifications/dublin-core/dcmi-terms/#terms-Standard"><code>Standard</code></a>.</em>
</p>
</dd>
<dt><dfn data-lt="data specification">data specification</dfn></dt>
<dd>
<p>
One form of a <em>specification</em> is a <em>standard</em> which is a "basis for comparison; a reference
point against which other things can be evaluated" - [[DCTERMS]]
A <a>specification</a>, with human- and/or machine-processable representations, that defines the content and structure of data used in a given context.
</p>
<p><em>Source: deliberations of the DXWG.</em></p>
</dd>
<dt><dfn>profile</dfn></dt>
<dt><dfn data-lt="profile">data profile</dfn></dt>
<dd>
<p>
A named set of constraints on one or more identified base <em>specifications</em>,
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.
A <a>data specification</a> that constrains, extends, combines, or provides guidance or explanation about the usage of other data specifications.
</p>
<p>
This definition includes what are often called "application profiles", "metadata application
profiles", or "metadata profiles".
This definition includes what are sometimes called "application profiles", "metadata application
profiles", or "metadata profiles". In this document, these, and "data profiles", are all referred to as just "profiles".
</p>
<p><em>Source: deliberations of the DXWG. See <a href="https://www.w3.org/2017/dxwg/wiki/ProfileContext">ProfileContext wiki page</a>.</em></p>
<p><em>Source: deliberations of the DXWG.</em></p>
</dd>
<dt><dfn>client</dfn></dt>
<dd>
A program that establishes a connection to a server for the purpose of sending one or more HTTP requests
[[RFC7230]]
A program that establishes a connection to a <a>server</a> for the purpose of sending one or more HTTP requests. [[RFC7230]]
</dd>
<dt><dfn>server</dfn></dt>
<dd>
A program that accepts connections in order to service HTTP requests by sending HTTP responses. [[RFC7230]]
A program that accepts connections in order to service HTTP <a>requests</a> by sending HTTP <a>responses</a>. [[RFC7230]]
</dd>
<dt><dfn>resource</dfn></dt>
<dd>
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]]
</dd>
<dt><dfn>metadata</dfn></dt>
<dd>Information that is supplied about a resource [[RFC3986]]</dd>
<dd>Information that is supplied about a resource. [[RFC3986]]</dd>
<dt><dfn>request</dfn></dt>
<dd>A message sent over the Internet, from a <em>client</em> to a <em>server</em>, for a information about a <em>resource</em> [[RFC7230]]</dd>
<dd>A message sent over the Internet, from a <em>client</em> to a <em>server</em>, for a information about a <em>resource</em>. [[RFC7230]]</dd>
<dt><dfn>response</dfn></dt>
<dd>A message sent over the Internet, from a <em>server</em> to a <em>client</em> answering a <em>request</em> for information about a <em>resource</em> [[RFC7230]]</dd>
<dd>A message sent over the Internet, from a <em>server</em> to a <em>client</em> answering a <em>request</em> for information about a <em>resource</em>. [[RFC7230]]</dd>
<dt><dfn>token</dfn></dt>
<dd>A short name identifying something, in the context of this document a <a>profile</a></dd>
<dd>A short name identifying something, in the context of this document, a <a>profile</a>.</dd>
</dl>
</section>
<section id="motivation" class="informative">
Expand Down Expand Up @@ -274,7 +278,7 @@ <h4>Using the Prefer/Preference-Applied header fields (RFC 7240)</h4>
<h3>Archival Resource Key (ARK)</h3>
<p>ARK (Archival Resource Key) [[ARK]] is an identifier scheme
for the persistent identification of information objects.
ARK identifiers can contain an optional qualifier
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)
Expand Down Expand Up @@ -340,7 +344,7 @@ <h3>OAI-PMH</h3>
<h3>Catalogue Service for the Web (CSW)</h3>
<p>
[[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.),
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 <code>outputSchema</code> and <code>outputFormat</code> 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 <code>GetCapabilities</code> request.
</p>
<p>
Expand Down Expand Up @@ -368,9 +372,9 @@ <h3>Context</h3>
</p>
<p>
An Internet <em>resource</em> may have many aspects over which a <em>client</em>/<em>server</em> pair of
agents might negotiate for content. These aspects are to be treated independently so content negotiation for a
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
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.
</p>
Expand Down Expand Up @@ -412,13 +416,13 @@ <h3>Requests and Responses</h3>
</ol>
<p>
A <em>server</em> adhering to this specification MUST respond to each request with the following
<em>response</em>s.
<em>response</em>s.
</p>
<ol>
<li>
<strong>list profiles</strong><br />
a <em>server</em> responds to a <em>client</em> with the list of <em>profile</em> URIs for the <em>profile</em>s for which it is able to
deliver conformant <em>resource</em> representations
deliver conformant <em>resource</em> representations
</li>
<li>
<strong>get resource by profile</strong><br />
Expand All @@ -431,7 +435,7 @@ <h3>Requests and Responses</h3>
<h4>list profiles</h4>
<p>
A <em>client</em> wishes to know for which <em>profile</em>s a <em>server</em> is able to deliver conformant
representations of a <em>resource</em>. The content of the list can be known either before a <em>request</em> for a
representations of a <em>resource</em>. The content of the list can be known either before a <em>request</em> for a
particular <em>resource</em> representation is made or it may only be known after an initial <em>request</em> for a
<em>resource</em> representation is made.
</p>
Expand Down Expand Up @@ -717,21 +721,21 @@ <h3>URL Query String Arguments</h3>
<div class="issue" data-number="594"></div>
<div class="issue" data-number="538"></div>
<p>
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.
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.
</p>
<p>
As one example of how an API for such a service can be implemented, a Query String Argument (QSA)
realization of the <a href="#abstractmodel">Abstract Model</a> 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
As one example of how an API for such a service can be implemented, a Query String Argument (QSA)
realization of the <a href="#abstractmodel">Abstract Model</a> 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.
</p>
<p>
Expand Down Expand Up @@ -857,7 +861,7 @@ <h4>get resource by profile</h4>
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 <code>aaa,bbb,ccc</code> will receive a resource that meets the requirements of profile
a client requesting profiles as <code>aaa,bbb,ccc</code> will receive a resource that meets the requirements of profile
<code>aaa</code> if it is available, else one that meets profile <code>bbb</code> if that is available, and so on.
</p>
</section>
Expand Down

0 comments on commit 12f3585

Please sign in to comment.