Skip to content

Commit

Permalink
Alternative version following structure presented in issue 242
Browse files Browse the repository at this point in the history 
This document seeks to reflect the structure suggested by Karen at #242 (comment). It also tries to re-use as much as possible the material edited by Nick at https://w3c.github.io/dxwg/profiles/ (on Sept 15 2018).
  • Loading branch information
@aisaac
aisaac committed Sep 17, 2018
1 parent 83ac2af commit 1ebfc69
Showing 1 changed file with 288 additions and 0 deletions.
288 changes: 288 additions & 0 deletions profiles/index-structure242.html
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,288 @@
<!DOCTYPE html>
<html lang="en">
<head>
<title>Profile Guidance</title>
<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" id="respecDocument">
<div class="note">
(Antoine:) This document seeks to reflect the structure suggested by Karen at https://github.com/w3c/dxwg/issues/242#issuecomment-408916364. It also tries to re-use as much as possible the material edited by Nick at https://w3c.github.io/dxwg/profiles/ (on Sept 15 2018).
I should still also try to go through and incorporate material that the group agrees to in the <a href="https://www.w3.org/2017/dxwg/wiki/ProfileRoundup">Profile Roundup</a>, <a href="https://github.com/w3c/dxwg/issues/196">Issue 196</a> and <a href="https://github.com/w3c/dxwg/issues/323">Issue 323</a> (for better articulation with the documentation for the ProfileDesc vocabulary).
</div>
<section id="abstract">
<h2>Abstract</h2>
<div class="note">
<!-- From Nick: This document describes what a profile is, how best to formulate one and to relate one to other relevant resources.-->
(Antoine:) Re-use wording from the charter and say how this document answers the mission exposed there.
</div>
</section>
<section id="sotd">
<!-- The "Status of This Document" section is generated by config.js -->
<section id="FamilyOfDocs">
<h3>Family of Documents</h3>
<div class="issue" title="(Antoine:) I've kept Nick's listing but I have doubts that DCAT fits here. I see more value in listing only the 3 profile-related docs, as they are meant to work together."></div>
<p>
This document is part of the output of the Dataset Exchange Working Group (DXWG). All documents from the group
are listed here.
</p>
<section id="dcat-docs">
<h4>DCAT documents</h4>
<p>
The DCAT documents are about the revised Data Catalog Vocabulary.
</p>
<ul>
<li>[[vocab-dcat]] (Recommendation), description of the DCAT RDF vocabulary</li>
</ul>
</section>
<section id="profiling-docs">
<h4>Profiling documents</h4>
<p>
These documents give 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 profiling documents. It is the
recommended starting point.
</p>
<ul>
<li><strong>[PROF-GUIDE]</strong> (Recommendation), <strong>this document</strong>, 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>[[PROF-IETF]] (<a href="http://www.ietf.org">IETF</a> <a href="http://www.ietf.org/standards/ids/">Internet-Draft</a>), HTTP Headers for HTTP content negotiation by profile</li>
</ul>
</section>
</section>
</section>
<section id="introduction">
<h1>Introduction (non-normative)</h1>
<div class="note">(Antoine:) I feel Nick's intro can be re-worked/completed. But for now I'm keeping it, as I think it is correct and works well as introductory material
</div>
<p>
Builders of vocabularies and ontologies are encouraged to make their
work as broadly applicable as possible so as to maximize future
adoption. As a result, vocabularies and ontologies typically define a
data model using minimal semantics. For example, DCAT [[vocab-dcat-2]] defines the
concept of a <em>dataset</em> as an abstract entity with <em>distributions</em> and <em>data services</em>
as means of accessing data. It is silent on whether a
distribution should be in a particular serialization, or set of
serializations; it is silent on how data services should be configured;
while it states that the value of dcat:theme should be a SKOS concept,
it does not specify a particular SKOS [[skos-reference]] concept scheme, and so on. Other
vocabularies such as Dublin Core Terms [[DCTERMS]] are equally parsimonious in their prescriptions of how they
should be used.
</p>
<p>
This is good practice: it means that data models and methods of working
can be applied in different circumstances than those in which the original
definition work was carried out and, in that sense, promotes broad
interoperability.
</p>
<p>
However, any individual system will be designed to meet a specific set
of needs, that is, it will operate in a specific context. It is that
context, and the individual choices made by the engineers working within
it, that will determine how a vocabulary or set of vocabularies will be
used. For example, a system ingesting data may require that a specific
subset of properties from a range of vocabularies is used and that only
terms from a defined code list are used as values for specified
properties. In other words, where the 'base vocabulary' might say "the
value of this property SHOULD be a value from a managed code list", a specialised <em>profile</em>
will say "the value of this property MUST be from <em>this</em> specific code list".
</p>
<p>
This document is about how to formulate and communicate <em>profiles</em>.
</p>
<div class="note">(Antoine:) Nick suggested to reuse some elements of the F2F3 outline as a 'motivation' section. I believe the following ones could be mentioned in intro:
<ul>
<li>Communities, national identity on data standards, domains of activity</li>
<li>Functions: consensus; sharing; search; etc.</li>
</ul>
</div>
</section>

