Skip to content

Commit

Permalink
Merge pull request #333 from w3c/profile-guidance-doc
Browse files Browse the repository at this point in the history 
Profile guidance doc - needs to update placeholder text to formal issues but merged so content accessible for current discussions,.
  • Loading branch information
@rob-metalinkage
rob-metalinkage committed Sep 4, 2018
2 parents 1aa2ad6 + 6ef53b0 commit b571821
Show file tree
Hide file tree
Showing 6 changed files with 486 additions and 16 deletions.
21 changes: 18 additions & 3 deletions conneg-by-ap/config.js
View file
Expand Up @@ -20,10 +20,11 @@ var respecConfig = {
}
],
authors: [{
name: "Nicholas Car",
name: "Nicholas J. Car",
url: "https://people.csiro.au/Nicholas-Car",
company: "CSIRO",
companyURL: "https://www.csiro.au/"
companyURL: "https://www.csiro.au/",
w3cid: 70131
}],
wg: "Dataset Exchange Working Group",
wgURI: "https://www.w3.org/2017/dxwg/",
Expand All @@ -32,5 +33,19 @@ var respecConfig = {
inlineCSS: "true",
lint: "false",
noRecTrack: "true",
issueBase: "https://github.com/w3c/dxwg/issues"
issueBase: "https://github.com/w3c/dxwg/issues",
localBiblio: {
"PROF-GUIDE": {
"href": "https://www.w3.org/TR/profile-guidance/",
"title": "Profile Guidance",
"date": " 2018-12-31",
"status": "W3C Editor's Draft"
},
"PROF-CONNEG": {
"href": "https://www.w3.org/TR/conneg-by-ap/",
"title": "Content Negotiation by Profile",
"date": " 2018-12-31",
"status": "W3C Editor's Draft"
}
}
};
21 changes: 21 additions & 0 deletions conneg-by-ap/dxwg-additions.css
View file
@@ -0,0 +1,21 @@
div.requirement {
background-color: rgb(235, 255, 255);
border-left: solid 0.5em rgb(153, 204, 255);
padding: 1em;
color: #005A9C;
margin: 1em 0;
}

div.requirement > p.reqTitle {
text-transform: uppercase;
}

div.req-response {
margin: 1em 0;
padding: 1em;
background-color: #e0e0eb;
}

div.req-response > p.respTitle {

}
318 changes: 317 additions & 1 deletion conneg-by-ap/index.html
View file
Expand Up @@ -5,6 +5,7 @@
<meta content="text/html; charset=utf-8" http-equiv="content-type"/>
<meta content="width=device-width,initial-scale=1" name="viewport"/>
<link rel="stylesheet" type="text/css" href="https://www.w3.org/StyleSheets/TR/2016/W3C-WG-NOTE"/>
<link rel="stylesheet" type="text/css" href="dxwg-additions.css">
</head>
<body class="h-entry" role="document" id="respecDocument">
<section id="abstract">
Expand All @@ -18,7 +19,19 @@ <h2>Abstract</h2>
<section id="sotd">
<!-- The "Status of This Document" section is generated by config.js -->
</section>

<section id="FamilyOfDocs">
<h1>Profiling Family of Documents</h1>
<p>
This document is part of a family of documents giving guidance on profiling. Some of the documents are general
while some are technology-specific. Please consult the Profile Guidance [[PROF-GUIDE]] document for an
overview of all documents. It is the recommended starting point.
</p>
<ul>
<li>[[PROF-GUIDE]] (Recommendation), the top-level general profiling guidance document giving an overview of all other documents</li>
<li>[[PROF-CONNEG]] (Recommendation), specific guidance on how to negotiate for Internet resource content using profiles</li>
<li>[other] (xxxxxxx), TBD</li>
</ul>
</section>
<section id="Introduction">
<h1>Introduction</h1>
<p>
Expand Down Expand Up @@ -93,7 +106,310 @@ <h2>Related Work</h2>
be seen as anything but work-in-progress.
</p>
</section>
<section id="Requirements">
<h2>Requirements</h2>
<p>
This section lists, and then addresses, individual requirements that the Dataset Exchange Working Group
considered important to address content negotiation by profile.
</p>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-1">
Entailment of schema.org [RES]
<a href="https://github.com/w3c/dxwg/issues/65">65</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-1">Req. 1</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-2">
Profile definition [RPFDF]
<a href="https://github.com/w3c/dxwg/issues/72">72</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-2">Req. 2</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-3">
Profiles listing [RPFL]
<a href="https://github.com/w3c/dxwg/issues/73">73</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-3">Req. 3</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-4">
Profile negotiation [RPFN]
<a href="https://github.com/w3c/dxwg/issues/74">74</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-4">Req. 4</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-5">
Usage notes [RUN]
<a href="https://github.com/w3c/dxwg/issues/86">86</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-5">Req. 5</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-6">
Responses can conform to multiple, modular profiles (UC 5.3)
<a href="https://github.com/w3c/dxwg/issues/217">217</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-6">Req. 6</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-7">
Define conneg interaction with media types that have a profile param
<a href="https://github.com/w3c/dxwg/issues/261">261</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-7">Req. 7</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-8">
IETF submission must not include query param pattern requirements
<a href="https://github.com/w3c/dxwg/issues/263">263</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-8">Req. 8</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-9">
Metadata about server profile support can be used for discovery and mediated traversal via content negotiation. [ID5] (5.5)
<a href="https://github.com/w3c/dxwg/issues/264">264</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-9">Req. 9</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-10">
Enable the ability to negotiate the metadata profile via http, similar to the negotiation of metadata formats today. [ID30] (5.30)
<a href="https://github.com/w3c/dxwg/issues/265">265</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-10">Req. 10</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-11">
Return http link headers using the following relationship types... [ID30] (5.30)
<a href="https://github.com/w3c/dxwg/issues/266">266</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-11">Req. 11</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-12">
There is a need to distinguish between distributions that package the entire dataset and those that support access to specific items, queries, and packaged downloads of data. [ID51] (5.51)
<a href="https://github.com/w3c/dxwg/issues/267">267</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-12">Req. 12</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-13">
A profile must have an identifier that can be served with a response to an API or http request. [ID2] (5.2)
<a href="https://github.com/w3c/dxwg/issues/284">284</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-13">Req. 13</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-14">
A client should be able to determine which profiles are supported by a server, and with which content types or other properties, in order to receive the one most appropriate for their use.
<a href="https://github.com/w3c/dxwg/issues/285">285</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-14">Req. 14</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-15">
There should be a way for a client to look up additional information about a profile. (What kinds of information? Can we clarify this?) [ID2] (5.2)
<a href="https://github.com/w3c/dxwg/issues/286">286</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-15">Req. 15</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-16">
A profile can be modular, with a given response made up of more than one module. A server can indicate that a response conforms to multiple, modular profiles. [ID3] (5.3)
<a href="https://github.com/w3c/dxwg/issues/287">287</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-16">Req. 16</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-17">
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)
<a href="https://github.com/w3c/dxwg/issues/288">288</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-17">Req. 17</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-18">
Invocation of a profile may be by profile name, a schema choice, an encoding, and/or a language. (schema? And assume that encoding is type as in type="application/xml".) [ID5] (5.5)
<a href="https://github.com/w3c/dxwg/issues/289">289</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-18">Req. 18</a></p>
<p>

