RDF Coding and Documentation

From Filtered Push Wiki
Jump to: navigation, search

See also:
DataAnnotationHome Start here when looking for the landscape.
CurrentExampleList List of RDF examples of data Annotations
RDF_Coding_and_Documentation Proposed Filtered Push Coding Practices for RDF, especially Annotations.

WORK IN PROGRESS. Please discuss on discussion page

Best Practices

Default namespace and xml:base

(Proposed practice): Normally, for RDF documents in files, use a (preferably resolvable and dereferencable) http URI as both the default namespace and xml:base). Do not terminate it with '/' or '#' but rather begin local resources with '#'. Assuming such usage, suppose the URIs are both http://example.com/example1.rdf, and &ao; is an entity reference that resolves to the location of the Annotation Ontology. Then in the snippet below, the first element describes the rdf document itself, and the second describes an Annotation http://example.com/example1.rdf#theAnnotation


  • rdf:RDF xmlns filename without trailing # or /
  • rdf:RDF xml:base filename without trailing # or /
Note: This follows the practice of the OWL 2 Web Ontology Language: XML Serialization. Note also this is analogous to typical usage in HTML, in which # signifies reference to a local anchor.--Bob Morris 14:50, 22 December 2011 (EST)
<rdf:Description rdf:about="">

<rdf:Description rdf:about="#theAnnotation">
    <rdf:type rdf:resource="&ao;Annotation"/>

Local vs external descriptions

When specifying an RDF graph (e.g. in an rdf document) the designer must decide which of the entities in it will be have descriptions in the graph and which external. For example, the rdf below are meant to be examples of data Annotations, so it is appropriate that the named foaf:Persons in it have descriptions in the rdf. Without them, the utility of the example might be reduced. But if those Persons had suitable globally unique URIs---preferably that could be resolved and dereferenced---then it might usually be more appropriate to use those URIs, rather than the local ones in this example. Otherwise, in some hypothetical data integration there might be conflicts between the descriptions of those entities as described in the examples, and the description as described elsewhere. Worse, if nowhere were there assertions about the relations between the fully qualified URIs in the graphs being integrated, then no conclusions at all could be drawn about whether the same Person was cited in all the data.

The recommended mechanism for declaring and referencing local entities in RDF/XML is to make their rdf:Description have rdf:about be simply #<S> where <S> is a string that can be a filename component of an http URI. In that case, references take the same form. Note that the xml:base attribute on the root rdf:RDF element specifies the first part of the actual URI of a local entity. (If not specified, it defaults to the value of the default namespace)

The two examples below illustrate these practices.

Example: Simple Annotation of a new determination

A simple annotation recommending that a new taxonomic determination be inserted into a taxonomic database.

<?xml version="1.0"?>

    <!ENTITY xsd "http://www.w3.org/2001/XMLSchema#" >
    <!ENTITY owl "http://www.w3.org/2002/07/owl#" >    
    <!ENTITY rdf "http://www.w3.org/1999/02/22-rdf-syntax-ns#" >
    <!ENTITY rdfs "http://www.w3.org/2000/01/rdf-schema#" >
    <!ENTITY dc "http://purl.org/dc/elements/1.1/" >        
    <!ENTITY pav "http://purl.org/pav/" >
    <!ENTITY foaf "http://xmlns.com/foaf/0.1/" >    
    <!ENTITY ao "http://purl.org/ao/">
    <!ENTITY aod "http://etaxonomy.org/ontologies/ao/aod.owl#" >
    <!--<!ENTITY dwc "http://rs.tdwg.org/dwc/terms/index.htm#" > -->
    <!ENTITY dwc "http://rs.tdwg.org/dwc/terms/" >
    <!--<!ENTITY dwcfp "http://etaxonomy.org/ontologies/dwcfp#" >-->
    <!ENTITY dwcfp "http://purl.org/dwcFPModel/" >    
    <!ENTITY applepie "http://etaxonomy.org/ontologies/applepieRules#" >
    <!ENTITY simpleExp "http://etaxonomy.org/ontologies/ao/insert_determination.rdf" >