<section id="whatisaprofile">
<h2>What is a profile? (normative)</h2>
<div class="note">(Antoine:) From https://github.com/w3c/dxwg/issues/242#issuecomment-408916364:
<ul>
<li>A profile SHOULD have a textual description intended for humans</li>
<li>A profile SHOULD describe metadata elements/properties</li>
<li>A profile SHOULD describe valid value types for elements</li>
<li>A profile SHOULD provide relevant cardinality rules</li>
<li>(etc. here until we finalize requirements - these are just examples)</li>
</ul>
</div>

<div class="note">(Antoine:) Though it should likely be formatted differently, I see this section as reprising Nick's idea in sections 8.2 and 8.3 at
https://github.com/w3c/dxwg/blob/a7403b8c3ceb2630a1a1eb87da7b9babc6fd2d7e/profiles/index.html (i.e. <a href="https://w3c.github.io/dxwg/profiles/#description">here</a> and <a href="https://w3c.github.io/dxwg/profiles/#functions">here</a> in the version of 15 Sept 2018). I.e. list some of the DXWG requirements on profile and explain how they translate in recommendations, when needed.</div>

<div class="note">(Antoine:) At this stage I have doubts on whether all requirements should be reflected in this section. Perhaps we should have only two clusters for the requirements about administrative and descriptive metadata in this section and detail them later, in the section about that metadata.</div>
</section>

<section id="publication">
<h2>Profile publication (normative)</h2>
<div class="note">(Antoine:) From https://github.com/w3c/dxwg/issues/242#issuecomment-408916364:
<ul>
<li>(here the various options for publication - PDF, XML, RDF...)</li>
<li>URL requirement fits here?</li>
</ul>
</div>
<div class="issue">(Antoine:) I think the URI requirements fits here. In fact I think this section should be the one that acts as a 'cover/teaser' for our conneg doc. I.e. it gives a brief motivation for it, tries to fit it in our general picture/model and point to it as our recommendation</div>
<div class="note">(Antoine:) To make this section work, I think it will be good if the reader can see our 'big picture' on profiles and their possible (or recommended) components. I'm thinking of something at the level of the diagram at https://docs.google.com/drawings/d/1dHkpwKwUwMgS1RqSCTPO3uOoRiY_qNk0z5bhXJlYi4Y/, which should work as an abstracted version of the ProfileDesc model https://w3c.github.io/dxwg/profiledesc/profiledesc.png (i.e. one without classes and properties that come from a specific namespace/vocabulary. NB: at this stage I'm not sure if this diagram would fit better in this section or in the one above ('What is a profile?').</div>
</section>

