$Id: secdocumentation.html,v 1.4 2005/09/29 15:52:57 ajm65 Exp $
This is a draft of a section for the SKOS Core Guide. See http://isegserv.itd.rl.ac.uk/cvs-public/skos/drafts/secdocumentation.html for revisions of this document.
N.B. This section has changed since the last public working draft, see Changes.
This section describes the SKOS Core documentation properties. These are 7 properties you can use to add human-readable documentation to the description of a concept. The properties are:
skos:note| +--skos:definition| +--skos:scopeNote| +--skos:example| +--skos:historyNote| +--skos:editorialNote| +--skos:changeNote
The SKOS Core documentation properties are arranged as a property hierarchy as shown above. Thus a skos:definition is also a skos:note, a skos:editorialNote is also a skos:note and so on.
Use the skos:note to supply general documentation for any purpose.
Use the skos:definition property to supply a complete explanation of the intended meaning of a concept.
Use the skos:scopeNote property to supply partial information about the intended meaning of a concept, i.e. information about what is or isn't included within the meaning ('scope') of the concept. See also [BS8723].
Use the skos:example property to supply an example of the use of a concept.
Use the skos:historyNote property to document instructions or useful information for users of the scheme, specifically relating to significant changes to the meaning/form/state of a concept. See also [BS8723].
Use the skos:editorialNote property to supply information that is an aid to administrative housekeeping, such as reminders of editorial work still to be done, or warnings in the event that future editorial changes might be made [BS8723].
Use the skos:changeNote property to document fine-grained changes to a concept, for the purposes fo administration and maintenance.
There are three recommended usage patterns for the SKOS Core documentation properties:
The sub-sections below explain these patterns.
This is the simplest pattern for using the SKOS Core documentation properties, where the property value (i.e. the object of the triple) is an RDF literal.
An example of this pattern is below:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#">
<skos:Concept rdf:about="http://www.example.org/concepts#bananarepublic">
<skos:prefLabel>banana republic</skos:prefLabel>
<skos:definition>A small country, especially in South and Central America, that is
poor and often badly and immorally ruled.</skos:definition>
</skos:Concept>
</rdf:RDF>
Note that an plain literal may include a language tag. Where a concept is labelled in more than one language, documentation may also be provided in multiple languages, for example:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#">
<skos:Concept rdf:about="http://www.example.com/concepts#pineapples">
<skos:prefLabel xml:lang="en">pineapples</skos:prefLabel>
<skos:definition xml:lang="en">The fruit of plants of the family Bromeliaceae.</skos:definition>
<skos:prefLabel xml:lang="fr">ananas</skos:prefLabel>
<skos:definition xml:lang="fr">Le fruit de la plante herbacée de la famille des broméliacées.</skos:definition>
</skos:Concept>
</rdf:RDF>
In this pattern the documentation is structured as a related resource description. This allows you to represent more complex documentation structures, including properties of the documentation itself, such as the creator(s) of the documentation, a date, or its intended audience.
An example of this pattern is below:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:foaf="http://xmlns.com/foaf/0.1/">
<skos:Concept rdf:about="http://www.example.org/concepts#laptops">
<skos:prefLabel>notebook computers</skos:prefLabel>
<skos:changeNote rdf:parseType="Resource">
<rdf:value>The preferred label for this concept changed from 'laptop computers' to
'notebook computers' on 23 Jan 1999.</rdf:value>
<dc:creator>
<foaf:Person>
<foaf:name>John Smith</foaf:name>
<foaf:mbox rdf:resource="mailto:jsmith@example.org"/>
</foaf:Person>
</dc:creator>
<dc:date>1999-01-23</dc:date>
</skos:changeNote>
</skos:Concept>
</rdf:RDF>
See FOAF [FOAF] and DC [DCMITERMS] specifications for more properties to use with related resource descriptions and usage guidelines.
In particular, the dc:audience property may be used to add information about the intended audience of the note, e.g.:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:dc="http://purl.org/dc/elements/1.1/">
<skos:Concept rdf:about="http://www.example.org/concepts#pineapples">
<skos:prefLabel>pineapples</skos:prefLabel>
<skos:definition rdf:parseType="Resource">
<rdf:value>The fruit of plants of the family Bromeliaceae.</rdf:value>
<dc:audience>general user</audience>
</skos:definition>
<skos:editorialNote rdf:parseType="Resource">
<rdf:value>Consult Dr. Jones regarding the definition of this concept at 2005-09-29
editorial meeting.</rdf:value>
<dc:audience>editor</audience>
</skos:editorialNote>
</skos:Concept>
</rdf:RDF>
Where the documentation is structured as a related resource description, you may use the dc:language property to indicate the language of the documentation, e.g.:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcterms="http://purl.org/dc/terms/">
<skos:Concept rdf:about="http://www.example.com/concepts#botany">
<skos:prefLabel>botany</skos:prefLabel>
<skos:note rdf:parseType="Resource">
<rdf:value>@@TODO</rdf:value>
<dc:creator>
<foaf:Person>
<foaf:name>John Smith</foaf:name>
<foaf:mbox rdf:resource="mailto:jsmith@example.org"/>
</foaf:Person>
</dc:creator>
<dc:language>
<dcterms:RFC1766>
<rdf:value>EN</rdf:value>
<rdfs:label>English</rdfs:label>
</dcterms:RFC1766>
</dc:language>
</skos:note>
</skos:Concept>
</rdf:RDF>
This pattern allows you to refer to documentation that is itself a document, via the URI of that document.
A specific examples of this pattern is below:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#">
<skos:Concept rdf:about="http://www.example.com/concepts#zoology">
<skos:prefLabel>zoology</skos:prefLabel>
<skos:scopeNote rdf:resource="http://www.example.com/notes/zoology.txt"/>
</skos:Concept>
</rdf:RDF>
Note that it is possible to include metaproperties of this document within the same RDF graph, for example:
Example
<rdf:RDF
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:skos="http://www.w3.org/2004/02/skos/core#"
xmlns:rdfs="http://www.w3.org/2000/01/rdf-schema#"
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:dcterms="http://purl.org/dc/terms/"
xmlns:foaf="http://xmlns.com/foaf/0.1/">
<skos:Concept rdf:about="http://www.example.com/concepts#botany">
<skos:prefLabel>botany</skos:prefLabel>
<skos:scopeNote>
<foaf:Document rdf:about="http://www.example.com/notes/botany.txt">
<dc:creator>
<foaf:Person>
<foaf:name>John Smith</foaf:name>
<foaf:mbox rdf:resource="mailto:jsmith@example.org"/>
</foaf:Person>
</dc:creator>
<dc:language>
<dcterms:RFC1766>
<rdf:value>EN</rdf:value>
<rdfs:label>English</rdfs:label>
</dcterms:RFC1766>
</dc:language>
</foaf:Document>
</skos:scopeNote>
</skos:Concept>
</rdf:RDF>
$Id: secdocumentation.html,v 1.4 2005/09/29 15:52:57 ajm65 Exp $
$Log: secdocumentation.html,v $ Revision 1.4 2005/09/29 15:52:57 ajm65 Did the TODO example. Wrote instructions on usage for each note type. Revision 1.3 2005/09/19 14:02:57 ajm65 editorial (sorting CVS keyword expansion) Revision 1.1 2005/09/19 13:54:36 ajm65 initial version