<rdf:RDF xmlns="&simpleExp;"     

    <!-- To Do: Perhaps make dwcFPModel URI resolvable -->
                  <!-- Metadata for this file -->
    <rdf:Description rdf:about="">
      <rdfs:comment xml:lang="en">An example to insert a new determination for the collection object A-huhBarcode-00107080.</rdfs:comment>
      <rdfs:comment xml:lang="en">Converted to pure RDF from aod_example_insert_determination.owl svn r809 </rdfs:comment>
      <rdfs:comment xml:lang="en">$Id: aod_example_insert_determination.rdf 819 2011-12-23 05:17:45Z ramorrismorris $</rdfs:comment>

                  <!-- The Annotation -->
    <rdf:Description rdf:about="#simple_annotation">
        <rdf:type rdf:resource="&aod;DataAnnotation"/>
        <pav:createdBy rdf:resource="#Robert_A._Morris"/>
        <pav:createdOn rdf:datatype="&xsd;dateTime">2011-09-11T21:32:52</pav:createdOn>        
        <aod:annotatesResource rdf:resource="#A-huhBarcode-00107080"/>
        <ao:hasTopic rdf:resource="#ID_as_Ateleia_gummifera_D._Dietrich"/>
        <aod:hasMotivation rdf:resource="#motivationForAssertion"/>
        <aod:hasEvidence rdf:resource="#evidenceForAssertion"/>
        <aod:hasExpectation rdf:resource="&aod;Expectation_Insert"/>
    <rdf:Description rdf:about="#Robert_A._Morris">  
    		<rdf:type rdf:resource="&foaf;Person"/>
        <foaf:name>Robert A. Morris</foaf:name>
        <foaf:mbox rdf:resource="mailto:edd@xml.com" />
        <foaf:phone rdf:resource="tel:+15174329527" />
    <rdf:Description rdf:about="#A-huhBarcode-00107080">
        <rdf:type rdf:resource="&dwc;references"/>

    <rdf:Description rdf:about="#ID_as_Ateleia_gummifera_D._Dietrich">
        <rdf:type rdf:resource="&dwc;Identification"/>        
        <dwcfp:identifiedBy>C.H. Stirton</dwcfp:identifiedBy>
        <dwcfp:scientificName>Ateleia gummifera</dwcfp:scientificName>
        <dwcfp:scientificNameAuthorship>D. Dietrich</dwcfp:scientificNameAuthorship>

    <rdf:Description rdf:about="#motivationForAssertion">
        <rdf:type rdf:resource="&aod;Motivation"/>
        <aod:asText xml:lang="en">Example of recording as an annotation a paper annotation found on a herbarium sheet.</aod:asText>

    <rdf:Description rdf:about="#evidenceForAssertion">
        <rdf:type rdf:resource="&aod;Evidence"/>
        <aod:asText>Written on the sheet along with the annotation text "Flora Neotropica"</aod:asText>


Example: ao_example_7 An Annotation asserting a new identification.

A more extensive Annotation asserting a new identification.

<?xml version="1.0"?>

<!ENTITY ao "http://purl.org/ao#" >
    <!ENTITY pav "http://purl.org/pav#" >
    <!ENTITY foaf "http://xmlns.com/foaf/spec/20100809.rdf#" >
    <!ENTITY owl "http://www.w3.org/2002/07/owl#" >
    <!ENTITY dc "http://purl.org/dc/elements/1.1#" >
    <!ENTITY tdwg.core "http://rs.tdwg.org/ontology/Core#" >
    <!ENTITY xsd "http://www.w3.org/2001/XMLSchema#" >
    <!ENTITY skos "http://www.w3.org/2004/02/skos/core#" >
    <!ENTITY rdfs "http://www.w3.org/2000/01/rdf-schema#" >
    <!ENTITY aod "http://etaxonomy.org/ontologies/ao/aod.owl#" >
    <!ENTITY rdf "http://www.w3.org/1999/02/22-rdf-syntax-ns#" >
    <!ENTITY tdwg.to "http://rs.tdwg.org/ontology/voc/TaxonOccurrence#" >
    <!ENTITY ex7 "http://etaxonomy.org/ontologies/ao/aod_example_7.rdf" >
    <!ENTITY Juss "http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#ID_as_Parameria_laevigata_(Juss.)" >
    <!ENTITY _Freckmann_ "http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#ID_as_Dichanthelium_acuminatum_subsp._columbianum_(Scribner)_Freckmann_&amp;amp;" >