<section id="relatedwork">
<h2>Related work and examples of existing profiles (non-normative)</h2>
<p>
<em>profiling</em> is an activity that has been undertaken by many communities with a range of formalisms.
</p>
<div class="issue">(Antoine) This section was recommended here in https://github.com/w3c/dxwg/issues/242#issuecomment-408916364. I now have doubts about the it, as it breaks the flow between two crucial (normative) sections on DXWG recommendations. As an alternative, I suggest to try to fit this in (a subsection of) the introduction if it can be short enough. Otherwise we could put it as appendix and refer to it from the introduction.</div>
<section id="dcat-ap">
<h3>DCAT Application Profiles</h3>
<p></p>
</section>
<section id="adms">
<h3>Asset Description Metadata Schema</h3>
<p>From the Asset Description Metadata Schema (ADMS) specification [[vocab-adms]]: "ADMS is a profile of DCAT [[vocab-dcat]], used to describe semantic assets".</p>
</section>
<section id="dcap">
<h3>Dublin Core Application Profile &amp; The Singapore Framework</h3>
<p>The Singapore Framework for Dublin Core Application Profiles [[DCSF]]</p>
<p>The Guidelines for Dublin Core Application Profiles [[DCAP]] </p>
<p>Description Set Profiles: A constraint language for Dublin Core Application Profiles [[DCDSP]]</p>
</section>
<section id="ogcp">
<h3>Open Geospatial Consortium Profiling</h3>
<p></p>
</section>
<section id="isop">
<h3>Profiling of ISO standards</h3>
<p></p>
<div class="issue">(Antoine:) I've kept this from Nick's doc but I'm not so sure what it's about.</div>
</section>
<section id="odrl">
<h3>ODRL profiles</h3>
<p></p>
<div class="issue">(Antoine) I've added this as we should really have something on this. The W3C ODRL community group is going to work on profiles of ODRL (including guidelines) quite extensively in the coming months and I think we should make sure our respective recommendations are aligned!</div>
<div class="note">(Antoine) If we really have a productive exchange with the ODRL community and they implement our recommendations, then we could have this example listed instead in the section on 'Examples of applying these recommendations'.</div>
</section>
<section id="bibframe">
<h3>BIBFRA.ME (one namespace)</h3>
<p></p>
<div class="note">(Antoine) This comes from https://github.com/w3c/dxwg/issues/242#issuecomment-408916364, I'm ok having it but if we don't have time to write it up I can live with it...</div>
</section>
</section>

