Darwin Core XML Guide

Title:	Darwin Core XML Guide
Date Issued:	2009-02-12
Date Modified:	2009-07-06
Abstract:	Guidelines for the implementation of Darwin Core in XML.
Contributors:	John Wieczorek (MVZ), Markus Döring (GBIF), Renato De Giovanni (CRIA), Tim Robertson (GBIF), Dave Vieglais (KUNHM)
Legal:	This document is governed by the standard legal, copyright, licensing provisions and disclaimers issued by the Taxonomic Databases Working Group.
Part of TDWG Standard:	*URL to DwC Standard* will go here
Creator:	Darwin Core Task Group
Identifier:	http://rs.tdwg.org/dwc/2009-07-06/terms/guides/xml/
Latest Version:	http://rs.tdwg.org/dwc/terms/guides/xml/
Replaces:	http://rs.tdwg.org/dwc/2009-05-25/terms/guides/xml/
Document Status:	For Public Review.

1. Introduction

Audience: This document is targeted toward those who wish to use or construct application schemas using Darwin Core terms in XML. It includes explanations of existing schemas such as the Simple Darwin Core [SIMPLEDWC] and how to build new schemas to meet specific models of information.

This document provides guidelines for implementing application schemas based on Darwin Core terms [TERMS] using [XML]. The underlying metadata model is described (in a syntax neutral way), followed by some specific guidelines for XML implementations. Some guidance on the use of non-Darwin Core terms is also provided.

This document does not provide guidelines for encoding Darwin Core in RDF/XML. Nor does it take a position on the relative merits of encoding metadata in 'plain' XML rather than RDF/XML. This document provides guidelines in those cases where RDF/XML is not considered appropriate.

2. Implementation Guide

2.1 XML Schema

Implementors should base their XML applications on XML Schemas [XMLSCHEMA] rather than XML DTDs. Approaches based on XML Schemas are more flexible and are more easily re-used within other XML applications.

2.2 XML Namespaces

Implementors should use XML Namespaces [XMLNS] to uniquely identify elements. Darwin Core namespaces are defined in the Darwin Core Namespace Policy [NAMESPACEPOLICY], while Dublin Core namespaces are defined in the DCMI Namespace Recommendation [DCMINS].

2.3 Abstract model

The Darwin Core follows the Dublin Core Metadata Initiative Abstract Model [ABSTRACTMODEL] except that the Darwin Core record is roughly equivalent to the Dublin Core resource.

Darwin Core terms are either classes or properties.
Each property has at most one class as its domain (describes no more than one class).
A Darwin Core record is made up of zero or more classes and one or more properties with their associated values.
Each value is a literal string.
The values of properties within a Darwin Core record describe that record.
A Darwin Core record must include all required properties, if any, and their associated values.

2.4 Properties and Values

The Darwin Core follows the guidelines for expressing Dublin Core metadata using XML [DCMIXMLGUIDE] except in that Darwin Core implementors should encode properties as XML elements and values as the content of those elements instead of having each property contain a value representation and its associated value. The name of the XML element should be an XML qualified name (QName), which associates the value given in the Term name attribute in the Darwin Core Terms recommendation [TERMS] with the appropriate namespace name. For example, use

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
    targetNamespace="http://rs.tdwg.org/dwc/terms/"
    xmlns:dwc="http://rs.tdwg.org/dwc/terms/">
...
<dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord>

rather than

<dwc:basisOfRecord value="HumanObservation" />

2.5 Null values

Elements for which the value is null should be omitted from the document or explicitly coded using the attribute xsi:nil="true".

<dwc:locality xsi:nil="true"/>

Do not use an empty string - an element with no content:

<dwc:locality"></dwc:locality">

2.6 Simple Darwin Core