<rdf:RDF xmlns="&ex7;"

    <rdf:Description rdf:about=""> <!-- metadata about this document -->
	<rdfs:comment xml:lang="en">An example of how the AO annotation ontology could be used to carry data annotations.</rdfs:comment>
	<rdfs:comment xml:lang="en">Real example drawn a recent re-determination of an NEBC specimen in the Harvard University herbaria.</rdfs:comment>
	<rdfs:comment xml:lang="en">Shown here: (1) An annotation containing a new determination for a specific collection object.</rdfs:comment>
	<rdfs:comment xml:lang="en">TODO: Refactor to use Bob's ontological representation of flat Simple DarwinCore, rather than TDWG ontology terms.</rdfs:comment>
	<rdfs:comment xml:lang="en">$Id: aod_example_7.rdf 816 2011-12-23 00:31:27Z ramorrismorris $
	Original author Paul J. Morris.  converted to pure RDF by Bob Morris from
	aod_example_7.owl svn r809 2011-12-20 21:38:09Z originally generated by Protege 4

    <rdf:Description rdf:about="#NEBC_00339174_example_annotation">
        <rdf:type rdf:resource="&ao;Annotation"/>
        <ao:annotatesResource rdf:resource="#NEBC_00339174"/>
        <ao:hasTopic rdf:resource="&_Freckmann_;amp;_Lelong"/>
        <aod:hasEvidence rdf:resource="#evidenceForAssertion"/>
        <aod:hasExpectation rdf:resource="#Expectation_Insert"/>
        <rdfs:label xml:lang="en">specimen annotation example 7</rdfs:label>
        <pav:createdOn rdf:datatype="&xsd;date">2011-10-14</pav:createdOn>
        <pav:createdBy rdf:resource="#Paul_J._Morris"/>


    <!-- http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#Expectation_Insert -->

    <rdf:Description rdf:about="#Expectation_Insert">
        <rdf:type rdf:resource="&aod;Expectation_Insert"/>

    <!-- http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#ID_as_Dichanthelium_acuminatum_subsp._columbianum_(Scribner)_Freckmann_&amp;amp;_Lelong -->

    <rdf:Description rdf:about="&_Freckmann_;amp;_Lelong">
        <rdf:type rdf:resource="&tdwg.to;Identification"/>
        <rdfs:label xml:lang="en">ID as Dichanthelium acuminatum subsp. columbianum (Scribner) Freckmann & Lelong by Walter Kittredge</rdfs:label>
        <tdwg.to:taxonName>Dichanthelium acuminatum subsp. columbianum (Scribner) Freckmann & Lelong</tdwg.to:taxonName>
        <tdwg.to:identifiedToString>Dichanthelium acuminatum subsp. columbianum (Scribner) Freckmann & Lelong</tdwg.to:identifiedToString>
        <tdwg.to:expertName>W.T.Kittredge [GH]</tdwg.to:expertName>

    <!-- http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#NEBC_00339174 -->

    <rdf:Description rdf:about="#NEBC_00339174">
        <rdf:type rdf:resource="&tdwg.core;Specimen"/>
        <tdwg.to:institutionCode rdf:datatype="&xsd;string">NEBC</tdwg.to:institutionCode>
        <tdwg.to:catalogNumber rdf:datatype="&xsd;string">NEBC-huhbarcode-00339174</tdwg.to:catalogNumber>

    <!-- http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#Paul_J._Morris -->

    <foaf:Person rdf:about="#Paul_J._Morris">
        <rdfs:label>Paul J. Morris</rdfs:label>
        <foaf:name>Paul J. Morris</foaf:name>

    <!-- http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#evidenceForAssertion -->

    <rdf:Description rdf:about="#evidenceForAssertion">
        <rdf:type rdf:resource="&aod;Evidence"/>
        <aod:asText>Possible Plant Ontology terms: 

PO:0025176 of two kinds, dense short puberulent and long non-pustulose.

