From 1c6baafbdb87059491d22442ea98528e1e82bbd4 Mon Sep 17 00:00:00 2001 From: David Bloom Date: Sun, 26 Aug 2018 17:14:57 +1200 Subject: [PATCH] Major edits Deletion of second version (possibly in conflict) at bottom of original document. Code blocks added and named. Other minor md edits for lists. --- standard/documents/xml/index.md | 357 ++------------------------------ 1 file changed, 23 insertions(+), 334 deletions(-) diff --git a/standard/documents/xml/index.md b/standard/documents/xml/index.md index c05371a..3604032 100644 --- a/standard/documents/xml/index.md +++ b/standard/documents/xml/index.md @@ -1,25 +1,3 @@ -<<<<<<< HEAD:guides/xml/index.html Darwin Core XML Guide - -Toggle navigation [Darwin Core](../index.html) - -- [Terms](../../terms/index.html) -- [Examples](../../examples/index.html) -- [Reference](#) - - [Change policy](../../change_policy.html) - - - [Simple Darwin Core](../../simple_dwc.html) - - - [Text guide](../text/index.html) - - [XML guide](../xml/index.html) - - [RDF guide](../rdf/index.html) - - - [Term history](../../terms/history.html) - - [Term decisions](../../terms/decisions.html) - - [Term mappings](../../terms/mappings.html) - -- [Resources](../../resources/index.html) -- [Source](http://github.com/tdwg/dwc) - # Darwin Core XML Guide ## 1\. Introduction @@ -44,36 +22,46 @@ Implementors should use _XML Namespaces_ \[[XMLNS](http://www.w3.org/TR/1999/REC The Darwin Core follows the _Dublin Core Metadata Initiative Abstract Model_ \[[ABSTRACTMODEL](http://dublincore.org/documents/abstract-model/)\] 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](http://dublincore.org/documents/dc-xml/)\] 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](../../index.htm)\] 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 +``` Do not use an empty string \- an element with no content: +```XML +''' ### 2.6 Simple Darwin Core @@ -83,6 +71,7 @@ The term [dcterms:type](../../index.htm#type) (which is controlled by the _Dubli Following is a brief example of an XML document for a single specimen complying with the _Simple Darwin Core Schema_ \[[SIMPLEXMLSCHEMA](../../../xsd/tdwg_dwc_simple.xsd)\]. The Simple Darwin Core XML example document \[[SIMPLEXMLEXAMPLE](../../../examples/xml/example_simple.xml)\] (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 25 km al NNE de Bariloche por Ruta 40 (=237) +``` ### 2.7 Classes and Containment @@ -115,6 +105,7 @@ Many Darwin Core terms (_properties_) are defined as being associated with anoth It is encouraged to use classes in a normalized way to avoid deep nesting. A _Darwin Core Tools and Applications_ wiki page \[[TOOLS](https://github.com/tdwg/dwc-documentation/blob/master/documentation/resources.md)\] has been created as an index to example schemas for the purpose of community discussions and development. An XML schema \[[CLASSXMLSCHEMA](../../../xsd/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. 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 mother of +``` Here is different example demonstrating area count observations for events on two different days at one location. Note that we omit the identification class here as there is not identification related data and link via the taxonID directly: +```XML urn:lsid:catalogueoflife.org:taxon:f000ee00\-29c1\-102b\-9a4a\-00304854f820:col20120721 +``` [![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png)](http://creativecommons.org/licenses/by/4.0/) -- Page last modified on 2015\-03\-13 +- Page last modified on 2015\-03\-13 - [Edit on GitHub](https://github.com/tdwg/dwc/blob/gh-pages/resources.html) (function(i,s,o,g,r,a,m){i\['GoogleAnalyticsObject'\]=r;i\[r\]=i\[r\]||function(){ (i\[r\].q=i\[r\].q||\[\]).push(arguments)},i\[r\].l=1\*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)\[0\];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google\-analytics.com/analytics.js','ga'); ga('create', 'UA\-386033\-4', 'auto'); ga('send', 'pageview'); \======= Darwin Core XML Guide - -Toggle navigation [Darwin Core](../index.html) - -- [Terms](../../terms/index.html) -- [Examples](../../examples/index.html) -- [Reference](#) - - [Change policy](../../change_policy.html) - - - [Simple Darwin Core](../../simple_dwc.html) - - - [Text guide](../text/index.html) - - [XML guide](../xml/index.html) - - [RDF guide](../rdf/index.html) - - - [Term history](../../terms/history.html) - - [Term decisions](../../terms/decisions.html) - - [Term mappings](../../terms/mappings.html) - -- [Resources](../../resources/index.html) -- [Source](http://github.com/tdwg/dwc) - -# Darwin Core XML Guide - -## 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](../../simple/index.htm)\] 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](../../index.htm)\] 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. - -## 2\. Implementation Guide - -### 2.1 XML Schema - -Implementors should base their XML applications on _XML Schemas_ \[[XMLSCHEMA](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 should use _XML Namespaces_ \[[XMLNS](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_ \[[NAMESPACEPOLICY](../../namespace/index.htm)\], while Dublin Core namespaces are defined in the _DCMI Namespace Recommendation_ \[[DCMINS](http://dublincore.org/documents/dcmi-namespace/)\]. - -### 2.3 Abstract model - -The Darwin Core follows the _Dublin Core Metadata Initiative Abstract Model_ \[[ABSTRACTMODEL](http://dublincore.org/documents/abstract-model/)\] 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](http://dublincore.org/documents/dc-xml/)\] 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](../../index.htm)\] with the appropriate namespace name. For example, use - - -... -HumanObservation - -rather than - - - -### 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"_. - - - -Do not use an empty string \- an element with no content: - - - -### 2.6 Simple Darwin Core - -The _Simple Darwin Core_ \[[SIMPLEXMLSCHEMA](../../../xsd/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](../../index.htm#ResourceRelationship) and [MeasurementOrFact](../../index.htm#MeasurementOrFact). The schema has no required terms and no term is repeated within a given _record_. Refer to the _Simple Darwin Core_ page \[[SIMPLEDWC](../../simple/index.htm)\] for the rationale behind this schema. - -The term [dcterms:type](../../index.htm#type) (which is controlled by the _Dublin Core Type Vocabulary_ \[[DCMI\-TYPE](http://dublincore.org/documents/dcmi-type-vocabulary/)\]), gives the basic category of object (PhysicalObject, StillImage, MovingImage, Sound, or Text) the record is about. The term [basisOfRecord](../../index.htm#basisOfRecord), which has a controlled vocabulary distinct from that of _dcterms:type_, shows the name of the Darwin Core class (e.g., LivingSpecimen, PreservedSpecimen, FossilSpecimen, HumanObservation, MachineObservation, Taxon) the record is about. - -Following is a brief example of an XML document for a single specimen complying with the _Simple Darwin Core Schema_ \[[SIMPLEXMLSCHEMA](../../../xsd/tdwg_dwc_simple.xsd)\]. The Simple Darwin Core XML example document \[[SIMPLEXMLEXAMPLE](../../../examples/xml/example_simple.xml)\] (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. - - - - - PhysicalObject - 2009\-02\-12T12:43:31 - Museum of Vertebrate Zoology - Creative Commons License - MVZ - Mammals - urn:catalog:MVZ:Mammals:14523 - PreservedSpecimen - Argentina - AR - Neuquén - 25 km al NNE de Bariloche por Ruta 40 (=237) - - - -### 2.7 Classes and Containment - -Many Darwin Core terms (_properties_) are defined as being associated with another term (a _class_). For example, [scientificName](../../index.htm#ScientificName) and [Taxon](../../index.htm#Taxon) are both Darwin Core terms, but _scientificName_ is a property associated with the _Taxon_ class. 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 _Class_ attribute of the term as given in the _Quick Reference Guide_ \[[TERMS](../../index.htm)\]) or the attribute _dwcattributes:organizedInClass_ in the term declaration in the [dcterms.rdf](../../../rdf/dcterms.rdf) file. To promote reuse, Darwin Core provides a set of xml schemas to use as the basis of additional schemas: - -- \[[TERMSXMLSCHEMA](../../../xsd/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_ \[[SIMPLEXMLSCHEMA](../../../xsd/tdwg_dwc_simple.xsd)\] is based. -- \[[CLASSTERMSXMLSCHEMA](../../../xsd/tdwg_dwc_class_terms.xsd)\] \- 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](https://github.com/tdwg/dwc-documentation/blob/master/documentation/resources.md)\] has been created as an index to example schemas for the purpose of community discussions and development. An XML schema \[[CLASSXMLSCHEMA](../../../xsd/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. 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: - - - - - http://guid.mvz.org/sites/arg/127 - Argentina - AR - Neuquén - 25 km al NNE de Bariloche por Ruta 40 (=237) - - - PhysicalObject - 2009\-02\-12T12:43:31 - MVZ - Mammals - urn:catalog:MVZ:Mammals:14523 - PreservedSpecimen - http://guid.mvz.org/sites/arg/127 - - - http://guid.mvz.org/identifications/23459 - Richard Sage - 2000 - sp. - urn:catalog:MVZ:Mammals:14523 - urn:lsid:catalogueoflife.org:taxon:d79c11aa\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - urn:lsid:catalogueoflife.org:taxon:d79c11aa\-29c1\-102b\-9a4a\-00304854f820:col20120721 - Ctenomys - genus - ICZN - Ctenomys - - - http://guid.mvz.org/identifications/94752 - James L Patton - 2001\-09\-14 - urn:catalog:MVZ:Mammals:14523 - urn:lsid:catalogueoflife.org:taxon:df0a797c\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - urn:lsid:catalogueoflife.org:taxon:df0a797c\-29c1\-102b\-9a4a\-00304854f820:col20120721 - urn:lsid:catalogueoflife.org:taxon:d79c11aa\-29c1\-102b\-9a4a\-00304854f820:col20120721 - Ctenomys sociabilis - Pearson and Christie, 1985 - species - ICZN - Animalia; Chordata; Vertebrata; Mammalia; Theria; Eutheria; Rodentia; Hystricognatha; Hystricognathi; Ctenomyidae; Ctenomyini; Ctenomys - Animalia - Chordata - Mammalia - Rodentia - Ctenomyidae - Ctenomys - sociabilis - - - PhysicalObject - 2009\-02\-12T12:43:31 - MVZ - Mammals - urn:catalog:MVZ:Mammals:14524 - PreservedSpecimen - http://guid.mvz.org/sites/arg/127 - - - http://guid.mvz.org/identifications/94753 - James L Patton - 2001\-09\-14 - urn:catalog:MVZ:Mammals:14524 - urn:lsid:catalogueoflife.org:taxon:df0a797c\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - http://guid.mvz.org/relations/23423 - urn:catalog:MVZ:Mammals:14523 - urn:catalog:MVZ:Mammals:14524 - offspring of - - - http://guid.mvz.org/relations/23424 - urn:catalog:MVZ:Mammals:14524 - urn:catalog:MVZ:Mammals:14523 - mother of - - - -Here is different example demonstrating area count observations for events on two different days at one location. Note that we omit the identification class here as there is not identification related data and link via the taxonID directly: - - - - - http://guid.mvz.org/sites/arg/127 - Argentina - AR - Neuquén - Valle Limay, Estancia Rincon Grande, 48 ha area with centroid at this point - \-40.97467 - \-71.0734 - WGS84 - 200 - - - http://guid.mvz.org/events/2006/11/26/17 - area count - 2006\-11\-26 - http://guid.mvz.org/sites/arg/127 - - - urn:catalog:AUDCLO:EBIRD:OBS64515288 - Event - 2009\-02\-17T07:33:04Z - AUDCLO - EBIRD - HumanObservation - 2 - http://guid.mvz.org/events/2006/11/26/17 - urn:lsid:catalogueoflife.org:taxon:f000ee00\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - urn:lsid:catalogueoflife.org:taxon:f000ee00\-29c1\-102b\-9a4a\-00304854f820:col20120721 - Anthus hellmayri Hartert, 1909 - Aves - Anthus - hellmayri - - - urn:catalog:AUDCLO:EBIRD:OBS64515286 - Event - 2009\-02\-17T07:33:04Z - AUDCLO - EBIRD - HumanObservation - 1 - http://guid.mvz.org/events/2006/11/26/17 - urn:lsid:catalogueoflife.org:taxon:f000e838\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - urn:lsid:catalogueoflife.org:taxon:f000e838\-29c1\-102b\-9a4a\-00304854f820:col20120721 - Anthus correndera Vieillot, 1818 - Aves - Anthus - correndera - - - http://guid.mvz.org/events/2006/11/27/6 - area count - 2006\-11\-27 - http://guid.mvz.org/sites/arg/127 - - - urn:catalog:AUDCLO:EBIRD:OBS64515333 - Event - 2009\-02\-17T07:33:04Z - AUDCLO - EBIRD - HumanObservation - 1 - http://guid.mvz.org/events/2006/11/27/6 - urn:lsid:catalogueoflife.org:taxon:f000ee00\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - urn:catalog:AUDCLO:EBIRD:OBS64515331 - Event - 2009\-02\-17T07:33:04Z - AUDCLO - EBIRD - HumanObservation - 2 - http://guid.mvz.org/events/2006/11/27/6 - urn:lsid:catalogueoflife.org:taxon:f000ee00\-29c1\-102b\-9a4a\-00304854f820:col20120721 - - - -[![Creative Commons License](https://i.creativecommons.org/l/by/4.0/88x31.png)](http://creativecommons.org/licenses/by/4.0/) - -- Page last modified on 2015\-03\-13 -- [Edit on GitHub](https://github.com/tdwg/dwc/blob/gh-pages/resources.html) - -(function(i,s,o,g,r,a,m){i\['GoogleAnalyticsObject'\]=r;i\[r\]=i\[r\]||function(){ (i\[r\].q=i\[r\].q||\[\]).push(arguments)},i\[r\].l=1\*new Date();a=s.createElement(o), m=s.getElementsByTagName(o)\[0\];a.async=1;a.src=g;m.parentNode.insertBefore(a,m) })(window,document,'script','//www.google\-analytics.com/analytics.js','ga'); ga('create', 'UA\-386033\-4', 'auto'); ga('send', 'pageview'); \>>>>>>> 3f4250f44d233b1ab4b22dc0864b9b2ff4d7949f:guides/xml/index.html