# Darwin Core XML guide Title : Darwin Core XML guide Date version issued : 2023-09-13 Date created : 2009-02-12 Part of TDWG Standard : This version : Latest version : Previous version : Abstract : Guidelines for the implementation of Darwin Core in XML. Contributors : [John Wieczorek](https://orcid.org/0000-0003-1144-0290) ([VertNet](http://www.wikidata.org/entity/Q98382028)), [Markus Döring](https://orcid.org/0000-0001-7757-1889) ([Global Biodiversity Information Facility](http://www.wikidata.org/entity/Q1531570)), [Renato De Giovanni](https://orcid.org/0000-0002-7104-7266) ([Centro de Referência em Informação Ambiental](http://www.wikidata.org/entity/Q29168927)), [Tim Robertson](https://orcid.org/0000-0001-6215-3617) ([Global Biodiversity Information Facility](http://www.wikidata.org/entity/Q1531570)), [Dave Vieglais](https://orcid.org/0000-0002-6513-4996) ([KU Natural History Museum](http://www.wikidata.org/entity/Q1111807)), [Gail Kampmeier](https://orcid.org/0000-0002-5178-4170) ([Illinois Natural History Survey](http://www.wikidata.org/entity/Q5999587)) Creator : Darwin Core Maintenance Group Bibliographic citation : Darwin Core Maintenance Group. 2023. Darwin Core XML guide. Biodiversity Information Standards (TDWG). ## 1 Introduction This document provides guidelines for implementing application schemas based on [Darwin Core terms](../../terms/) using [XML](http://www.w3.org/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. ### 1.1 Status of the content of this document All sections of this document are normative, except for sections that are explicitly marked as non-normative. #### 1.1.1 RFC 2119 key words The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [BCP 14](https://datatracker.ietf.org/doc/html/bcp14) [[RFC2119]](https://datatracker.ietf.org/doc/html/rfc2119) [[RFC8174]](https://datatracker.ietf.org/doc/html/rfc8174) when, and only when, they are written in capitals (as shown here). ### 1.2 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 [Simple Darwin Core](../simple/) and how to build new schemas to meet specific models of information. ## 2 Implementation guide ### 2.1 XML schema Implementors SHOULD base their XML applications on [XML Schemas](http://www.w3.org/XML/Schema) 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 MUST use [XML Namespaces](http://www.w3.org/TR/1999/REC-xml-names-19990114/) to uniquely identify elements. Darwin Core namespaces are defined in the [Darwin Core Namespace Policy](../../namespace/), while Dublin Core namespaces are defined in the [DCMI Namespace Recommendation](http://dublincore.org/documents/dcmi-namespace/). ### 2.3 Abstract model The Darwin Core follows the [Dublin Core Metadata Initiative Abstract Model](http://dublincore.org/documents/abstract-model/) except that the Darwin Core _record_ is roughly equivalent to the Dublin Core _resource_. - A Darwin Core term MUST be either a `class` or a `property` where `class` is defined as http://www.w3.org/2000/01/rdf-schema#Class and `property` is defined as http://www.w3.org/1999/02/22-rdf-syntax-ns#Property. - A `Darwin Core record` MUST be made up of zero or more `classes` and one or more `properties` with their associated `values`. - Each `value` MUST be 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 Darwin Core follows the guidelines for expressing [Dublin Core metadata using XML](http://dublincore.org/documents/dc-xml/) except in that Darwin Core implementors MUST 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 MUST be an XML qualified name (QName), which associates the value given in the `Term name` attribute in the [Darwin Core Terms](../../terms/) recommendation with the appropriate namespace name. For example, use: ```xml ... HumanObservation ``` rather than: ```xml ``` ### 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"`. ```xml ``` An empty string - an element with no content - MUST NOT be used: ```xml ``` ### 2.6 Simple Darwin Core [Simple Darwin Core](tdwg_dwc_simple.xsd) 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](http://rs.tdwg.org/dwc/terms/ResourceRelationship), [MeasurementOrFact](http://rs.tdwg.org/dwc/terms/MeasurementOrFact), and [ChronometricAge](http://rs.tdwg.org/chrono/terms/ChronometricAge). The schema has no required terms and no term is repeated within a given _record_. Refer to [Simple Darwin Core](../simple/) for the rationale behind this schema. The term [`dcterms:type`](http://rs.tdwg.org/dwc/terms/dcterms:type) (which is controlled by the [Dublin Core Type Vocabulary](http://dublincore.org/documents/dcmi-type-vocabulary/)), gives the basic category of object (`PhysicalObject`, `StillImage`, `MovingImage`, `Sound`, `Text`) the record is about. The term [`basisOfRecord`](http://rs.tdwg.org/dwc/terms/basisOfRecord), which has a controlled vocabulary distinct from that of `dcterms:type`, shows the name of the Darwin Core class (e.g., [`Event`](http://rs.tdwg.org/dwc/terms/Event), [`LivingSpecimen`](http://rs.tdwg.org/dwc/terms/LivingSpecimen), [`PreservedSpecimen`](http://rs.tdwg.org/dwc/terms/PreservedSpecimen), [`FossilSpecimen`](http://rs.tdwg.org/dwc/terms/FossilSpecimen), [`MaterialEntity`](http://rs.tdwg.org/dwc/terms/MaterialEntity), [`MaterialCitation`](http://rs.tdwg.org/dwc/terms/MaterialCitation), [`HumanObservation`](http://rs.tdwg.org/dwc/terms/HumanObservation), [`MachineObservation`](http://rs.tdwg.org/dwc/terms/MachineObservation), [`Taxon`](http://rs.tdwg.org/dwc/terms/Taxon)) the record is about. #### 2.6.1 Simple Darwin Core example (non-normative) Following is a brief example of an XML document for a single specimen complying with the [Simple Darwin Core Schema](tdwg_dwc_simple.xsd)]. ```xml PhysicalObject 2009-02-12T12:43:31 en Regents of the University of California http://creativecommons.org/publicdomain/zero/1.0/legalcode PreservedSpecimen MVZ Mammal specimens MVZ:Mamm:14523 male http://arctos.database.museum/guid/MVZ:Mamm:14523?seid=770093 United States US California Kern County 8 mi NE Bakersfield 35.45038 -118.9092 epdg:4267 13696 1911-05-14 Perognathus inornatus inornatus ``` ### 2.7 Classes and containment Many Darwin Core terms (`properties`) are defined as being associated with another term (a `class`). For example, [`scientificName`](http://rs.tdwg.org/dwc/terms/scientificName) and [`Taxon`](http://rs.tdwg.org/dwc/terms/Taxon) are both Darwin Core terms, but `scientificName` is a property organized within the `Taxon` class. When constructing schemas that take advantage of classes in structures, implementors SHOULD maintain the property/class organization for the terms whenever possible (refer to the grouping of the term within a class 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: - [Terms XML Schema](tdwg_dwcterms.xsd) - 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](tdwg_dwc_simple.xsd) is based. - [Class Terms XML Schema](tdwg_dwc_class_terms.xsd) - class term definitions as typed global elements with subelements referencing all corresponding property terms via their substitution group. Classes SHOULD be used in a normalized way to avoid deep nesting. An [XML schema](tdwg_dwc_classes.xsd) 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. #### 2.7.1 Normalized classes examples (non-normative) Following is an example of using a normalized class-based schema to represent two related specimen dwc:Occurrences from one dwc:Event. In this example a Western garter snake collected by Gordon W Gullion in 1949 was found to have eaten a Coastal giant salamander. Note the reuse of class instances by referring to the identifiers declared in the instances of those classes: ```xml http://arctos.database.museum/guid/MVZ:Herp:51568?seid=525813 PhysicalObject PreservedSpecimen MVZ Amphibian and reptile specimens MVZ:Herp:51568 Gordon W. Gullion http://arctos.database.museum/guid/MVZ:Herp:51568 525813 http://arctos.database.museum/MediaSearch.cfm?collection_object_id=10513964 "had stomach contents":"http://arctos.database.museum/guid/MVZ:Herp:51500?seid=670405" http://arctos.database.museum/guid/MVZ:Herp:51568 multicellular organism "ate":"http://arctos.database.museum/guid/MVZ:Herp:51500" 525813 1949-09-02 2 Sep 1949 https://arctos.database.museum/place.cfm?action=detail&locality_id=10754971 https://arctos.database.museum/place.cfm?action=detail&locality_id=10754971 United States US California Humboldt County Raccoon Creek, 3 mi N Willow Creek Museum of Vertebrate Zoology, University of California, Berkeley 1999-01-27 http://arctos.database.museum/guid/MVZ:Herp:51568?seid=525813 https://www.gbif.org/species/2457545 https://www.gbif.org/species/2457545 Thamnophis elegans (Baird & Girard, 1853) species Thamnophis elgans http://arctos.database.museum/guid/MVZ:Herp:51500?seid=670405 PhysicalObject PreservedSpecimen MVZ Amphibian and reptile specimens MVZ:Herp:51500 Gordon W. Gullion 525813 http://arctos.database.museum/MediaSearch.cfm?collection_object_id=10513964 "found as stomach contents of":"http://arctos.database.museum/guid/MVZ:Herp:51568?seid=525813" http://arctos.database.museum/guid/MVZ:Herp:51500 multicellular organism "eaten by":"http://arctos.database.museum/guid/MVZ:Herp:51568" Museum of Vertebrate Zoology, University of California, Berkeley 1999-01-27 http://arctos.database.museum/guid/MVZ:Herp:51500?seid=670405 https://www.gbif.org/species/2432022 https://www.gbif.org/species/2432022 Dicamptodon tenebrosus (Baird & Girard, 1852) species Dicamptodon tenebrosus http://arctos.database.museum/guid/MVZ:Herp:51568 ate http://arctos.database.museum/guid/MVZ:Herp:51500 http://arctos.database.museum/guid/MVZ:Herp:51500 eaten by http://arctos.database.museum/guid/MVZ:Herp:51568 ``` Here is an example demonstrating area count observations for dwc:Events on two different days at the same dcterms:Location. Note that we omit the dwc:Identification class here as there is no identification-related data and link directly to the dwc:Taxon via the `dwc:taxonID`: ```xml AR-NQ-LL-ERG Argentina AR Neuquén Valle Limay, Estancia Rincon Grande, 48 ha area with centroid at this point -40.97467 -71.0734 WGS84 200 JW-AR-NQ-LL-ERG/2006/11/26 area count 2006-11-26 AR-NQ-LL-ERG URN:catalog:CLO:EBIRD:OBS64515288 CLO EBIRD HumanObservation 2 JW-AR-NQ-LL-ERG/2006/11/26 https://www.gbif.org/species/2490280 https://www.gbif.org/species/2490280 Anthus hellmayri Hartert, 1909 Aves Anthus hellmayri URN:catalog:CLO:EBIRD:OBS64515286 CLO EBIRD HumanObservation 4 JW-AR-NQ-LL-ERG/2006/11/26 https://www.gbif.org/species/9286490 https://www.gbif.org/species/9286490 Anthus correndera Vieillot, 1818 Aves Anthus correndera JW-AR-NQ-LL-ERG/2006/11/27 area count 2006-11-27 AR-NQ-LL-ERG URN:catalog:CLO:EBIRD:OBS64515333 CLO EBIRD HumanObservation 2 JW-AR-NQ-LL-ERG/2006/11/27 https://www.gbif.org/species/2490280 urn:catalog:AUDCLO:EBIRD:OBS64515331 CLO EBIRD HumanObservation 4 JW-AR-NQ-LL-ERG/2006/11/27 https://www.gbif.org/species/9286490 ```