<section id="metadata">
<h2>Administrative and descriptive metadata (normative)</h2>
<div class="note">(Antoine:) From https://github.com/w3c/dxwg/issues/242#issuecomment-408916364, Administrative metadata:
<ul>
<li>A profile MUST have URI (or an IRI?) identifying it. The URI SHOULD be an http URI</li>
<li>creator/maintainer (+ contact info)</li>
<li>date/version</li>
<li>etc</li>
<li></li>
</ul>
</div>
<div class="note">(Antoine:) I've kept it here, but I do agree with the comment at https://github.com/w3c/dxwg/issues/242#issuecomment-408916364 (and above) that URI should be in a specific section on publication of profiles.</div>
<div class="note">(Antoine:) From https://github.com/w3c/dxwg/issues/242#issuecomment-408916364, Descriptive metadata:
<ul>
<li>title</li>
<li>human-readable description </li>
<ul>
<li>title</li>
<li>Design rationale</li>
<li>Model and elements</li>
</ul>
<li>Relationship to vocabs or other profilesn</li>
<li>Link to validation schemas implementing the profile</li>
</ul>
</div>
<div class="issue">(Antoine:) One may argue that human-readable description (if it's provided as a full document) does fit better in a separate section. But upon re-reading the structure suggested by Karen I was not sure of the 'granularity' (of the description) meant here.</div>
<div class="note">(Antoine:) In this section we could list all the requirements on metadata, which we have not listed in the 'What is a profile?' section.</div>
</section>

<section id="ProfileDesc">
<h2>The ProfileDesc vocabulary (non-normative)</h2>
<div class="note">(Antoine:) What I have in mind for this section is to introduce the DXWG ProfileDesc RDF vocabulary. Say how it can support the requirements we identified, point to it, and suggest to use in contexts where an RDF / Linked Data description of the profiles and their associated resources can be made. for example using a sentence like <i>The machine-readable version of the metadata on profiles and their links to associated resources may be provided using the ProfileDesc Vocabulary developed by the DXWG working group</i> (shamelessly inspired from how we've done it in the DWBP doc at https://www.w3.org/TR/dwbp/#quality). I guess it should also reprise some points made at https://github.com/w3c/dxwg/issues/323.</div>
</section>

<section id="examples">
<h2>Examples of applying these recommendations (non-normative)</h2>
<div class="note">(Antoine:) The idea here would be to point to examples that follow our recommendations, made up to illustrate specific features, or complete 'real' implementations. Ideally these would be using ProfileDesc, on the condition that we still refer to ProfileDesc as a suggestion not a formal recommendation (see the way it's been mentioned above). I reckon that some may find it more natural to have fully fledged</div>
<div class="issue">(Antoine:) Some may prefer to have fully fledged examples in ProfileDesc in ProfileDesc's own documentation. I do think there is value in having at least some examples here, even if as a result we decide that the ProfileDesc documentation would be a 'pure' namespace doc like this one for SKOS: https://www.w3.org/2009/08/skos-reference/skos.html</div>

</section>

<section id="appendices" class="appendix">
<h1>Appendices</h1>

<section id="definitions" class="appendix">
<h2>Definitions</h2>
<div class="issue" title="(Antoine:) I'm pasting Nick's definitions here. They need to be polished (as Nick has written himself) and I think we may want to move the definition of profile into the introduction. In any case I'm keeping them entirely for now as it's good to have a reference set of terms we've been interested in defining at some point and I think we should welcome input from the WG, on whether we should add other terms here. For example, 'schema', as refered at https://github.com/w3c/dxwg/issues/242#issuecomment-408916364"></div>
<dl>
<dt><dfn>formalism</dfn></dt>
<dd>
<p><em>definition not finalised</em></p>
<p><em>Source: deliberations of the DXWG. See <a href="https://github.com/w3c/dxwg/issues/194">GitHub Issue 194</a>.</em></p>
</dd>
<dt><dfn>specification</dfn></dt>
<dd>
<p>
An act of identifying something precisely or of stating a precise requirement.
</p>
<p>
<em>Source: <a href="https://en.oxforddictionaries.com/definition/specification">Oxford English Dictionary</a>.</em>
</p>
</dd>
<dt><dfn>standard</dfn></dt>
<dd>
<p>
A basis for comparison; a reference point against which other things can be evaluated.
</p>
<p><em>Source: [[DCTERMS]]</em>.</p>
</dd>
<dt><dfn>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.
</p>
<p>
This definition includes what are often called "application profiles", "metadata application
profiles", or "metadata 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>
</dd>
</dl>
<div class="issue" title="(Nick:) Complete list of definitions"></div>
<div class="issue" title="(Nick:) Extend the second paragraph of 'profile' to indicate data use, not just metadata"></div>
</section>
<section id="relatedworkdefns" class="appendix">
<h4>Comparison with definitions in related work</h4>
<div class="note">(Antoine:) I'm keeping Nick's idea so that the WG can make its mind on whether it is worth pursuing. I personally think it's a noble endeavour but one that would consume too much of our time now.
</div>
<p>The following term definitions, taken from the DC AP &amp; SF specifications ([[DCAP]], [[DCSF]] &amp; [[DCDSP]]) are included to indicate how this document's definitions contrast with those of previous work.</p>
<figure id="relateddefn">
<table class="defn">
<tr>
<th>Term</th><th>Definition</th><th>Reference</th>
</tr>
<tr>
<td><em>profile</em></td><td>The term profile is widely used to refer to a document that describes how standards or specifications are deployed to support the requirements of a particular application, function, community, or context. In the metadata community, the term _application profile_has been applied to describe the tailoring of standards for specific applications.</td><td>[[DCSF]]</td>
</tr>
</table>
<figcaption>Table of profile-related term definitions from the related works</figcaption>
</figure>
<div class="issue" title="(Nick:) Complete table of related works' definitions"></div>
</section>

</section>

<div class="issue" title="(Nick:) Determine references for a 'Normative references' subsection"></div>


<script class="remove" src="config.js"></script>
<script class="remove" src="https://www.w3.org/Tools/respec/respec-w3c-common"></script>
</body>
</html>

0 comments on commit 1ebfc69

Please sign in to comment.