The Simple Darwin Core [SIMPLEXMLSCHEMA] most closely models the "flat" nature of many data sets. It is a ready-made schema for sharing information with no structure beyond properties of a record (equivalent to fields in a table, or columns in a spreadsheet). It is meant to accommodate all properties except those that require further structure to be meaningful (auxilliary terms in the classes ResourceRelationship and MeasurementOrFact. The schema has no required terms and no term is repeated within a given record. Refer to the Simple Darwin Core page [SIMPLEDWC] for the rationale behind this schema.

Records for specimens, observations, taxa, media, locations, and nomenclatural checklists can be constructed using an appropriate values of dcterms:type, to describe the class that is the root of the record, and basisOfRecord, to describe subtype or basic nature of the record, along with appropriate subsets of the Simple Darwin Core elements. The content of these type elements are controlled by the Darwin Core Type vocabulary [DWC-TYPE].

Following is a brief example of an XML document for a single specimen complying with the Simple Darwin Core Schema [SIMPLEXMLSCHEMA]. The Simple Darwin Core XML example document [SIMPLEXMLEXAMPLE] (if this link shows a blank page in your browser, use the View Source option to see the XML document) shows detail for a single record having a more complete set of elements.

<?xml version="1.0"?>
<dwr:SimpleDarwinRecordSet
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/dwc/xsd/simpledarwincore/  http://rs.tdwg.org/dwc/xsd/tdwg_dwc_simple.xsd"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:dwc="http://rs.tdwg.org/dwc/terms/"
    xmlns:dwr="http://rs.tdwg.org/dwc/xsd/simpledarwincore/">
    <dwr:SimpleDarwinRecord>
        <dcterms:type>Occurrence</dcterms:type>
        <dcterms:modified>2009-02-12T12:43:31</dcterms:modified>
        <dcterms:rightsHolder>Museum of Vertebrate Zoology</dcterms:rightsHolder>
        <dcterms:rights>Creative Commons License</dcterms:rights>
        <dwc:institutionCode>MVZ</dwc:institutionCode>
        <dwc:collectionCode>Mammals</dwc:collectionCode>
        <dwc:occurrenceID>urn:catalog:MVZ:Mammals:14523</dwc:occurrenceID>
        <dwc:basisOfRecord>PreservedSpecimen</dwc:basisOfRecord>
        <dwc:country>Argentina</dwc:country>
        <dwc:countryCode>AR</dwc:countryCode>
        <dwc:stateProvince>Neuquén</dwc:stateProvince>
        <dwc:locality>25 km al NNE de Bariloche por Ruta 40 (=237)</dwc:locality>
    </dwr:SimpleDarwinRecord>
</dwr:SimpleDarwinRecordSet>

2.7 Classes and Containment

Many Darwin Core terms (properties) are defined as having other terms (classes) as their domain. For example, scientificName and Taxon are both Darwin Core terms, and scientificName is a property of the Taxon class (it has Taxon as its domain). When constructing schemas that take advantage of classes in structures, implementors are encouraged to maintain the property/class relationships defined by the terms whenever possible (refer to the Has Domain attribute of the term as given in the Quick Reference Guide [TERMS]). To promote reuse Darwin Core provides a set of xml schemas to use as the basis of additional schemas:

[TERMSXMLSCHEMA] - property term definitions as typed global elements and named groups for all terms for a given class to be referenced. The schema makes use of substitution groups anyClass, anyProperty, anyIdentifier and anyXYZTerm for each class, e.g. anyTaxonTerm. This is the schema upon which the Simple Darwin Core XML Schema [SIMPLEXMLSCHEMA] is based.
[CLASSTERMSXMLSCHEMA] - class term definitions as typed global elements with subelements referencing all corresponding property terms via their substitution group.

It is encouraged to use classes in a normalized way to avoid deep nesting. A Darwin Core Tools and Applications wiki page [TOOLS] has been created as an index to example schemas for the purpose of community discussions and development. An XML schema [CLASSXMLSCHEMA] is provided to freely mix any Darwin Core Class in a global list and allow them to reference each other using the respective class identifier terms. Following is an example of using normalized classes to represent two related specimen occurrences (one of which has had a second identification) at one location following this class-based schema. Note that you can reuse the location definition here by referring to it via locationID:

<?xml version="1.0"?>
<dwr:DarwinRecordSet
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/dwc/dwcrecord/  http://rs.tdwg.org/dwc/xsd/tdwg_dwc_classes.xsd"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:dwc="http://rs.tdwg.org/dwc/terms/"
    xmlns:dwr="http://rs.tdwg.org/dwc/dwcrecord/">
    <dcterms:Location>
        <dwc:locationID>http://guid.mvz.org/sites/arg/127</dwc:locationID>
        <dwc:country>Argentina</dwc:country>
        <dwc:countryCode>AR</dwc:countryCode>
        <dwc:stateProvince>Neuquén</dwc:stateProvince>
        <dwc:locality>25 km al NNE de Bariloche por Ruta 40 (=237)</dwc:locality>
    </dcterms:Location>
    <dwc:Occurrence>
        <dcterms:type>Occurrence</dcterms:type>
        <dcterms:modified>2009-02-12T12:43:31</dcterms:modified>
        <dcterms:rightsHolder>Museum of Vertebrate Zoology</dcterms:rightsHolder>
        <dcterms:rights>Creative Commons License</dcterms:rights>
        <dwc:institutionCode>MVZ</dwc:institutionCode>
        <dwc:collectionCode>Mammals</dwc:collectionCode>
        <dwc:occurrenceID>urn:catalog:MVZ:Mammals:14523</dwc:occurrenceID>
        <dwc:basisOfRecord>PreservedSpecimen</dwc:basisOfRecord>
        <dwc:locationID>http://guid.mvz.org/sites/arg/127</dwc:locationID>
    </dwc:Occurrence>
    <dwc:Identification>
      <dwc:identificationID>http://guid.mvz.org/identifications/23459</dwc:identificationID>
      <dwc:identifiedBy>Richard Sage</dwc:identifiedBy>
      <dwc:dateIdentified>2000</dwc:dateIdentified>
      <dwc:identificationQualifier>sp.</dwc:identificationQualifier>
      <dwc:occurrenceID>urn:catalog:MVZ:Mammals:14523</dwc:occurrenceID>
    </dwc:Identification>
    <dwc:Taxon>
      <dwc:scientificName>Ctenomys</dwc:scientificName>
      <dwc:genus>Ctenomys</dwc:genus>
      <dwc:identificationID>http://guid.mvz.org/identifications/23459</dwc:identificationID>
    </dwc:Taxon>
    <dwc:Identification>
      <dwc:identificationID>http://guid.mvz.org/identifications/94752</dwc:identificationID>
      <dwc:identifiedBy>James L Patton</dwc:identifiedBy>
      <dwc:dateIdentified>2001-09-14</dwc:dateIdentified>
      <dwc:occurrenceID>urn:catalog:MVZ:Mammals:14523</dwc:occurrenceID>
    </dwc:Identification>
    <dwc:Taxon>
      <dwc:scientificName>Ctenomys sociabilis</dwc:scientificName>
      <dwc:higherTaxonName>Animalia, Chordata, Vertebrata, Mammalia, Theria, Eutheria, Rodentia, Hystricognatha, Hystricognathi, Ctenomyidae, Ctenomyini, Ctenomys</dwc:higherTaxonName>
      <dwc:kingdom>Animalia</dwc:kingdom>
      <dwc:phylum>Chordata</dwc:phylum>
      <dwc:class>Mammalia</dwc:class>
      <dwc:order>Rodentia</dwc:order>
      <dwc:family>Ctenomyidae</dwc:family>
      <dwc:genus>Ctenomys</dwc:genus>
      <dwc:specificEpithet>sociabilis</dwc:specificEpithet>
      <dwc:identificationID>http://guid.mvz.org/identifications/94752</dwc:identificationID>
    </dwc:Taxon>
    <dwc:Occurrence>
        <dcterms:type>Occurrence</dcterms:type>
        <dcterms:modified>2009-02-12T12:43:31</dcterms:modified>
        <dcterms:rightsHolder>Museum of Vertebrate Zoology</dcterms:rightsHolder>
        <dcterms:rights>Creative Commons License</dcterms:rights>
        <dwc:institutionCode>MVZ</dwc:institutionCode>
        <dwc:collectionCode>Mammals</dwc:collectionCode>
        <dwc:occurrenceID>urn:catalog:MVZ:Mammals:14524</dwc:occurrenceID>
        <dwc:basisOfRecord>PreservedSpecimen</dwc:basisOfRecord>
        <dwc:locationID>http://guid.mvz.org/sites/arg/127</dwc:locationID>
    </dwc:Occurrence>
    <dwc:Identification>
      <dwc:identificationID>http://guid.mvz.org/identifications/94753</dwc:identificationID>
      <dwc:identifiedBy>James L Patton</dwc:identifiedBy>
      <dwc:dateIdentified>2001-09-14</dwc:dateIdentified>
      <dwc:occurrenceID>urn:catalog:MVZ:Mammals:14524</dwc:occurrenceID>
    </dwc:Identification>
    <dwc:Taxon>
      <dwc:scientificName>Ctenomys sociabilis</dwc:scientificName>
      <dwc:higherTaxonName>Animalia, Chordata, Vertebrata, Mammalia, Theria, Eutheria, Rodentia, Hystricognatha, Hystricognathi, Ctenomyidae, Ctenomyini, Ctenomys</dwc:higherTaxonName>
      <dwc:kingdom>Animalia</dwc:kingdom>
      <dwc:phylum>Chordata</dwc:phylum>
      <dwc:class>Mammalia</dwc:class>
      <dwc:order>Rodentia</dwc:order>
      <dwc:family>Ctenomyidae</dwc:family>
      <dwc:genus>Ctenomys</dwc:genus>
      <dwc:specificEpithet>sociabilis</dwc:specificEpithet>
      <dwc:identificationID>http://guid.mvz.org/identifications/94753</dwc:identificationID>
    </dwc:Taxon>
    <dwc:ResourceRelationship>
        <dwc:resourceRelationshipID>http://guid.mvz.org/relations/23423</dwc:resourceRelationshipID>
        <dwc:resourceID>urn:catalog:MVZ:Mammals:14523</dwc:resourceID>
        <dwc:relatedResourceID>urn:catalog:MVZ:Mammals:14524</dwc:relatedResourceID>
        <dwc:relationshipOfResource>offspring of</dwc:relationshipOfResource>
    </dwc:ResourceRelationship>
    <dwc:ResourceRelationship>
        <dwc:resourceRelationshipID>http://guid.mvz.org/relations/23424</dwc:resourceRelationshipID>
        <dwc:resourceID>urn:catalog:MVZ:Mammals:14524</dwc:resourceID>
        <dwc:relatedResourceID>urn:catalog:MVZ:Mammals:14523</dwc:relatedResourceID>
        <dwc:relationshipOfResource>mother of</dwc:relationshipOfResource>
    </dwc:ResourceRelationship>
</dwr:DarwinRecordSet>

Here is different example demonstrating area count observations for events on two different days at one location:

<?xml version="1.0"?>
<dwr:DarwinRecordSet
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://rs.tdwg.org/dwc/dwcrecord/  http://rs.tdwg.org/dwc/xsd/tdwg_dwc_classes.xsd"
    xmlns:dcterms="http://purl.org/dc/terms/"
    xmlns:dwc="http://rs.tdwg.org/dwc/terms/"
    xmlns:dwr="http://rs.tdwg.org/dwc/dwcrecord/">
    <dcterms:Location>
      <dwc:locationID>http://guid.mvz.org/sites/arg/127</dwc:locationID>
      <dwc:country>Argentina</dwc:country>
      <dwc:countryCode>AR</dwc:countryCode>
      <dwc:stateProvince>Neuquén</dwc:stateProvince>
      <dwc:locality>Valle Limay, Estancia Rincon Grande, 48 ha area with centroid at this point</dwc:locality>
      <dwc:decimalLatitude>-40.97467</dwc:decimalLatitude>
      <dwc:decimalLongitude>-71.0734</dwc:decimalLongitude>
      <dwc:geodeticDatum>WGS84</dwc:geodeticDatum>
      <dwc:coordinateUncertaintyInMeters>200</dwc:coordinateUncertaintyInMeters>
    </dcterms:Location>
    <dwc:Event>
      <dwc:eventID>http://guid.mvz.org/events/2006/11/26/17</dwc:eventID>
      <dwc:samplingProtocol>area count</dwc:samplingProtocol>
      <dwc:eventDate>2006-11-26</dwc:eventDate>
      <dwc:locationID>http://guid.mvz.org/sites/arg/127</dwc:locationID>
    </dwc:Event>
    <dwc:Occurrence>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515288</dwc:occurrenceID>
      <dcterms:type>Occurrence</dcterms:type>
      <dcterms:modified>2009-02-17T07:33:04Z</dcterms:modified>
      <dcterms:rightsHolder>Avian Knowledge Network</dcterms:rightsHolder>
      <dcterms:rights>Creative Commons License</dcterms:rights>
      <dwc:institutionCode>AUDCLO</dwc:institutionCode>
      <dwc:collectionCode>EBIRD</dwc:collectionCode>
      <dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord>
      <dwc:individualCount>2</dwc:individualCount>
      <dwc:eventID>http://guid.mvz.org/events/2006/11/26/17</dwc:eventID>
    </dwc:Occurrence>
    <dwc:Taxon>
      <dwc:scientificName>Anthus hellmayri</dwc:scientificName>
      <dwc:class>Aves</dwc:class>
      <dwc:genus>Anthus</dwc:genus>
      <dwc:specificEpithet>hellmayri</dwc:specificEpithet>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515288</dwc:occurrenceID>
    </dwc:Taxon>
    <dwc:Occurrence>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515286</dwc:occurrenceID>
      <dcterms:type>Occurrence</dcterms:type>
      <dcterms:modified>2009-02-17T07:33:04Z</dcterms:modified>
      <dcterms:rightsHolder>Avian Knowledge Network</dcterms:rightsHolder>
      <dcterms:rights>Creative Commons License</dcterms:rights>
      <dwc:institutionCode>AUDCLO</dwc:institutionCode>
      <dwc:collectionCode>EBIRD</dwc:collectionCode>
      <dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord>
      <dwc:individualCount>1</dwc:individualCount>
      <dwc:eventID>http://guid.mvz.org/events/2006/11/26/17</dwc:eventID>
    </dwc:Occurrence>
    <dwc:Taxon>
      <dwc:scientificName>Anthus correndera</dwc:scientificName>
      <dwc:class>Aves</dwc:class>
      <dwc:genus>Anthus</dwc:genus>
      <dwc:specificEpithet>correndera</dwc:specificEpithet>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515286</dwc:occurrenceID>
    </dwc:Taxon>
    <dwc:Event>
      <dwc:eventID>http://guid.mvz.org/events/2006/11/27/6</dwc:eventID>
      <dwc:samplingProtocol>area count</dwc:samplingProtocol>
      <dwc:eventDate>2006-11-27</dwc:eventDate>
      <dwc:locationID>http://guid.mvz.org/sites/arg/127</dwc:locationID>
    </dwc:Event>
    <dwc:Occurrence>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515333</dwc:occurrenceID>
      <dcterms:type>Occurrence</dcterms:type>
      <dcterms:modified>2009-02-17T07:33:04Z</dcterms:modified>
      <dcterms:rightsHolder>Avian Knowledge Network</dcterms:rightsHolder>
      <dcterms:rights>Creative Commons License</dcterms:rights>
      <dwc:institutionCode>AUDCLO</dwc:institutionCode>
      <dwc:collectionCode>EBIRD</dwc:collectionCode>
      <dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord>
      <dwc:individualCount>1</dwc:individualCount>
      <dwc:eventID>http://guid.mvz.org/events/2006/11/27/6</dwc:eventID>
    </dwc:Occurrence>
    <dwc:Taxon>
      <dwc:scientificName>Anthus hellmayri</dwc:scientificName>
      <dwc:class>Aves</dwc:class>
      <dwc:genus>Anthus</dwc:genus>
      <dwc:specificEpithet>hellmayri</dwc:specificEpithet>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515333</dwc:occurrenceID>
    </dwc:Taxon>
    <dwc:Occurrence>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515331</dwc:occurrenceID>
      <dcterms:type>Occurrence</dcterms:type>
      <dcterms:modified>2009-02-17T07:33:04Z</dcterms:modified>
      <dcterms:rightsHolder>Avian Knowledge Network</dcterms:rightsHolder>
      <dcterms:rights>Creative Commons License</dcterms:rights>
      <dwc:institutionCode>AUDCLO</dwc:institutionCode>
      <dwc:collectionCode>EBIRD</dwc:collectionCode>
      <dwc:basisOfRecord>HumanObservation</dwc:basisOfRecord>
      <dwc:individualCount>2</dwc:individualCount>
      <dwc:eventID>http://guid.mvz.org/events/2006/11/27/6</dwc:eventID>
    </dwc:Occurrence>
    <dwc:Taxon>
      <dwc:scientificName>Anthus hellmayri</dwc:scientificName>
      <dwc:class>Aves</dwc:class>
      <dwc:genus>Anthus</dwc:genus>
      <dwc:specificEpithet>hellmayri</dwc:specificEpithet>
      <dwc:occurrenceID>urn:catalog:AUDCLO:EBIRD:OBS64515331</dwc:occurrenceID>
    </dwc:Taxon>
</dwr:DarwinRecordSet>

Except where otherwise noted, content on this site is licensed under a Creative Commons Attribution 3.0 United States License.