PO:0020104 has trichome  of two kinds, dense short puberulent and long non-pustulose.
        <aod:asText xml:lang="en">The stems and sheaths have two kinds of hairs, dense short puberulent ones and long non-pustulose ones. This is how you distinguish this subspecies from the others of D. acuminatum.</aod:asText>

    <!-- http://etaxonomy.org/ontologies/ao/aod_example_7.rdf#W.T.Kittredge -->
    <!-- Nothing references this resource, mainly because tdwg.to:expertName provides only for a string.  This should be fixed
         by pointing at a more structured Identification object.  ram Dec 22 2011  -->

    <foaf:Person rdf:about="#W.T.Kittredge">
        <foaf:mbox_sha1sum rdf:datatype="&xsd;string">0d295eeef9d7b1397355adcc529cb8003b42007f</foaf:mbox_sha1sum>
        <foaf:name rdf:datatype="&xsd;string">Walter T. Kittredge</foaf:name>



Some (all?) of our examples either refer to a local object typed as aod:<someSubClass> of aod:Expectation and containing no other data except the type. Where the object is declared with a full qualified URI (whether by prefix or not) there remains the possible risk that the URI of the rdf:about object be inadvertantly set to that of the subclass in Annotation Ontology itself. This is probably ill-advised since a lot of tractable OWL profiles prohibit a class from also being an individual, and such usage might make an Annotation inconconsistent with tractable versions of the annotation ontology. Consequently, I suggest the following practices:

  1. AOD or AO provide a member something like aod:simple<ExpectationClassName> (e.g. aod:simpleExpectationInsert) which is deemed (or enforced?) to be final and if no data are required on the Expectation, that this global object be used.
  2. If data are required on the Expectation object, that a local object of type aod:<ExpectationClassName> be described and referenced.

--Bob Morris 15:43, 24 December 2011 (EST) See the Discussion page for more on this issue.

RDF graph provenance

When constructing or generating RDF, consider whether the provenance of the graph(s) in it are different from the provenance of the RDF document or generation event itself. For example, in static RDF files such as those of the examples above, the document itself may require provenance, and the graphs within it may separately require provenance. For static files, where possible document the origin and version of the file. For RDF constructed dynamically, where possible include an rdf:Description of the service and event providing the served rdf.

Namespace prefixes

Note that these are under discussion. Especially for the AO namespaces, these may ultimately change to W3C namespaces.

Preferred Namespace Prefixes
Name URL Prefix Alternate Notes
Dublin Core Terms http://dublincore.org/documents/dcmi-terms/#terms-identifier dct dcterms
Darwin Core Terms http://rs.tdwg.org/dwc/terms dwct dwcterms
Annotation Ontology (AO) http://purl.org/pav/ao ao
Data Annotation AO Extension (AOD) http://etaxonomy.org/ontologies/ao/aod.owl aod
Friend of a Friend (FOAF) http://xmlns.com/foaf/spec/20100809.rdf foaf

ApplePie Standard Annotation RDF

There is now an ApplePie external DTD that greatly simplifies making ApplePie Annotations. It provides standard namespaces, prefixes and entity references in ways that any agent that creates an XML DOCTYPE for rdf:RDF elements in rdf/xml will have everything provided except what they wish to add. The key is to make your serialization look like this:

<?xml version="1.0"?>

   <!ENTITY % applepieDTD SYSTEM "http://etaxonomy.org/ontologies/ao/applepie.dtd">
   <!-- your local entities go here -->
  <!ENTITY simpleExp "http://etaxonomy.org/ontologies/ao/insert_determination.rdf" >
    <!-- your local namespace declarations go in the rdf:RDF element.  The ones in the appliepie dtd are automatically included and can be used in the rdf -->


Current RDF Example List

A number of examples from our svn repository are in a historically accidental form of OWL ontologies when they should be instances. We are in the process of editing those and more will appear in this list as that progresses.

aod_example_2.rdf asserts that a certain Flickr image depicts the species Dictyophora indusiata.

aod_example_3.rdf asserts a taxonomic identification on a specimen.

aod_example_4.rdf further taxonomic identifications.

aod_example_7.rdf examples including evidence for new taxonomic determinations with expectation that the underlying data will be updated.

aod_example_insert_determination.rdf expect the insertion of a taxonomic determination for a previously unidentified specimen.

Requirements5Annotation.rdf An annotation of another annotation given by a URI. See also Requirement5Soln