</p>
</div>
<div class="requirement">
<p class="reqTitle">Requirement</p>
<p class="req" id="req-19">
There needs to be metadata about the views provided by profiles (“named collections of properties”) that can included in a http header [ID5] (5.5)
<a href="https://github.com/w3c/dxwg/issues/290">290</a>
</p>
</div>
<div class="req-response">
<p class="respTitle">RESPONSE FOR <a href="#req-19">Req. 19</a></p>
<p>

</p>
</div>
</section>
<section id="TestSuite">
<h2>Test Suite</h2>
<p>
This section describes the software test suite used to assess adherence of implementations to guidance in
this document.
</p>
<p>
The test suite, implemented using <a href="https://jmeter.apache.org/">Apache's JMeter</a> tool, is...
</p>
</section>
<section id="Implementations">
<h2>Implementations</h2>
<p>
This section describes exemplar implementations of the guidance outlined in this document.
</p>
<section class="implementation" id="impl-csiro">
<h3><a href="https://www.csiro.au">CSIRO</a>'s pyLDAPI</h3>
<p>
CSIRO supports a <a href="https://www.python.org/">Python</a> <a href="http://flask.pocoo.org/">Flask</a>
extension that implements the HTTP, QSA and ontology navigation by profile.
</p>
<ul>
<li><a href="https://pypi.org/project/pyldapi/">pyLDAPI on the Python Package Index</a></li>
</ul>
<p>There are X number of Linked Data APIs implemented using this tool:</p>
<ul>
<li><a href="http://linked.data.gov.au/dataset/gnaf">G-NAF Dataset</a> - a Linked Data representation of Australia's geo-coded addresses <em>(not working yet)</em></li>
<li><a href="http://pid.geoscience.gov.au/samples">Geoscience Australia's Linked Data API of Samples</a> <em>(not working yet)</em></li>
<li><a href="http://pid.geoscience.gov.au/datasets">Geoscience Australia's dataset catalogue, eCat</a> <em>(not working yet)</em></li>
<li><a href="http://linked.data.gov.au/dataset/geofabric">Geofabric</a> - a Linked Data representation of Australia's national digital surface hydrology product <em>(not working yet)</em></li>
</ul>
<h4>Implementation Test Suite results</h4>
<p>
<em>Here will be given each of the implementation instance's results according to the Test Suite</em>
</p>
</section>
<section class="implementation" id="impl-ogc">
<h3><a href="http://www.opengeospatial.org/">OGC</a>'s xxxx</h3>
<p>The OGC implements...</p>
</section>
<section class="implementation" id="impl-dnb">
<h3><a href="http://www.dnb.de">Deutsche Nationalbibliothek</a>'s xxxx</h3>
<p>The Deutsche Nationalbibliothek implements...</p>
</section>
<section class="implementation" id="impl-sdo">
<h3><a href="http://schema.org">schema.org</a>'s xxxx</h3>
<p>schema.org implements...</p>
</section>
<p></p>
</section>
<script class="remove" src="config.js"></script>
<script class="remove" src="https://www.w3.org/Tools/respec/respec-w3c-common"></script>
</body>
Expand Down

0 comments on commit b571821

Please sign in to comment.