search_index.json

[
["eml-ecological-metadata-language.html", "Ecological Metadata Language (EML) 1 EML: Ecological Metadata Language 1.1 Getting Started 1.2 About the EML Project 1.3 Contributing 1.4 History 1.5 Older versions (deprecated) 1.6 Copyright and License 1.7 Funding and Acknowledgements", " Ecological Metadata Language (EML) 2019-08-15 1 EML: Ecological Metadata Language Cite as: Matthew B. Jones, Margaret O’Brien, Bryce Mecum, Carl Boettiger, Mark Schildhauer, Mitchell Maier, Timothy Whiteaker, Steven Chong. 2019. Ecological Metadata Language version 2.2.0. KNB Data Repository. DOI TO BE ISSUED Abstract: The Ecological Metadata Language (EML) defines a comprehensive vocabulary and a readable XML markup syntax for documenting research data. It is in widespread use in the earth and environmental sciences, and increasingly in other research disciplines as well. EML is a community-maintained specification, and evolves to meet the data documentation needs of researchers who want to openly document, preserve, and share data and outputs. EML includes modules for identifying and citing data packages, for describing the spatial, temporal, taxonomic, and thematic extent of data, for describing research methods and protocols, for describing the structure and content of data within sometimes complex packages of data, and for precisely annotating data with semantic vocabularies. EML includes metadata fields to fully detail data papers that are published in journals specializing in scientific data sharing and preservation. EML 2.2.0 Specification Read it online Download EML - The download consists of the EML modules, described in the XML Schema language. In addition, the full documentation on the modules is provided in HTML format. Changes to EML in version 2.1.1 EML Frequently Asked Questions (FAQ) Version: 2.2.0 (In development, not yet released) DOI: (NOT YET ISSUED) Feedback: eml-dev@ecoinformatics.org Bug reports: http://github.com/NCEAS/eml/issues Web site: https://eml.ecoinformatics.org/ Source code: http://github.com/NCEAS/eml Validation service: https://knb.ecoinformatics.org/emlparser/ Slack Discussion channel: #eml on http://slack.nceas.ucsb.edu 1.1 Getting Started Composing an EML document can be done in a simple text editor (e.g., Atom), via scripting languages like R and python (e.g., the R eml package), in general-purpose XML authoring tools (e.g., Oxygen), and in custom web-based metadata editing tools (e.g., MetacatUI). While these tools expand and shift over time, the core metadata language has been consistent and backwards compatible, allowing for decades of seamless interoperability of data sets in many repositories. EML documents can be started simply, and then additional detail added over time. On the simple end, an EML document that provides basic bibliographic information would be sufficient for citing a data set and for simple discovery in catalogs: <?xml version="1.0"?> <eml:eml packageId="doi:10.xxxx/eml.1.1" system="https://doi.org" xmlns:eml="https://eml.ecoinformatics.org/eml-2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:stmml="http://www.xml-cml.org/schema/stmml-1.1" xsi:schemaLocation="https://eml.ecoinformatics.org/eml-2.2.0 xsd/eml.xsd"> <dataset> <title>Primary production of algal species from Southeast Alaska, 1990-2002</title> <creator id="https://orcid.org/0000-0003-0077-4738"> <individualName> <givenName>Matthew</givenName> <givenName>B.</givenName> <surName>Jones</surName> </individualName> <electronicMailAddress>jones@nceas.ucsb.edu</electronicMailAddress> <userId directory="https://orcid.org">https://orcid.org/0000-0003-0077-4738</userId> </creator> <keywordSet> <keyword>biomass</keyword> <keyword>productivity</keyword> </keywordSet> <contact> <references>https://orcid.org/0000-0003-0077-4738</references> </contact> </dataset> </eml:eml> This document can then be supplemented with additional metadata describing research projects and methods, structural information about the data, and much more. 1.2 About the EML Project The EML project is an open source, community oriented project dedicated to providing a high-quality metadata specification for describing data relevant to the ecological discipline. The project is completely comprised of voluntary project members who donate their time and experience in order to advance information management for ecology. Project decisions are made by consensus according to the voting procedures described in the ecoinformatics.org Charter. We welcome contributions to this work in any form. Individuals who invest substantial amounts of time and make valuable contributions to the development and maintenance of EML (in the opinion of current project members) will be invited to become EML project members according to the rules set forth in the ecoinformatics.org Charter. Contributions can take many forms, including the development of the EML schemas, writing documentation, and helping with maintenance, among others. 1.3 Contributing Developers may be interested in browsing the source code repository that we use in developing EML. Starting with EML 2.1.1, the master branch reflects the current stable release of EML. Developmet occurs in development branches (e.g., BRANCH_EML_2_2), which allows experimental additions as they are being proposed by the community. This always contains the most recent development version of EML, and therefore may be in flux, or otherwise broken. It is unlikely that it will contain the same files that are in the current release. Development branches are virtually guaranteed to change before they are released, and so they should not be used in production environments. Use development branches at your own risk for testing. Write access to this repository is reserved for current project maintainers. Please submit contributions as pull requests. We welcome contributions to this work in any form. Contributions can take many forms, including the development of the EML schema, writing documentation, and helping with maintenance, among others. Non-project members can contribute by submitting their feedback, revisions, fixes, code, or any other contribution through pull requests at GitHub. Discussion of issues occurs on the eml-dev@ecoinformatics.org mailing list, or through the EML Issue Tracking system. The preferred way to submit problems with EML or feature requests is the issue tracking system. 1.4 History EML was originally developed by Matthew Jones at NCEAS based on work done by the ESA Committee on the Future of Long-Term Ecological Data and on a related paper on ecological metadata by Michener et al. (see Michener, William K., et al., 1997. Ecological Applications, “Nongeospatial metadata for the ecological sciences” Vol 7(1). pp. 330-342.). Version 1.0 was released at NCEAS in 1997 and used internally, with further internal releases of versions 1.2, 1.3, and 1.4, all of which followed the FLED recommendations closely in its content implementation. Version 2 was modified substantially after experience using the specification at NCEAS and from feedback from the ecological community, particularly the Long Term Ecological Research Network. Versions 2.1 and 2.2 introduce significant new features like internationalization, semantic annotations, and support for data papers. 1.5 Older versions (deprecated) The following versions are still available for reference purposes, although they have been superseded by the current version (2.2.0). Please make every effort to use the current version. EML 2.1.1 EML 2.1.0 EML 2.0.1 EML 2.0.0 EML 1.4.1 1.6 Copyright and License Copyright: 1997-2019 Regents of the University of California This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA 1.7 Funding and Acknowledgements EML was developed and is maintained with support from the National Center for Ecological Analysis and Synthesis (NCEAS), a Center funded by the University of California Santa Barbara and the state of California. This material is based upon work supported by the US National Science Foundation under Grant No. DEB-9980154, DBI-9904777, 0225676, DEB-0072909, DBI-9983132, and DEB-9634135. Any opinions, findings and conclusions or recommendations expressed in this material are those of the author(s) and do not necessarily reflect the views of the National Science Foundation (NSF). This product includes software developed by the Apache Software Foundation (http://www.apache.org/). See the LICENSE file in lib/apache for details. The source code, object code, and documentation in the com.oreilly.servlet package is copyright and owned by Jason Hunter. See the cos-license.html file for details of the license. Licensor retains title to and ownership of the Software and all enhancements, modifications, and updates to the Software. This product includes software developed by the JDOM Project (http://www.jdom.org/). See jdom-LICENSE.txt for details. "],
["features.html", "2 Features", " 2 Features The architecture of EML was designed to serve the needs of the research community, and has benefitted from previous work in other related metadata languages. EML has adopted the strengths of many of these languages, but also addresses a number of shortcomings that have inhibited the automated processing and integration of dataset resources via their metadata. The following list represents some of the features of EML: Modularity: EML was designed as a collection of modules rather than one large standard to facilitate future growth of the language in both breadth and depth. By implementing EML with an extensible architecture, groups may choose which of the core modules are pertinent to describing their data, literature, and software resources. Also, if EML falls short in a particular area, it may be extended by creating a new module that describes the resource ( e.g. a detailed soils metadata profile that extends eml-dataset). The intent is to provide a common set of core modules for information exchange, but to allow for future customizations of the language without the need of going through a lengthy approval process. Detailed Structure: EML strives to balance the tradeoff of too much detail with enough detail to enable advanced services in terms of processing data through the parsing of accompanied metadata. Therefore, a driving question throughout the design was: ‘Will this particular piece of information be machine-processed, just human readable, or both?’ Information was then broken down into more highly structured elements when the answer involved machine processing. Compatibility: EML adopts much of it’s syntax from the other metadata standards that have evolved from the expertise of groups in other disciplines. Whenever possible, EML adopted entire trees of information in order to facilitate conversion of EML documents into other metadata languages. EML was designed with the following standards in mind: Dublin Core Metadata Initiative, the Content Standard for Digital Geospatial Metadata (CSDGM from the Federal Geographic Data Committee (FGDC)), the Biological Profile of the CSDGM (from the National Biological Information Infrastructure), the International Standards Organization’s Geographic Information Standard (ISO 19115), the ISO 8601 Date and Time Standard, the OpenGIS Consortiums’s Geography Markup Language (GML), the Scientific, Technical, and Medical Markup Language (STMML), and the Extensible Scientific Interchange Language (XSIL). Strong Typing: EML is implemented in an Extensible Markup Language (XML) known as XML Schema, which is a language that defines the rules that govern the EML syntax. XML Schema is an internet recommendation from the World Wide Web Consortium, and so a metadata document complies with the syntax of EML will structurally meet the criteria defined in the XML Schema documents for EML. Over and above the structure (what elements can be nested within others, cardinality, etc.), XML Schema provides the ability to use strong data typing within elements. This allows for finer validation of the contents of the element, not just it’s structure. For instance, an element may be of type ‘date’, and so the value that is inserted in the field will be checked against XML Schema’s definition of a date. Traditionally, XML documents (including previous versions of EML) have been validated against Document Type Definitions (DTDs), which do not provide a means to employ strong validation on field values through typing. There is a distinction between the content model (i.e. the concepts behind the structure of a document - which fields go where, cardinality, etc.) and the syntactic implementation of that model (the technology used to express the concepts defined in the content model). The normative sections below define the content model and the XML Schema documents distributed with EML define the syntactic implementation. For the foreseeable future, XML Schema will be the syntactic specification, although it is reasonable to create other syntactic representations of the vocabularly, such as in JSON-LD or RDF. "],
["contributors.html", "3 Contributors 3.1 Current contributors 3.2 Past contributors", " 3 Contributors The EML project is an open source, community oriented project dedicated to providing a high-quality metadata specification for describing data relevant to the ecological discipline. The project is completely comprised of voluntary project members who donate their time and experience in order to advance information management for ecology. Project decisions are made by concensus according to the voting procedures described in the ecoinformatics.org Charter. We welcome contributions to this work in any form. Individuals who invest substantial amounts of time and make valuable contributions to the development and maintenance of EML (in the opinion of current project members) will be invited to become EML project members according to the rules set forth in the ecoinformatics.org Charter. Contributions can take many forms, including the development of the EML schemas, writing documentation, and helping with maintenance, among others. Write access to the EML source code repository is reserved for EML project members. Contributions should be submitted as pull requests, and will be reviewed and merged by an EML project member. 3.1 Current contributors Name Organization Email Matthew Jones NCEAS, UCSB jones@nceas.ucsb.edu Mark Schildhauer NCEAS, UCSB schild@nceas.ucsb.edu Chris Jones NCEAS, UCSB cjones@nceas.ucsb.edu Corinna Gries EDI, UW gries@ecoinformatics.org Margaret O’Brien EDI, UCSB mob@msi.ucsb.edu Bryce Mecum NCEAS, UCSB mecum@nceas.ucsb.edu Carl Boettiger Berkeley cboettig@berkeley.edu Mitchell Maier NCEAS, UCSB Timothy Whiteaker whiteaker@utexas.edu Stevan Earl LTER, ASU stevan.earl@asu.edu Steven Chong NCEAS, UCSB chong@nceas.ucsb.edu 3.2 Past contributors Name Organization Email Chad Berkley NCEAS, UCSB berkley@nceas.ucsb.edu Jivka Bojilova NCEAS, UCSB bojilova@nceas.ucsb.edu James Brunt LTER, UNM brunt@ecoinformatics.org David Blankman LTER-Israel, Ma’arg blankman@ecoinformatics.org Owen Eddins LTER LNO, UNM oeddins@lternet.edu Daniel Higgens NCEAS, UCSB higgins@nceas.ucsb.edu Peter McCartney LTER CAP, ASU mccartney@ecoinformatics.org Matthew Brooke NCEAS, UCSB brooke@ecoinformatics.org John Harris NCEAS, UCSB harris@nceas.ucsb.edu Scott Chapal Jones Ecological Research Center chapal@ecoinformatics.org Tim Bergsma LTER KBS, MSU bergsma@ecoinformatics.org Ken Ramsey LTER JRN, NMSU ramsey@ecoinformatics.org Saurabh Garg NCEAS, UCSB sgarg@ecoinformatics.org Mark Servilla EDI, UNM servilla@ecoinformatics.org "],
["whats-new-in-eml-2-2-0.html", "4 What’s New in EML 2.2.0", " 4 What’s New in EML 2.2.0 This document highlights changes and new features in EML 2.2. EML authors should also refer to the affected sections in the normative schema documents for complete usage information and examples. EML 2.2 is backward compatible, i.e., EML 2.0 and 2.1 documents could be relabled as EML 2.2 without violating the schema. However, some predefined values, particularly units, are deprecated in favor of new values to fix mispellings or inconsistencies. EML authors are encouraged to migrate away from deprecated values. EML MAINTAINERS: Is this in the works?????? > Existing EML 2.1-series documents can be converted to EML 2.2.0 using the XSL > stylesheet that accompanies this release, as described in section 2 below. See the ‘Readme’ that accompanies the distribution for a complete list of the bugs addressed, and for information of interest to developers. Q: Unit Additions and Changes A: Many units were added for EML 2.2.0, including units supporting oceanography, climatology, forestry and limnology. The following unit types from the unit dictionary have been renamed to better reflect their dimensionality: massFlux is now massRate arealMassDensityRate is now massFlux amountOfSubstanceWeightFlux is now amountOfSubstanceWeightRate Dozens of units are now deprecated in favor other units to address issues such as naming consistency. Use the “deprecatedInFavorOf” attribute in eml-unitDictionary.xml to identify deprecated units. Q: BibTeX Support A: CitationType elements can use the new <bibtex> element as an alternative to encoding citations in the EML XML structures. BibTeX entries generally play well inside of XML structures, but XML escaping is still needed for special characters, so consider embedding BibTeX entries in CDATA blocks if XML escaping becomes cumbersome. <citation> <bibtex> @article{fegraus_2005, title = {Maximizing the {Value} of {Ecological} {Data} with {Structured} {Metadata}: {An} {Introduction} to {Ecological} {Metadata} {Language} ({EML}) and {Principles} for {Metadata} {Creation}}, journal = {Bulletin of the Ecological Society of America}, author = {Fegraus, Eric H. and Andelman, Sandy and Jones, Matthew B. and Schildhauer, Mark}, year = {2005}, pages = {158--168} } </bibtex> </citation> Q: Citation Lists A: EML 2.2.0 includes a new <literatureCited> element as a CitationListType that represents one or more citations. These citations can be a series of <citation> elements or a <bibtex> element with a list of citations. Example of <literatureCited> element in EML 2.2.0: <literatureCited> <citation> <bibtex> @article{fegraus_2005, title = {Maximizing the {Value} of {Ecological} {Data} with {Structured} {Metadata}: {An} {Introduction} to {Ecological} {Metadata} {Language} ({EML}) and {Principles} for {Metadata} {Creation}}, journal = {Bulletin of the Ecological Society of America}, author = {Fegraus, Eric H. and Andelman, Sandy and Jones, Matthew B. and Schildhauer, Mark}, year = {2005}, pages = {158--168} } </bibtex> </citation> <citation> <title>Title of a paper that this dataset, or its metadata, references.</title> <creator> <individualName> <givenName>Mark</givenName> <surName>Jarkady</surName> </individualName> </creator> <pubDate>2017</pubDate> <article> <journal>EcoSphere</journal> <publicationPlace>https://doi.org/10.1002/ecs2.2166</publicationPlace> </article> </citation> <bibtex> @article{hampton_2017, title = {Skills and {Knowledge} for {Data}-{Intensive} {Environmental} {Research}}, volume = {67}, copyright = {All rights reserved}, issn = {0006-3568, 1525-3244}, url = {https://academic.oup.com/bioscience/article-lookup/doi/10.1093/biosci/bix025}, doi = {10.1093/biosci/bix025}, language = {en}, number = {6}, urldate = {2018-02-15}, journal = {BioScience}, author = {Hampton, Stephanie E. and Jones, Matthew B. and Wasser, Leah A. and Schildhauer, Mark P. and Supp, Sarah R. and Brun, Julien and Hernandez, Rebecca R. and Boettiger, Carl and Collins, Scott L. and Gross, Louis J. and Fernández, Denny S. and Budden, Amber and White, Ethan P. and Teal, Tracy K. and Labou, Stephanie G. and Aukema, Juliann E.}, month = jun, year = {2017}, pages = {546--557} } @article{collins_2018, title = {Temporal heterogeneity increases with spatial heterogeneity in ecological communities}, volume = {99}, copyright = {All rights reserved}, issn = {00129658}, url = {http://doi.wiley.com/10.1002/ecy.2154}, doi = {10.1002/ecy.2154}, language = {en}, number = {4}, urldate = {2018-04-16}, journal = {Ecology}, author = {Collins, Scott L. and Avolio, Meghan L. and Gries, Corinna and Hallett, Lauren M. and Koerner, Sally E. and La Pierre, Kimberly J. and Rypel, Andrew L. and Sokol, Eric R. and Fey, Samuel B. and Flynn, Dan F. B. and Jones, Sydney K. and Ladwig, Laura M. and Ripplinger, Julie and Jones, Matt B.}, month = apr, year = {2018}, pages = {858--865} } </bibtex> </literatureCited> Q: Markdown Support A: TextType elements can include GitHub Flavored Markdown using the new <markdown> element. See the description for the <markdown> element in eml-text.xsd for more details on embedded images, inline citations, and formatting considerations regarding special characters and indentation. Example of markdown in EML 2.2.0: <markdown> An introduction goes here. It can include multiple paragraphs. And these paragraphs should have enough text to wrap in a wide browser. So, repeat that last thought. And these paragraphs should have enough text to wrap in a wide browser. So, repeat that last thought. Text can cite other works, such as [@jones_2001], in which case the associated key must be present as either the citation identifier in a `bibtex` element in the EML document, or as the `id` attribute on one of the `citation` elements in the EML document. These identifiers must be unique across the document. And bulleted lists are also supported: - Science - Engineering - Math It can also include equations: $$\\left( x + a \\right)^{n} = \\sum_{k = 0}^{n}{\\left( \\frac{n}{k} \\right)x^{k}a^{n - k}}$$ Plus, it can include all of the other features of [Github Flavored Markdown (GFM)](https://github.github.com/gfm/). </markdown> Q: Usage Citations A: EML 2.2.0 documents can include a non-comprehensive list of citations in which the data were explicitly used via a <usageCitation> element, which is a CitationType. Example usageCitation element: <dataset> ... <usageCitation> <bibtex> @article{jones_2001, title = {Managing scientific metadata}, volume = {5}, issn = {10897801}, url = {http://ieeexplore.ieee.org/lpdocs/epic03/wrapper.htm?arnumber=957896}, doi = {10.1109/4236.957896}, number = {5}, journal = {IEEE Internet Computing}, author = {Jones, Matthew B. and Berkley, Chad and Bojilova, Jivka and Schildhauer, Mark}, year = {2001}, pages = {59--68} } </bibtex> </usageCitation> ... </dataset> Q: Reference Publications A: For cases when a research paper illustrates the usage of a dataset, the new <referencePublication> element can be used to associate the dataset with the paper. <dataset> ... <referencePublication> <bibtex> @article{ludwig_2018, title = {Permafrost carbon and nitrogen, Yukon-Kuskokwim Delta, Alaska}, url = {http://ecosphere.esa.org/article/yyyy.zzzzzzz}, doi = {10.xxxx/yyyy.zzzzzz}, journal = {EcoSphere}, author = {Ludwig, Sarah}, year = {2018} } </bibtex> </referencePublication> ... </dataset> Q: Data Paper Support A: ESA and other societies are moving towards the publication of data papers that include more complete narratives about a data set and its importance and use. To support data papers, EML 2.2.0 includes new optional fields for Introduction, Getting Started, and Acknowledgements, as well as markdown and citation-related elements described elsewhere in this document. See the example EML document for a data paper. Q: Dataset license A: Datasets can now include a <licensed> element along with a URL to a license. <dataset> ... <licensed> <licenseName>Creative Commons Attribution 4.0 International</licenseName> <url>https://spdx.org/licenses/CC-BY-4.0.html</url> <identifier>CC-BY-4.0</identifier> </licensed> ... </dataset> Q: Structured Funding Information A: EML 2.2.0 sees the addition of an <award> element to support structured funding information for a research project. This is used as an alternative or in addition to the <funding> element which is a text type. <project> ... <funding><para>Funding is from a grant from the National Science Foundation.</para></funding> <award> <funderName>National Science Foundation</funderName> <funderIdentifier>https://doi.org/10.13039/00000001</funderIdentifier> <awardNumber>1546024</awardNumber> <title>Scientia Arctica: A Knowledge Archive for Discovery and Reproducible Science in the Arctic</title> <awardUrl>https://www.nsf.gov/awardsearch/showAward?AWD_ID=1546024</awardUrl> </award> </project> Q: “unkown” deprecated as <maintenanceUpdateFrequency> element value. A: Some EML documents have specified “unkown” instead of “unknown” for the maintenanceUpdateFrequency because there is a typo in the list of allowed values in eml-dataset.xsd. For EML 2.2.0, a value of “unknown” is added to the list, while the the original value of “unkown” is kept in the enumeration for backwards compatibility with a note that its use is deprecated. Q: Accommodating Semantic Metadata A: See EML Semantic Annotation Primer EML 2.2.0 supports entering terms from an ontology via <annotation> elements to further describe items such as data attributes, entity groups, and resource groups. Annotations are allowed in five locations in the EML document: in attribute, entity, and dataset (or other resource) elements in an /eml/annotations root element in /eml/additionalMetadata When the annotation is embedded in a containing EML attribute element, the annotation’s subject is that attribute: <attribute id="att.12"> <attributeName>biomass</attributeName> ... <annotation> <propertyURI label="of characteristic">http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#ofCharacteristic</propertyURI> <valueURI label="Mass">http://ecoinformatics.org/oboe/oboe.1.2/oboe-characteristics.owl#Mass</valueURI> </annotation> <annotation> <propertyURI label="of entity">http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#ofEntity</propertyURI> <valueURI label="Plant Sample">http://example.com/example-vocab-1.owl#PlantSample</valueURI> </annotation> </attribute> For annotations in /eml/annotations, the subject of the annotation is established using a references attribute that points at the id of the subject of the annotation: <annotations> <annotation references="CDR-biodiv-table"> <propertyURI label="Subject">http://purl.org/dc/elements/1.1/subject</propertyURI> <valueURI label="grassland biome">http://purl.obolibrary.org/obo/ENVO_01000177</valueURI> </annotation> </annotations> For annotations in /eml/additionalMetadata, the subject is the element with the id listed within the associated <describes> element: <additionalMetadata> <describes>adam.shepherd</describes> <metadata> <annotation> <propertyURI label="member of">https://schema.org/memberOf</propertyURI> <valueURI label="BCO-DMO">https://doi.org/10.17616/R37P4C</valueURI> </annotation> </metadata> </additionalMetadata> Q: Support for ids in <taxonomicClassification> element A: <taxonomicClassification> elements can now include a reference to external identifiers, e.g., to a code from a system like ITIS or WoRMS. <taxonomicClassification id="taxon_MAPY"> <taxonRankName>species</taxonRankName> <taxonRankValue>Macrocystis pyrifera</taxonRankValue> <commonName>Giant Kelp</commonName> <taxonId provider="ITIS">11274</taxonId> <taxonId provider="https://www.ncbi.nlm.nih.gov/taxonomy">35122</taxonId> </taxonomicClassification> Q: How can I convert from earlier versions of EML? A: An XSL stylesheet is provided with the EML Utilities to convert valid EML 2.1-series documents to EML 2.2.0 (see http://knb.ecoinformatics.org/software/eml/). The stylesheet performs basic tasks to create a template EML 2.2.0 document. For more information, see the Utilities documentation. Q: Validity of new EML 2.2.0 documents A: Because of the flexibility allowed in EML, the stylesheet may encounter EML 2.1.0/1 structures that cannot be transformed or that may result in invalid EML 2.2.0 after processing. For example, by design <additionalMetadata> sections are parsed laxly, and so it is possible for their content in EML-2.1.0/1 to contain <access> trees which are invalid. Document authors are advised to check the validity of their new EML 2.2.0 after transformation. EML instance documents can be validated in these ways: With the online EML Parser. The online parser will validate all versions of EML. Using the Parser that comes with EML. To execute it, change into the ‘lib’ directory of the EML release and run the ‘runEMLParser’ script passing your EML instance file as a parameter. The script performs two actions: it checks the validity of references and id attributes, and it validates the document against the EML 2.2 schema. The EML parser included with the distribution is capable of checking only EML 2.2.0 documents, and cannot be used to validate earlier versions (e.g., EML 2.1.1). If you are planning to contribute your EML 2.2.0 document to a Metacat repository, note that the Metacat servlet checks all versions of incoming EML for validity as part of the insertion process. "],
["the-eml-module-and-resources.html", "5 The EML Module and Resources 5.1 The eml module - A metadata container 5.2 The eml-resource module - Base information for all resources 5.3 The eml-dataset module - Dataset specific information 5.4 The eml-literature module - Citation-specific information 5.5 The eml-software module - Software specific information 5.6 The eml-protocol module - Research protocol specific information", " 5 The EML Module and Resources 5.1 The eml module - A metadata container The eml module is a wrapper container that allows the inclusion of any metadata content in a single EML document. The eml module is used as a container to hold structured descriptions of ecological resources. In EML, the definition of a resource comes from the The Dublin Core Metadata Initiative, which describes a general element set used to describe "networked digital resources". The top-level structure of EML has been designed to be compatible with the Dublin Core syntax. In general, dataset resources, literature resources, software resources, and protocol resources comprise the list of information that may be described in EML. EML is largely designed to describe digital resources, however, it may also be used to describe non-digital resources such as paper maps and other non-digital media. In EML, the definition of a "Data Package" is the combination of both the data and metadata for a resource. So, data packages are built by using the <eml> wrapper, which will include all of the metadata, and optionally the data (or references to them). All EML packages must begin with the <eml> tag and end with the </eml> tag. The eml module may be extended to describe other resources by means of its optional sub-field, <additionalMetadata>. This field is largely reserved for the inclusion of metadata that may be highly discipline specific and not covered in this version of EML, or it may be used to internally extend fields within the EML standard. 5.2 The eml-resource module - Base information for all resources The eml-resource module contains general information that describes dataset resources, literature resources, protocol resources, and software resources. Each of the above four types of resources share a common set of information, but also have information that is unique to that particular resource type. Each resource type uses the eml-resource module to document the information common to all resources, but then extend eml-resource with modules that are specific to that particular resource type. For instance, all resources have creators, titles, and perhaps keywords, but only the dataset resource would have a "data table" within it. Likewise, a literature resource may have an "ISBN" number associated with it, whereas the other resource types would not. The eml-resource module is exclusively used by other modules, and is therefore not a stand-alone module. The following four modules are used to describe separate resources: datasets, literature, software, and protocols. However, note that the dataset module makes use of the other top-level modules by importing them at different levels. For instance, a dataset may have been produced using a particular protocol, and that protocol may come from a protocol document in a library of protocols. Likewise, citations are used throughout the top-level resource modules by importing the literature module. 5.3 The eml-dataset module - Dataset specific information The eml-dataset module contains general information that describes dataset resources. It is intended to provide overview information about the dataset: broad information such as the title, abstract, keywords, contacts, maintenance history, purpose, and distribution of the data themselves. The eml-dataset module also imports many other modules that are used to describe the dataset in fine detail. Specifically, it uses the eml-methods module to describe methodology used in collecting or processing the dataset, the eml-project module to describe the overarching research context and experimental design, the eml-access module to define access control rules for the data and metadata, and the eml-entity module to provide detailed information about the logical structure of the dataset. A dataset can be (and often is) composed of a series of data entities (tables) that are linked together by particular integrity constraints. The eml-dataset module, like other modules, may be "referenced" via the <references> tag. This allows a dataset to be described once, and then used as a reference in other locations within the EML document via its ID. 5.4 The eml-literature module - Citation-specific information The eml-literature module contains information that describes literature resources. It is intended to provide overview information about the literature citation, including title, abstract, keywords, and contacts. Citation types follow the conventions laid out by EndNote, and there is an attempt to represent a compatible subset of the EndNote citation types. These citation types include: article, book, chapter, edited book, manuscript, report, thesis, conference proceedings, personal communication, map, generic, audio visual, and presentation. The generic citation type would be used when one of the other types will not work. There are three unique CitationType elements that may be employed within a eml-dataset module, including the <literatureCited>, <usageCitation>, and <referencePublication> elements. The purpose and examples of each CitationType element type are detailed below. Similar to other eml modules, each of the CitationType elements may be referenced via the <references> tag. The <references> tag allows a citation to be described once then used as a reference in other locations within the EML document via its reference ID. As of EML 2.2.0, each CitationType element can use the <bibtex> element as an alternative to encoding citations in the EML XML structures. BibTeX entries generally play well inside of XML structures, but XML escaping is still needed for special characters so consider embedding BibTeX entries in CDATA blocks if XML escaping is cumbersome. 5.4.1 eml-literature module - literature cited Citations to articles or other resources that are referenced in the data set or its associated metadata should be included in a <literatureCited> element. <literatureCited> is a CitationListType cataloging one or more citations that represent a bibliography of works related to the data set for reference, comparison, or other purposes. These citations can be a series of <citation> elements, a <bibtex> element featuring one or more BibTeX-style citations, or a mix of the two types. Example of the <literatureCited> element: <dataset> ... <literatureCited> <citation> <bibtex> @article{fegraus_2005, title = {Maximizing the {Value} of {Ecological} {Data} with {Structured} {Metadata}: {An} {Introduction} to {Ecological} {Metadata} {Language} ({EML}) and {Principles} for {Metadata} {Creation}}, journal = {Bulletin of the Ecological Society of America}, author = {Fegraus, Eric H. and Andelman, Sandy and Jones, Matthew B. and Schildhauer, Mark}, year = {2005}, pages = {158--168} } </bibtex> </citation> <citation> <title>Title of a paper that this dataset, or its metadata, references.</title> <creator> <individualName> <givenName>Mark</givenName> <surName>Jarkady</surName> </individualName> </creator> <pubDate>2017</pubDate> <article> <journal>EcoSphere</journal> <publicationPlace>https://doi.org/10.1002/ecs2.2166</publicationPlace> </article> </citation> <bibtex> @article{hampton\\_2017, title = {Skills and {Knowledge} for {Data}-{Intensive} {Environmental} {Research}}, volume = {67}, copyright = {All rights reserved}, issn = {0006-3568, 1525-3244}, url = {https://academic.oup.com/bioscience/article-lookup/doi/10.1093/biosci/bix025}, doi = {10.1093/biosci/bix025}, language = {en}, number = {6}, urldate = {2018-02-15}, journal = {BioScience}, author = {Hampton, Stephanie E. and Jones, Matthew B. and Wasser, Leah A. and Schildhauer, Mark P. and Supp, Sarah R. and Brun, Julien and Hernandez, Rebecca R. and Boettiger, Carl and Collins, Scott L. and Gross, Louis J. and Fernández, Denny S. and Budden, Amber and White, Ethan P. and Teal, Tracy K. and Labou, Stephanie G. and Aukema, Juliann E.}, month = jun, year = {2017}, pages = {546--557} } @article{collins\\_2018, title = {Temporal heterogeneity increases with spatial heterogeneity in ecological communities}, volume = {99}, copyright = {All rights reserved}, issn = {00129658}, url = {http://doi.wiley.com/10.1002/ecy.2154}, doi = {10.1002/ecy.2154}, language = {en}, number = {4}, urldate = {2018-04-16}, journal = {Ecology}, author = {Collins, Scott L. and Avolio, Meghan L. and Gries, Corinna and Hallett, Lauren M. and Koerner, Sally E. and La Pierre, Kimberly J. and Rypel, Andrew L. and Sokol, Eric R. and Fey, Samuel B. and Flynn, Dan F. B. and Jones, Sydney K. and Ladwig, Laura M. and Ripplinger, Julie and Jones, Matt B.}, month = apr, year = {2018}, pages = {858--865} } </bibtex> </literatureCited> ... </dataset> 5.4.2 eml-literature module - usage citation A citation to an article or other resource in which the data set is used or referenced should be included in a <usageCitation> element, a CitationType detailing a literature resource that has used or references this data set. It is not expected that one or more usage citations will necessarily be an exhaustive list of resources that employ the data set, but rather will serve as a example(s) and pointer(s) to scholarly works in which this data set has been used. The <usageCitation> element can be a <citation> or <bibtex> element. Example of the element: <dataset> ... <usageCitation> <citation> <title>Title of a paper that uses this dataset or its metadata</title> <creator> <individualName> <givenName>Mark</givenName> <surName>Jarkady</surName> </individualName> </creator> <pubDate>2017</pubDate> <article> <journal>EcoSphere</journal> <publicationPlace>https://doi.org/10.1002/ecs2.2166</publicationPlace> </article> </citation> </usageCitation> <usageCitation> <bibtex> <![CDATA[ @article{doi:10.1890/10-0423.1, author = {Lerman, Susannah B. and Warren, Paige S.}, title = {The conservation value of residential yards: linking birds and people}, journal = {Ecological Applications}, volume = {21}, number = {4}, pages = {1327-1339}, keywords = {Arizona, USA, CAP LTER, human–wildlife interactions, long-term ecological research, native landscaping, residential yards, socio-ecology, urban birds}, doi = {10.1890/10-0423.1}, url = {https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/10-0423.1}, eprint = {https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/10-0423.1} } ]]> </bibtex> </usageCitation> ... </dataset> 5.4.3 eml-literature module - reference publication A citation to an article or other resource that serves as an important reference for a data set should be documented in a <referencePublication> element. Anyone using the data set should generally cite the data set itself (using the creator, pubDate, title, publisher, and packageId fields), and consider providing an additional citation to the reference publication. The <referencePublication> element will typically be used when the data set and a companion or associated paper are published near concurrently. Common cases where a reference publication may be useful include when a data paper is published that describes the dataset, or when a paper is intended to be the canonical or exemplar reference to the dataset – these are features that distinguish the <referencePublication> CitationType from the <usageCitation> CitationType. Example of the <referencePublication> element: <dataset> ... <referencePublication> <bibtex> @article{doi:10.1890/14-2252.1, author = {Edwards, Kyle F. and Klausmeier, Christopher A. and Litchman, Elena}, title = {Nutrient utilization traits of phytoplankton}, journal = {Ecology}, volume = {96}, number = {8}, pages = {2311-2311}, keywords = {algae, allometry, competition, Droop, Monod, nitrogen, phosphorus, physiology, stoichiometry, uptake kinetics}, doi = {10.1890/14-2252.1}, url = {https://esajournals.onlinelibrary.wiley.com/doi/abs/10.1890/14-2252.1}, eprint = {https://esajournals.onlinelibrary.wiley.com/doi/pdf/10.1890/14-2252.1} } </bibtex> </referencePublication> ... </dataset> 5.5 The eml-software module - Software specific information The eml-software module contains general information that describes software resources. This module is intended to fully document software that is needed in order to view a resource (such as a dataset) or to process a dataset. The software module is also imported into the eml-methods module in order to document what software was used to process or perform quality control procedures on a dataset. The eml-software module, like other modules, may be "referenced" via the <references> tag. This allows a software resource to be described once, and then used as a reference in other locations within the EML document via its ID. 5.6 The eml-protocol module - Research protocol specific information The EML Protocol Module is used to define abstract, prescriptive procedures for generating or processing data. Conceptually, a protocol is a standardized method. Eml-protocol resembles eml-methods; however, eml-methods is descriptive (often written in the declarative mood: "I took five subsamples...") whereas eml-protocol is prescriptive (often written in the imperative mood: "Take five subsamples..."). A protocol may have versions, whereas methods (as used in eml-methods) should not. "],
["data-structure-modules.html", "6 Data Structure Modules 6.1 The eml-entity module - Entity level information within datasets 6.2 The eml-attribute module - Attribute level information within dataset entities 6.3 The eml-constraint module - Relationships among and within dataset entities 6.4 The eml-dataTable module - Logical information about data table entities 6.5 The eml-spatialRaster module - Logical information about regularly gridded geospatial image data 6.6 The eml-spatialVector module - Logical information about non-gridded geospatial image data 6.7 Schema for validating spatial referencing descriptions 6.8 The eml-storedProcedure module - Data tables resulting from procedures stored in a database 6.9 The eml-view module - Data tables resulting from a database query", " 6 Data Structure Modules The following three modules are used to document the logical layout of a dataset. Many datasets are comprised of multiple entities (e.g. a series of tabular data files, or a set of GIS features, or a number of tables in a relational database). Each entity within a dataset may contain one or more attributes (e.g. multiple columns in a data file, multiple attributes of a GIS feature, or multiple columns of a database table). Lastly, there may be both simple or complex relationships among the entities within a dataset. The relationships, or the constraints that are to be enforced in the dataset, are described using the eml-constraint module. All entities share a common set of information (described using eml-entity), but some discipline specific entities have characteristics that are unique to that entity type. Therefore, the eml-entity module is extended for each of these types (dataTable, spatialRaster, spatialVector, etc...) which are described in the next section. 6.1 The eml-entity module - Entity level information within datasets The eml-entity module defines the logical characteristics of each entity in the dataset. Entities are usually tables of data (eml-dataTable). Data tables may be ascii text files, relational database tables, spreadsheets or other type of tabular data with a fixed logical structure. Related to data tables are views (eml-view) and stored procedures (eml-storedProcedure). Views and stored procedures are produced by an RDBMS or related system. Other types of data such as: raster (eml-spatialRaster), vector (eml-spatialVector) or spatialReference image data are also data entities. An otherEntity element would be used to describe types of entities that are not described by any other entity type. Each of these entity type uses the eml-entity module elements as it’s base set of elements, but then extends the base with entity-specific elements. Note that the eml-spatialReference module is not an entity type, but is rather a common set of elements used to describe spatial reference systems in both eml-spatialRaster and eml-spatialVector. It is described here in relation to those two modules. The eml-entity module, like other modules, may be “referenced” via the <references> tag. This allows an entity document to be described once, and then used as a reference in other locations within the EML document via its ID. 6.2 The eml-attribute module - Attribute level information within dataset entities The eml-attribute module describes all attributes (variables) in a data entity: dataTable, spatialRaster, spatialVector, storedProcedure, view or otherEntity. The description includes the name and definition of each attribute, its domain, definitions of coded values, and other pertinent information. Two structures exist in this module: 1. attribute is used to define a single attribute; 2. attributeList is used to define a list of attributes that go together in some logical way. The eml-attribute module, like other modules, may be "referenced" via the <references> tag. This allows an attribute document to be described once, and then used as a reference in other locations within the EML document via its ID. 6.2.1 Philosophy of Attribute Units The concept of "unit" represents one of the most fundamental categories of metadata. The classic example of data entropy is the case in which a reported numeric value loses meaning due to lack of associated units. Much of Ecology is driven by measurement, and most measurements are inherently comparative. Good data description requires a representation of the basis for comparison, i.e., the unit. In modeling the attribute element, the authors of EML drew inspiration from the NIST Reference on Constants, Units, and Uncertainty. This document defines a unit as "a particular physical quantity, defined and adopted by convention, with which other particular quantities of the same kind are compared to express their value." The authors of the EML 2.0 specification (hereafter "the authors") decided to make the unit element required, wherever possible. Units may also be one of the most problematic categories of metadata. For instance, there are many candidate attributes that clearly have no units, such as named places and letter grades. There are other candidate attributes for which units are difficult to identify, despite some suspicion that they should exist (e.g. pH, dates, times). In still other cases, units may be meaningful, but apparently absent due to dimensional analysis (e.g. grams of carbon per gram of soil). The relationship between units and dimensions likewise is not completely clear. The authors decided to sharpen the model of attribute by nesting unit under measurementScale. Measurement Scale is a data typology, borrowed from Statistics, that was introduced in the 1940's. Under the adopted model, attributes are classified as nominal, ordinal, interval, and ratio. Though widely criticized, this classification is well-known and provides at least first-order utility in EML. For example, nesting unit under measurementScale allows EML to prevent its meaningless inclusion for categorical data -- an approach judged superior to making unit universally required or universally optional. The sharpening of the attribute model allowed the elimination of the unit type "undefined" from the standard unit dictionary (see eml-unitDictionary.xml). It seemed self-defeating to require the unit element exactly where appropriate, yet still allow its content to be undefined. An attribute that requires a unit definition is malformed until one is provided. The unit type "dimensionless" is preserved, however. In EML 2.0, it is synonymous with "unitless" and represents the case in which units cannot be associated with an attribute for some reason, despite the proper classification of that attribute as interval or ratio. Dimensionless may itself be an anomaly arising from the limitations of the adopted measurement scale typology. Closely related to the concept of unit is the concept of attribute domain. The authors decided that a well-formed description of an attribute must include some indication of the set of possible values for that attribute. The set of possible values is useful, perhaps necessary, for interpreting any particular observed value. While universally required, attribute domain has different forms, depending on the associated measurement scale. The element storageType has an obvious relationship to domain. It gives some indication of the range of possible values of an attribute, and also gives some (potentially critical) operability information about the way the attribute is represented or construed in the local storage system. The storageType element seems to fall in a gray area between the logical and physical aspects of stored data. Neither comfortable with eliminating it nor with making it required, the authors left it available but optional under attribute. In addition, it is repeatable so that different storage types can be provided for various systems (e.g., different databases might use different types for columns, even though the domain of the attribute is the same regardless of which database is used). Attributes representing dates, times, or combinations thereof (hereafter "dateTime") were the most difficult to model in EML. Is dateTime of type interval or ordinal? Does it have units or not? Strong cases can be made on each side of the issue. The confusion may reflect the limitations of the measurement scale typology. The final resolution of the dateTime model is probably somewhat arbitrary. There was clearly a need, however, to allow for the interoperability of dateTime formats. EML 2.0 tries to provide an unambiguous mechanism for describing the format of dateTime values by providing a separate category for date and time values. This "dateTime" measurement scale allows users to explicitly label attributes that contain Gregorian date and time values, and allows them to provide the information needed to parse these values into their appropriate components (e.g., days, months, years)./ 6.3 The eml-constraint module - Relationships among and within dataset entities The eml-constraint schema defines the integrity constraints between entities (e.g., data tables) as they would be maintained in a relational management system. These constraints include primary key constraints, foreign key constraints, unique key constraints, check constraints, and not null constraints, among potential others. 6.4 The eml-dataTable module - Logical information about data table entities The eml-dataTable module is used to describe the logical characteristics of each tabular set of information in a dataset. A series of comma-separated text files may be considered a dataset, and each file would subsequently be considered a dataTable entity within the dataset. Since the eml-dataTable module extends the eml-entity module, it uses all of the common entity elements to describe the table, along with a few elements specific to just data table entities. The eml-dataTable module allows for the description of each attribute (column/field/variable) within the data table through the use of the eml-attribute module. Likewise, there are fields used to describe the physical distribution of the data table, its overall coverage, the methodology used in creating the data, and other logical structure information such as its orientation, case sensitivity, etc. 6.5 The eml-spatialRaster module - Logical information about regularly gridded geospatial image data The eml-spatialRaster module allows for the description of entities composed of rectangular grids of data values that are usually georeferenced to a portion of the earth's surface. Specific attributes of a spatial raster can be documented here including the spatial organization of the raster cells, the cell data values, and if derived via imaging sensors, characteristics about the image and its individual bands. 6.6 The eml-spatialVector module - Logical information about non-gridded geospatial image data The eml-spatialVector module allows for the description of spatial objects in a GIS system that are not defined in a regularly gridded pattern. These geometries include points and vectors and the relationships among them. Specific attributes of a spatial vector can be documented here including the vector's geometry type, count and topology level. 6.7 Schema for validating spatial referencing descriptions This module defines both projected and unprojected coordinate systems for referencing the spatial coordinates of a dataset to the earth. The schema is based on that used by Environmental Systems Research Inc (ESRI) for its .prj file format. EML provides a library of pre-defined coordinate systems that may be referred to by name in the horizCoordSysName element. A custom projection may be defined using this schema for any projection that does not appear in this dictionary. 6.8 The eml-storedProcedure module - Data tables resulting from procedures stored in a database The storedProcedure module is meant to capture information on procedures that produce data output in the form of a data table. In an RDBMS one can code complex queries and transactions into stored procedures and then invoke them directly from front-end applications. It allows the optional description of any parameters that are expected to be passed to the procedure when it is called. 6.9 The eml-view module - Data tables resulting from a database query The eml-view module describes a view from a database management system. A view is a query statement that is stored as a database object and executed each time the view is called. "],
["discovery-and-interpretation-modules.html", "7 Discovery and Interpretation Modules 7.1 The eml-access module - Access control rules for resources 7.2 The eml-physical module - Physical file format 7.3 The eml-party module - People and organization information 7.4 The eml-coverage module - Geographic, temporal, and taxonomic extents of resources 7.5 The eml-project module - Research context information for resources 7.6 The eml-methods module - Methodological information for resources", " 7 Discovery and Interpretation Modules The following six modules are used to qualify the resources being described in more detail. They are used to describe access control rules, distribution of the metadata and data themselves, parties associated with the resource, the geographic, temporal, and taxonomic extents of the resource, the overall research context of the resource, and detailed methodology used for creating the resource. Some of these modules are imported directly into the top-level resource modules, often in many locations in order to limit the scope of the description. For instance, the eml-coverage module may be used for a particular column of a dataset, rather than the entire dataset as a whole. 7.1 The eml-access module - Access control rules for resources The eml-access module describes the level of access that is to be allowed or denied to a resource for a particular user or group of users, and can be described independently for metadata and data. The eml-access module uses a reference to a particular authentication system to determine the set of principals (users or groups) that can be specified in the access rules. The special principal 'public' can be used to indicate that any user or group has access permission, thereby making it easier to specify that anonymous access is allowed. There are two mechanisms for including access control via the eml-access module: The top-level "eml" element may have an optional <access> element that is used to establish the default access control for the entire EML package. If this access element is omitted from the document, then the package submitter should be given full access to the package but all other users should be denied all access. To allow the package to be publicly viewable, the EML author must explicitly include a rule stating so. Barring the existence of a distribution-level <access> element (see below), access to data entities will be controlled by the package-level <access> element in the <eml> element. Exceptions for particular entity-level components of the package can be controlled at a finer grain by using an access description in that entity's physical/distribution tree. When access control rules are specified at this level, they apply only to the data in the parent distribution element, and not to the metadata. Thus, it will control access to the content of the <inline> element, as well as resources that are referenced by the <online/url> and <online/connection> paths. These exceptions to access for particular data resources are applied after the default access rules at the package-level have been applied, so they effectively override the default rules when they overlap. In previous versions of EML access rules for entity-level distribution were contained in <additionalMetadata> sections and referenced via the <describes> tag. Although in theory these could have referenced any node, in application such node-level access control is problematic. Since the most common uses of access control rules were to limit access to specific data entities, the access tree has been placed there explicitly in EML 2.1.0. Access is specified with a choice of child elements, either <allow> or <deny>. Within these rules, values can be assigned for each <principal> using the <permission> element. Users given "read" permission can view the resource; "write" allows changes to the resource excluding changes to the access rules; "changePermission" includes "write" plus the changing of access rules. Users allowed "all" permissions; may do all of the above. Access to data and metadata is affected by the order attribute of the <access> element. It is possible for a deny rule to override an allow rule, and vice versa. In the case where the order attribute is set to "allowFirst", and there are rules similar to the following (with non-critical sections deleted): <deny> <principal>public</principal> <permission>read</permission> </deny> <allow> <principal>uid=alice,o=NASA,dc=ecoinformatics,dc=org</principal> <permission>read</permission> </allow> the principal "uid=alice ..." will be denied access, because it is a member of the special "public" principal, and the deny rule is processed second. For this allow rule to truly allow access to that principal, the order attribute should be set to "denyFirst", and the allow rule will override the deny rule when it is processed second. An example is given below, with non-critical sections deleted: <eml> <access authSystem="ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org" order="allowFirst"> <allow> <principal>uid=alice,o=NASA,dc=ecoinformatics,dc=org</principal> <permission>read</permission> <permission>write</permission> <allow> </access> <dataset> ... ... <dataTable id="entity123"> ... <physical> ... <distribution> ... <access id="access123" authSystem="ldap://ldap.ecoinformatics.org:389/dc=ecoinformatics,dc=org" order="allowFirst"> <deny> <principal>uid=alice,o=NASA,dc=ecoinformatics,dc=org</principal> <permission>write</permission> </deny> </access> </distribution> </physical> </dataTable> <dataTable id="entity234"> ... <physical> ... <distribution> ... <access> <references>access123</references> </access> </distribution> </physical> </dataTable> ... </dataset> <eml> In this example, the overall default access is to allow the user=alice (but no one else) to read and write all metadata and data. However, under "entity123" and "entity234", there is an additional rule saying that user=alice does not have write permission. The net effect is that Alice can read and make changes to the metadata, but cannot make changes to the two data entities. In addition, Alice cannot change these access rules; although the submitter can. This example also shows how the eml-access module, like other modules, may be "referenced" via the <references> tag. This allows an access control document to be described once, and then used as a reference in other locations within the EML document via its ID. In summary, access rules can be applied in two places in an eml document. Default access rules are established in the top <access> element for the main eml document (e.g., "/eml/access"). These default rules can be overridden for particular data entities by adding additional <access> elements in the physical/distribution trees of those entities. 7.2 The eml-physical module - Physical file format The eml-physical module describes the external and internal physical characteristics of a data object as well as the information required for its distribution. Examples of the external physical characteristics of a data object would be the filename, size, compression, encoding methods, and authentication of a file or byte stream. Internal physical characteristics describe the format of the data object being described. Both named binary or otherwise proprietary formats can be cited (e.g., Microsoft Access 2000), or text formats can be precisely described (e.g., ASCII text delimited with commas). For these text formats, it also includes the information needed to parse the data object to extract the entity and its attributes from the data object. Distribution information describes how to retrieve the data object. The retrieval information can be either online (e.g., a URL or other connection information) or offline (e.g., a data object residing on an archival tape). The eml-physical module, like other modules, may be "referenced" via the <references> tag. This allows a physical document to be described once, and then used as a reference in other locations within the EML document via its ID. 7.3 The eml-party module - People and organization information The eml-party module describes a responsible party and is typically used to name the creator of a resource or metadata document. A responsible party may be an individual person, an organization or a named position within an organization. The eml-party module contains detailed contact information. It is used throughout the other EML modules where detailed contact information is needed. The eml-party module, like other modules, may be "referenced" via the <references> tag. This allows a party to be described once, and then used as a reference in other locations within the EML document via its ID. 7.4 The eml-coverage module - Geographic, temporal, and taxonomic extents of resources The eml-coverage module contains fields for describing the coverage of a resource in terms of time, space, and taxonomy. These coverages (temporal, spatial, and taxonomic) represent the extent of applicability of the resource in those domains. The Geographic coverage section allows for 2 means of expressing coverage on the surface of the earth: 1) via a set of bounding coordinates that define the North, South, East and West points in a rectangular area, optionally including a bounding altitude, and 2) using a G-Ring polygon definition, where an irregularly shaped area may be defined using a ordered list of latitude/longitude coordinates. A G-Ring may also include an "inner G-Ring" that defines one or more "cut-outs" in the area, i.e. the donut hole concept. The temporal coverage section allows for the definition of either a single date or time, or a range of dates or times. These may be expressed as a calendar date according to the ISO 8601 Date and Time Specification, or by using an alternate time scale, such as the geologic time scale. Currently, EML does not have specific fields to indicate that a data resource may be "ongoing." Two examples are data tables that are planned to be appended in the future, or resources with complex connection definitions (such as to a database) which may return data in real time. It is important that EML be able to handle data from both the "producer" and "consumer" points of view, although currently the temporal coverage modules are designed for the latter. There is no universally acceptable recommendation for describing "ongoing" data within EML. Some groups have chosen to use the <alternateTimeScale> node for the end date, with a value of "ongoing," although this practice is not endorsed by the EML authors. A better solution could be to use very general content for the endDate (such as only the current year) so that the data are accurately described, and searches return datasets as expected. A future version of EML will accommodate such data types with coverage elements specific to their needs. The taxonomic coverage section allows for detailed description of the taxonomic extent of the dataset or resource. The taxonomic classification consists of a recursive set of taxon rank names, their values, and their common names. This construct allows for a taxonomic hierarchy to be built to show the level of identification (e.g. Rank Name = Kingdom, Rank Value = Animalia, Common Name = Animals, and so on down the hierarchy.) The taxonomic coverage module also allows for the definition of the classification system in cases where alternative systems are used. The eml-coverage module, like other modules, may be "referenced" via the <references> tag. This allows the coverage extent to be described once, and then used as a reference in other locations within the EML document via its ID. 7.5 The eml-project module - Research context information for resources The eml-project module describes the research context in which the dataset was created, including descriptions of over-all motivations and goals, funding, personnel, description of the study area etc. This is also the module to describe the design of the project: the scientific questions being asked, the architecture of the design, etc. This module is used to place the dataset that is being documented into its larger research context. The eml-project module, like other modules, may be "referenced" via the <references> tag. This allows a research project to be described once, and then used as a reference in other locations within the EML document via its ID. 7.6 The eml-methods module - Methodological information for resources The eml-methods module describes the methods followed in the creation of the dataset, including description of field, laboratory and processing steps, sampling methods and units, quality control procedures. The eml-methods module is used to describe the actual procedures that are used in the creation or the subsequent processing of a dataset. Likewise, eml-methods is used to describe processes that have been used to define / improve the quality of a data file, or to identify potential problems with the data file. Note that the eml-protocol module is intended to be used to document a prescribed procedure, whereas the eml-method module is used to describe procedures that were actually performed. The distinction is that the use of the term "protocol" is used in the "prescriptive" sense, and the term "method" is used in the "descriptive" sense. This distinction allows managers to build a protocol library of well-known, established protocols (procedures), but also document what procedure was truly performed in relation to the established protocol. The method may have diverged from the protocol purposefully, or perhaps incidentally, but the procedural lineage is still preserved and understandable. "],
["utility-modules.html", "8 Utility Modules 8.1 The eml-text module - Text field formatting 8.2 The eml-semantics module - Semantic annotations for formalized statements about EML components", " 8 Utility Modules The following modules are used to highlight the information being documented in each of the above modules where prose may be needed to convey the critical metadata. The eml-text module provides a number of text-based constructs to enhance a document (including sections, paragraphs, lists, subscript, superscript, emphasis, etc.) 8.1 The eml-text module - Text field formatting The eml-text module is a wrapper container that allows general text descriptions to be used within the various modules of eml. It can include either structured or unstructured text blocks. It isn't really appropriate to use this module outside of the context of a parent module, because the parent module determines the appropriate context to which this text description applies. The eml-text module allows one to provide structure to a text description in order to convey concepts such as sections (paragraphs), hierarchy (ordered and unordered lists), emphasis (bold, superscript, subscript) etc. The structured elements can be specified using a subset of DocBook so the predefined DocBook stylesheets can be used to style EML fields that implement this module, or alternatively can be specified using Markdown text blocks. Combinations of plain text, docbook sections, and markdown sections can be interleaved in any order, but most people will likely find the markdown syntax the easiest to use. 8.2 The eml-semantics module - Semantic annotations for formalized statements about EML components The eml-semantics module defines types and elements for annotating other structures within EML with semantically-precise statements from various controlled vocabularies. This is accomplished by associating the global URI for a property and value with elements from EML, such as an attribute, an entity, or a dataset. It is used throughout the other EML modules where detailed semantic information is needed. For example, given an EML attribute named “tmpair”, one might want to indicate semantically that the attribute is measuring the property “Temperature” from a sample of the entity “Air”, where both of those terms are defined precisely in controlled vocabularies. The eml-semantics module defines an ‘annotation’ element and associated type that can be used within EML resources (dataset, software, etc.), EML Entities (dataTable, spatialRaster, spatialVector, otherEntity), and EML Attributes. They can also be applied within the EML additionalMetadata field to label arbitrary structures within EML, in which case the subject of the annotation is the element listed in the describes element within the additionalMetadata field. "],
["eml-schema.html", "9 EML Schema", " 9 EML Schema EML is defined by a set of XML Schema files that define the types and structure of a valid EML document. In this chapter, all of the elements and types defined within those EML schemas are displayed using diagrams illustrating the relationships among these components. "],
["validation-and-content-references.html", "10 Validation and Content references 10.1 Validation rules 10.2 Validation algorithm 10.3 Content references 10.4 EML Validity Parser 10.5 id and Scope Examples", " 10 Validation and Content references This section explains the validation rules of EML. While most of the validation rules are expressed as constraints within the XML Schema definition files, there are some rules that cannot be written directly into the XML Schemas nor enforced by an XML parser. These additional validation rules MUST be enforced by every EML package in order for it to be considered EML-compliant. 10.1 Validation rules For a document to be EML-valid, all of the following constraints must hold true: The document MUST validate using a compliant XML Schema validating parser All EML documents MUST have the ‘eml’ module as the root A packageId attribute MUST be present on the root eml element All id attributes within the document MUST be unique Elements which contain an annotation child element MUST contain an id attribute, unless the containing annotation element contains a references attribute If an element references another using a child references element, another element with that value in its id attribute MUST exist in the document When references is used, the system attribute MUST have the same value in both the target and source elements, or it must be absent in both. Frequently it is absent in both. If an element references another using a child references element, it MUST not have an id attribute itself If an additionalMetadata element references another using a child describes element, another element with that value in its id attribute MUST exist in the document 10.2 Validation algorithm One reasonable algorithm for assessing these constraints without loading the XML into a DOM structure could be implemented by checking id and references fields while parsing the document and storing their values in identifierHash and referencesHash data structures in order to do the final consistency check. For example, in pseudocode: Parse the XML document using an XML Schema-compliant parser If the root element is not eml, then the document is invalid For each element, record whether it has an id attribute or not If an element does not contain an id, but it has a child annotation element, and that child annotation does not contain a references attribute, then the document is invalid For each id attribute If id is not in identifiersHash then add it as the key of identifiersHash, with its system as the value If id is already in identifiersHash then the document is invalid If the element containing the id contains a references element as an immediate child then the document is invalid For each references element If the references key is not in referencesHash, then add it as a key with the system value to referencesHash If the references key is in referencesHash, but the current system value does not match the value for that key, then the document is invalid For each references attribute on an annotation element If the references key is not in referencesHash, then add it as a key with the empty string ’’ value to referencesHash For each describes element within an additionalMetadata element If the describes key is not in referencesHash, then add it as a key with the empty string ’’ value to referencesHash Once document processing is complete, for each key in referencesHash If !identifierHash.hasKey(key) OR 'referencesHash[key] != identifierHash[key]' then the document is invalid If no validity errors are found above or by the parser, then the document is valid 10.3 Content references Each EML module, with the exception of “eml” itself, has a top level choice between the structured content of that element or a “references” field. This enables the reuse of content previously defined elsewhere in the document. This allows, for example, an author to create a single <creator id='m.jones'> element with all of its child detail, and then reference that as <contact><references>m.jones</references></contact> to indicate that the same person is both the creator and contact. This creates an unambiguous linkage via the id field that the two elements refer to the same entity, in this case a person, and avoids having to re-enter the same information multiple times in the document. Another common location for re-use is when a single attributeList is defined with a set of variables and their metadata, and then that list is referenced in multiple dataTable elements to show that they are structured identically. The reuse of structured content is accomplished through the use of id/references pairs. Each element that is to be reused will contain a unique id attribute on the element. Because this identifier is guaranteed to be unique within the EML document, any other location that wants to point at that content can do so using the references element, as shown in the example above. These types of references can also be used in the references attribute of annotation elements, and in the describes element within the additionalMetadata element. If an id attribute is provided for content, then that content is considered to represent a different entity than all other elements that are defined in the document, except for those that include its id in the references child. This is useful to indicate, for example, that two people with similar names (e.g., “D. Clark” and “D. Clark”) are in fact distinct individuals (e.g., “Deborah Clark” and “David Clark”), or that two variables with the same attributeName are in fact different variables. While it would be bad practice to reuse attribute names like this, it does happen and EML needs to be able to document it when it does. 10.4 EML Validity Parser Because some of these rules cannot be enforced in XML-Schema, we have written a parser which checks the validity of the references and ids used in a document. This parser is included with the release of EML. To run the parser, you must have Java installed. To execute it change into the lib directory of the release and run the ‘runEMLParser’ script passing your EML instance file as a parameter. There may also be an online version of this parser, which is publicly accessible. The online parser will both validate your XML document against the schema as well as check the integrity of your references. 10.5 id and Scope Examples Example: Invalid EML due to duplicate identifiers <?xml version="1.0"?> <eml:eml packageId="eml.1.1" system="knb" xmlns:eml="https://eml.ecoinformatics.org/eml-2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://eml.ecoinformatics.org/eml-2.2.0 eml.xsd"> <dataset id="ds.1"> <title>Sample Dataset Description</title> <!-- the two creators have the same id. this should be an error--> <creator id="23445" scope="document"> <individualName> <surName>Smith</surName> </individualName> </creator> <creator id="23445" scope="document"> <individualName> <surName>Smith</surName> </individualName> </creator> ... </dataset> </eml:eml> This instance document is invalid because both creator elements have the same id. No two elements can have the same string as an id. Example: Invalid EML due to a non-existent reference <?xml version="1.0"?> <eml:eml packageId="eml.1.1" system="knb" xmlns:eml="https://eml.ecoinformatics.org/eml-2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://eml.ecoinformatics.org/eml-2.2.0 eml.xsd"> <dataset id="ds.1"> <title>Sample Dataset Description</title> <creator id="23445" scope="document"> <individualName> <surName>Smith</surName> </individualName> </creator> <creator id="23446" scope="document"> <individualName> <surName>Myer</surName> </individualName> </creator> ... <contact> <references>23447</references> </contact> </dataset> </eml:eml> This instance document is invalid because the contact element references an id that does not exist. Any referenced id must exist in the document. Example: Invalid EML due to a conflicting id attribute and a <references> element <?xml version="1.0"?> <eml:eml packageId="eml.1.1" system="knb" xmlns:eml="https://eml.ecoinformatics.org/eml-2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://eml.ecoinformatics.org/eml-2.2.0 eml.xsd"> <dataset id="ds.1"> <title>Sample Dataset Description</title> <creator id="23445" scope="document"> <individualName> <surName>Smith</surName> </individualName> </creator> <creator id="23446" scope="document"> <individualName> <surName>Meyer</surName> </individualName> </creator> ... <contact id="522"> <references>23445</references> </contact> </dataset> </eml:eml> This instance document is invalid because the contact element both references another element and has an id itself. If an element references another element, it may not have an id. This prevents circular references. Example: A valid EML document <?xml version="1.0"?> <eml:eml packageId="eml.1.1" system="knb" xmlns:eml="https://eml.ecoinformatics.org/eml-2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://eml.ecoinformatics.org/eml-2.2.0 eml.xsd"> <dataset id="ds.1"> <title>Sample Dataset Description</title> <creator id="23445" scope="document"> <individualName> <surName>Smith</surName> </individualName> </creator> <creator id="23446" scope="document"> <individualName> <surName>Smith</surName> </individualName> </creator> ... <contact> <references>23446</references> </contact> <contact> <references>23445</references> </contact> </dataset> </eml:eml> This instance document is valid. Each contact is referencing one of the creators above and all the ids are unique. The each creator has a its own id indicates that they are different people, even though they have the same surName and there is no other distinguishing metadata. "],
["semantic-annotation-primer.html", "11 Semantic Annotation Primer 11.1 Introduction 11.2 Semantic Annotations in EML 2.2.0 11.3 Appendix 11.4 Frequently asked questions", " 11 Semantic Annotation Primer 11.1 Introduction A semantic annotation creates a relationship between some semantic metadata and a resource - in this case, a dataset, or some other element of a dataset (e.g., an attribute). What makes the annotation “semantic” is that the resource is linked to a well-defined term in a web-accessible ontology. In this way, semantic annotation provides access to precise definitions of concepts, and clarifies the relationships among concepts in a machine-readable way. Creating semantic annotations does require additional effort but pays off by enhancing discovery and reuse of your data. The main differences between semantic annotation and simply adding keywords are: - semantic annotations can be read and interpreted by computers - semantic annotations describe the relationship between a specific part of the metadata and terms in external vocabularies - semantic annotations use W3C-recommended languages to express these relationships via the Web For the purposes of this document all mentions of “annotation” imply “semantic annotation” as described above. Whereas more generic methods for annotating data and metadata exist (e.g., using keywords), these are not nearly as powerful as “semantic annotation”. Benefits of annotation: Annotations enhance data discovery and interpretation thereby making it easier for others to find and reuse data (and thus give proper credit). For example, consider the following cases: Finding synonymous concepts: Assume one dataset uses the phrase “carbon dioxide flux” and another dataset “CO2 flux”. An information system can recognize, through semantic annotation, that these datasets are about the same concepts if the datasets were annotated using the same term identifier for that measurement. Disambiguating terms: If datasets have been annotated, the system can assist in providing only results relevant for your intended meaning. For example, if you are searching for datasets about “litter” (as in “plant litter”), other irrelevant terms also labelled as “litter” (e.g., “garbage” or a “group of animals born together”) can be eliminated from your search results. This is because each distinct type of “litter” would be associated with a different identifier. Hierarchical searches: If you search for datasets containing “carbon flux” measurements, then datasets annotated as having measurements of “carbon dioxide flux” or “CO2 flux” will also be returned because these are both types of “carbon flux”. This is possible if the concepts come from a structured vocabulary where “carbon dioxide flux” is lower in the hierarchy (i.e., is a subclass) of “carbon flux”. There are five locations within the EML 2.2.0 schema to embed references to terms in external vocabularies (also known as ontologies) using HTTP uniform resource identifiers or URIs. The association of an element in an EML metadata document with that external reference is a semantic annotation. By referencing terms from an external vocabulary, one can provide a rigorous, expressive, and consistent interpretation of the metadata. This is only true, however, if the external vocabulary itself is well-constructed, and expressed in a W3C semantic web language. Since the external reference (or annotation) is to a controlled vocabulary or ontology, the annotation provides a computer-usable pointer (the HTTP URI) that resolves (and dereferences) to a useful description, definition, or specification of other relationships for that annotated resource. Related FAQ: How do computers use EML annotations? 11.1.1 Take-home messages Semantic statements must be logically consistent, as they are not simply a set of loosely structured keywords. EML 2.2.0 has five places or methods that accept annotations (described in greater detail below). The best place for advice and feedback on EML annotations is your data management community 11.1.2 Organization of this document The purpose of this primer is to provide an introduction to how semantic annotations are structured in EML documents. It is expected that the readers is already familiar with the EML schema. This primer is divided into three major sections, including this Introduction), the central text (Semantic Annotations in EML 2.2.0), and an Appendix. While the central text of the primer (Semantic Annotations in EML 2.2.0) should provide all the information needed to create annotations in EML, additional details and more in-depth explanations are provided in the Appendix. Introduction Semantic Annotations in EML 2.2.0, with examples. Where used, EML elements are shown as inline code blocks (e.g., elementName). Appendix: Additional information on specific related topics, linked from other sections. Glossary: Glossary of terms, linked from text Semantic triples: Details on their structure (and machine use). Explanation of how that structure is leveraged by annotations with examples of their power URIs: Defined, and as components of semantic triples RDF model and graphs: Brief description of the W3C’s RDF model with example graphs based on EML annotations Logical consistency: Common mistakes and how to check for them Vocabularies and repositories used in examples: Descriptions and links out to explore further Additional background information: The EML annotation approach here is compatible with recommendations by the World Wide Web Consortium (W3C) for construction of the Semantic Web. A wealth of material is available; a few selected ones are suggested here. Frequently asked questions: Some questions asked by readers, and their answers 11.1.3 Other Conventions and Terminology Use of the terms “required” or “must”: this feature is a requirement of EML 2.2 Use of the term “should”: this feature is not required by EML 2.2 schema but is a recommended or emerging best practice. It is not checked by the EML schema or parser, but could be checked or confirmed by an external system. 11.2 Semantic Annotations in EML 2.2.0 There are five locations within the EML 2.2.0 schema where annotations can be included: top-level resource: an annotation element is a child of the dataset, literature, software, or protocol elements entity-level: an annotation element is a child of a dataset’s entity (e.g., dataTable) attribute: an annotation element is a child of a dataset entity’s attribute element eml/annotations: a container for a group of annotation elements using references eml/additionalMetadata: annotation elements that reference a main-body element by its id attribute 11.2.1 Annotation element structure All annotation nodes are defined as an XML type so they have the same structure anywhere they appear in the EML record. The basic structure is listed below (additional examples are provided in the following sections). <annotation> <propertyURI label="property label here">property URI here</propertyURI> <valueURI label="value label here">value URI here</valueURI> </annotation> An annotation element always has a parent-EML element, which is the ‘thing’ being annotated, or the subject (e.g., the dataset, attribute). The annotation element has two required child elements: propertyURI and valueURI. Together, these two child elements, along with the subject, form a “semantic statement” that can become a “semantic triple”. The concept of a triple is covered in more detail (see Semantic Triples, below). Here, we concentrate on the structure of an annotation within the EML document itself: propertyURI and valueURI elements each element’s text is the URI for the concept in an external vocabulary. The URI points to a term in a vocabulary where a definition, description, and that term’s relationships to other concepts are formally modelled. Content is required by the EML schema, and it should be a URI. the XML attribute label is required (for both propertyURI and valueURI) it should be suitable for application interfaces to display to humans it should be populated with values from the referenced vocabulary’s label field (e,g., rdfs:label or skos:prefLabel). Note that this assumes the referenced vocabulary is stored as an RDF document, which is current best practice for sharing scientific vocabularies over the Web. A note about annotations and element IDs All annotations must have an unambiguous subject. At the dataset-, entity-, or attribute- level, the parent element is the subject (e.g., <dataset>, <dataTable>, <attribute>), and precision of nodes in EML is guaranteed by the element’s id. That is, if an element has an annotation child, it must also have an id so it can become the annotation subject. Annotations at eml/annotations or eml/additionalMetadata will have subjects defined with a references attribute or describes element. As with other internal EML references, an id is required. With EML 2.2.0, the parser will check that an id attribute is present on elements with annotation children. As a reminder, the id must be unique within an EML document. Ideally, that id either is, or can readily be translated into, an HTTP URI that can be dereferenced (see examples below). 11.2.2 Top-level resource, entity-level, and attribute annotations Annotations for top-level resources, entities, and attributes follow the same general pattern: the subject of the semantic statement is the parent element of the annotation; it must have an id attribute. 11.2.2.1 Example 1: Top-level resource annotation (dataset) In the following dataset annotation, the semantic statement can be read as “the dataset with the id ‘dataset-01’ is about grassland biome(s)”. the subject of the semantic statement is the dataset element containing the id attribute value "dataset-01" the annotation itself has 2 parts: propertyURI is ‘http://purl.obolibrary.org/obo/IAO_0000136’, and describes the nature of the relationship between the subject (above) and object (valueURI below), using a term from the Information Artifact Ontology (IAO). valueURI is ‘http://purl.obolibrary.org/obo/ENVO_01000177’, which resolves to the “grassland biome” term in the Environment Ontology (EnvO). <dataset id="dataset-01"> <title>Soil organic matter responses to nutrient enrichment in the Nutrient Network:Nutrient Network. A cross-site investigation of bottom-up control over herbaceous plant community dynamics and ecosystem function.</title> <creator id="eric.seabloom"> <individualName> <givenName>Eric</givenName> <surName>Seabloom</surName> </individualName> </creator> ... <coverage> ... </coverage> <annotation> <propertyURI label="is about">http://purl.obolibrary.org/obo/IAO_0000136</propertyURI> <valueURI label="grassland biome">http://purl.obolibrary.org/obo/ENVO_01000177</valueURI> </annotation> ... </dataset> 11.2.2.2 Example 2: Entity-level annotation In the following entity-level annotation, the semantic statement can be read as “the entity with the id ‘urn:uuid:9f0eb128-aca8-4053-9dda-8e7b2c43a81b’ is about Mammalia”. The subject of the semantic statement is the otherEntity with id attribute value, "urn:uuid:9f0eb128-aca8-4053-9dda-8e7b2c43a81b". The annotation itself has 2 parts propertyURI is “http://purl.obolibrary.org/obo/IAO_0000136”, which resolves to “is about”, from IAO valueURI is “http://purl.obolibrary.org/obo/NCBITaxon_40674”, which resolves to “Mammalia” in the NCBI Taxon ontology. <otherEntity id="urn:uuid:9f0eb128-aca8-4053-9dda-8e7b2c43a81b" scope="document"> <entityName>DBO_MMWatch_SWL2016_MooreGrebmeierVagle.xlsx</entityName> <entityDescription>Data contained in the file DBO_MMWatch_SWL2016_MooreGrebmeierVagle.xlsx are marine mammal observations and observation conditions from CCGS Sir Wilfrid Laurier July 10-20, 2016. Data observations and locations are part of the Distributed Biological Observatory (DBO).</entityDescription> <physical scope="document"> <objectName>DBO_MMWatch_SWL2016_MooreGrebmeierVagle.xlsx</objectName> <size unit="bytes">24635</size> </physical> <entityType>Other</entityType> <annotation> <propertyURI label="is about">http://purl.obolibrary.org/obo/IAO_0000136</propertyURI> <valueURI label="Mammalia">http://purl.obolibrary.org/obo/NCBITaxon_40674</valueURI> <annotation> </otherEntity> 11.2.2.3 Example 3: Attribute annotation In the following attribute annotation, the semantic statement can be read as “the attribute with the id ‘att.4’ contains measurements of type plant cover percentage” The subject of the semantic statement is the attribute element with the id value “att.4”. The annotation itself has 2 parts propertyURI is “http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#containsMeasurementsOfType”, from the Extensible Ontology for Observations (OBOE) valueURI is “http://purl.dataone.org/odo/ECSO_00001197”, which resolves to “Plant Cover Percentage” in the Ecosystem Ontology (ECSO) Related FAQ: Are all EML dataTable attributes measurements? <attribute id="att.4"> <attributeName>pctcov</attributeName> <attributeLabel>percent cover</attributeLabel> <attributeDefinition>The percent ground cover on the field</attributeDefinition> <annotation> <propertyURI label="contains measurements of type">http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#containsMeasurementsOfType</propertyURI> <valueURI label="Plant Cover Percentage">http://purl.dataone.org/odo/ECSO_00001197</valueURI> </annotation> </attribute> example 3 presented as an RDF graph 11.2.3 Annotations grouped under the EML <annotations> element Examples 1-3 above show annotations directly beneath the parent element, which is the semantic subject. However, all the annotations for an entire dataset can be grouped together instead of nested below a parent element. This can be accomplished in two ways/places: (1) in an <annotations> element (example 4), and (2) under <additionalMetadata> (example 5). When the annotations are grouped together, each annotation must have its subject designated by a references attribute that points to the id attribute of the element being annotated (the subject). That is, what is listed in the references attribute is the id of the subject of the semantic annotation. An implication of this is that that any EML element with an id can become the subject of an annotation. 11.2.3.1 Example 4: Annotating with the <annotations> element All the annotations for a resource can be grouped together under an annotations element. With this construct, each annotation must have its subject specifically identified with a references attribute that points to the subject’s id. The group of annotations must be placed… This example 4 contains 3 different annotations: In the first, the subject is the dataTable element with the id of “CDF-soil-table”. Its annotation components are analogous to Example 2 above, again referencing terms in IAO and ENVO. The semantic statement can be read as “the dataTable with the id ‘CDR-soil-table’ is about grassland biome(s)”. The second and third annotations both have individual persons as their subjects – the creator element that has the id “eric.seabloom”. Respectively, their semantic statements can be read as “‘eric.seabloom’, the creator (of the dataset), is a person”. “‘eric.seabloom’, the creator (of the dataset), is a member of University of Minnesota”. The ontologies used for eric.seabloom are in the second annotation propertyURI : uses an RDF built-in type, rdf:type that has label “is a” (as in, the subject *is an* instance of a class) valueURI : schema.org’s concept of a “person” third annotation propertyURI : another schema.org concept for a relationship, “is a member of” valueURI : the DOI, which is managed by Research Organization Registry, for the organization University of Minnesota. <eml> ... <dataset id="dataset-01"> <title>Soil organic matter responses to nutrient enrichment in the Nutrient Network:Nutrient Network. A cross-site investigation of bottom-up control over herbaceous plant community dynamics and ecosystem function.</title> <creator id="eric.seabloom"> <individualName> <givenName>Eric</givenName> <surName>Seabloom</surName> </individualName> </creator> <dataTable id="CDR-soil-table"> <entityName>e247_Soil organic matter responses to nutrient enrichment in the Nutrient Network</entityName> ... </dataTable> </dataset> ... <annotations> <annotation references="CDR-soil-table"> <propertyURI label="is about">http://purl.obolibrary.org/obo/IAO_0000136</propertyURI> <valueURI label="grassland biome">http://purl.obolibrary.org/obo/ENVO_01000177</valueURI> </annotation> <annotation references="eric.seabloom"> <propertyURI label="is a">http://www.w3.org/1999/02/22-rdf-syntax-ns#type</propertyURI> <valueURI label="Person">https://schema.org/Person</valueURI> </annotation> <annotation references="eric.seabloom"> <propertyURI label="member of">https://schema.org/memberOf</propertyURI> <valueURI label="University of Minnesota">https://ror.org/017zqws13</valueURI> </annotation> </annotations> ... </eml> example 4 as an RDF graph 11.2.4 Annotations grouped under <additionalMetadata> Like the annotations grouped under <annotations>, annotations can also be grouped under <additionalMetadata>. If an additionalMetadata section holds a semantic annotation, it must have a describes element (to hold the subject) with a metadata element containing at least one annotation element. The subject of the semantic statement has its id contained in the describes element. The annotation itself is within the additionalMetadata metadata section. Multiple annotation elements may be embedded in the same metadata element to assert multiple semantic statements about the same subject. To annotate different subjects, it is best to use multiple additionalMetadata sections, each with a single subject. 11.2.4.1 Example 5: additionalMetadata element annotation Example 5 shows one of the same annotations as presented in Example 4, but here is contained in an additionalMetadata section. The semantic statements can be read as “‘eric.seabloom’, the creator (of the dataset), is a person”. The subject of the semantic statement is the EML creator element with the id attribute “eric.seabloom”. The annotation itself has 2 parts propertyURI is “https://schema.org/memberOf”, which resolves to “is a member of”, from schema.org valueURI is “https://ror.org/017zqws13”, a DOI which resolves to “University of Minnesota”. <eml> ... <dataset id="dataset-01"> <title>Soil organic matter responses to nutrient enrichment in the Nutrient Network:Nutrient Network. A cross-site investigation of bottom-up control over herbaceous plant community dynamics and ecosystem function.</title> <creator id="eric.seabloom"> <individualName> <givenName>Eric</givenName> <surName>Seabloom</surName> </individualName> </creator> <dataTable id="CDR-soil-table"> <entityName>e247_Soil organic matter responses to nutrient enrichment in the Nutrient Network</entityName> ... </dataTable> </dataset> ... <additionalMetadata> <describes>eric.seabloom</describes> <metadata> <annotation> <propertyURI label="member of">https://schema.org/memberOf</propertyURI> <valueURI label="University of Minnesota">https://ror.org/017zqws13</valueURI> </annotation> </metadata> </additionalMetadata> </eml> 11.3 Appendix 11.3.1 Semantic triples Semantic annotations enable the creation of what are called triples, that are 3-part statements conforming to the W3C recommended RDF data model (learn more: https://www.w3.org/TR/rdf11-primer/). The newly introduced Semantic Annotation capabilities introduced in EML 2.2.0 are constructed in a way that affords relatively straightforward re-expression of those annotations as true RDF triples. A triple is composed of three parts: a subject, a predicate (that can be an object property or datatype property), and an object. [subject] [predicate] [object] These components are analogous to parts of a sentence: the subject and object can be thought of as nouns in the sentence and the predicate (object property or datatype property) is akin to a verb or relationship that connects the subject and object. The semantic triple expresses a statement about the associated resource, that is the subject. There are (perhaps unfortunately) several other ways that the components of an RDF statement are sometimes described. One popular “synonymy” for subject-predicate-object is resource-property-value, i.e. the subject is referred to as the resource, the predicate a property, and the object a value. This can be confusing, since the usual definition of a resource in the context of the World Wide Web is any identifiable ‘thing’ or object, especially one assigned a URI; and by this definition, resources can and often do occur in all three components of a triple. But thinking of a triple as a resource-property-value does provide an indication of the directionality of the semantics of an RDF statement. This latter terminology is also similar to how analogous components are named in JSON-LD. Note that JSON-LD is closely compatible with RDF, and one format can often be readily translated to the other (although there are some exceptions). Semantic annotations added to an EML document can be extracted and processed into a semantic web format, such as RDF/XML. These “semantic” statements, i.e. RDF triples, are interpretable by any machines that can process the W3C standard of RDF. Those RDF statements collectively constitute the Semantic Web. 11.3.2 URIs Ideally, the components of the semantic triple should be globally unique and persistent (unchanging), and consist of resolvable/dereferenceable HTTP uniform resource identifiers (URIs; or more formally, IRIs). The subjects of most EML semantic annotations will likely be HTTP URIs that identify the dataset resource itself, or specific attributes or other features within a dataset. The objects of EML semantic annotations, as well as the predicates that relate the subject to the object, will most typically be HTTP URI references to terms in controlled vocabularies (also called “ontologies”) accessible through the Web, so that users (or computers) can dereference the URIs and look up precise definitions and relationships of these resources to other terms. An example of a URI pointing to a term in a controlled vocabulary is: http://purl.obolibrary.org/obo/ENVO_00000097. When entered into the address bar of a web browser, the abpve URI resolves to the term with a label of “desert area” in the Environment Ontology (EnvO). Users can learn what this URI indicates and explore how the term is related to other terms in the ontology simply by dereferencing its URI in a web browser. All those other aspects you see on the Web page describing “http://purl.obolibrary.org/obo/ENVO_00000097” are from other RDF statements (triples) related to “ENVO_00000097”, and that have been rendered into HTML. From here, you might decide that “http://purl.obolibrary.org/obo/ENV0_00000172” (“sandy desert”) is a better annotation for your object. An RDF triple can be constructed as follows, with subject URI, predicate URI, and object URI: <<https://doi.org/10.6073/pasta/06db7b16fe62bcce4c43fd9ddbe43575>> <<http://purl.obolibrary.org/obo/RO_0001025>> <<http://purl.obolibrary.org/obo/ENVO_00000097>> . … indicating that the referenced dataset (subject/resource) was “located in” (predicate/property) a “desert area” (object/value). Note that when expressing a semantic triple, a blank-space must separate the subject, from the predicate, from the object, and that a “period” completes the triple. This is a valid RDF triple, expressed in N-Triple syntax. RDF is most often serialized into XML, however, as Web browsers and many applications are good at parsing XML. While our focus here is on the semantic annotation of EML documents, it is easy to see how the RDF statements can be used to describe and inter-relate any resources that have unique, persistent HTTP URIs! Note that the above RDF triple consists of three HTTP URIs. While the exact distinction among what is a URI, a URN, and a URL can be debated, for our purposes, these HTTP URIs can be considered both the name and web location of a resource. Content negotiation between a Web server and a client (which might be a browser, or a Python or R script) can enable an HTTP URI to dereference in ways optimized for the requesting client – e.g. in one case, presenting a human-readable view of metadata for a dataset, and in another, activating a download of that dataset for import into a script. Semantic annotations in EML are useful because they enable associating data objects described in EML, with terms from external vocabularies. These external vocabularies can be used by other systems to similarly describe data objects, dataset variables, etc. The ability to extract semantic annotations out of EML, and convert these into valid RDF triples, provides further utility that is a pathway to the future. Sets of RDF triples, called “graphs”, or in this case more accurately, “knowledge graphs” (since these triples describe our understanding of data set contents and their relationships) is under development at DataONE, NCEAS, EDI, through the rOpenSci project, and elsewhere. The RDF triple described above hopefully gives an idea of how such triples, constructed of dereferenceable HTTP URIs, can be very useful. Related FAQ: What is the difference between an URI and a URL? 11.3.3 RDF Graphs In a data-modeling sense, a graph consists of resources linked to other resources. Thus, the simplest graph structure is a triple, that consists of two nodes that are somehow linked. This is the basic model underlying RDF: a predicate linking a subject to an object. A graph consists of many triples that can be linked with one another. Below are examples of how annotations can be converted to RDF triples in RDF/XML, so that the RDF information is now computer-readable. Be aware that there are several formats for serializing RDF, including RDF/XML, Turtle, N-Triples, and N3, that vary in the level of how human-readable they are– although these are all machine-readable with complete consistency. The process of converting (i.e., extracting) a semantic annotation in EML into RDF, is done by parsing applications under development at EDI, NCEAS, rOpenSci, and other data repositories. Careful examination of the examples below also show references to “owl:Class”, “owl:ObjectProperty”, and other statements that may not be familiar. These are fundamental entities or building blocks in W3C-recommended Semantic Web languages, and are determined by the relationships that the triple component identifiers (HTTP URIs) have within their native knowledge graph/ontology. Related FAQ: What is RDFS? Related FAQ: An image of an RDF Graph is great, but a computer doesn’t parse that. What does the RDF look like? 11.3.3.1 Graph from Example 3 (attribute annotation): (back to Example 3 XML) RDF example A <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#"> <rdf:Description rdf:about="att.4"> ### See note below <owl:ObjectProperty rdf:about="http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#containsMeasurementsOfType"> <owl:Class rdf:about="http://purl.dataone.org/odo/ECSO_00001197" /> </owl:ObjectProperty> </rdf> </rdf:RDF> Note: The subject described in the rdf:Description about element attribute ideally would be a globally unique HTTP URI for the (EML) attribute, rather than ‘att.4’– which is a localized identifier. Methods for constructing this HTTP URI are being developed by EDI, NCEAS, and others. While care must be taken that the id provided in the original EML was unique or defined with proper scoping and referencing elements, in RDF this is not a problem: ids specified in “rdf:about” attributes can be repeated without issue. 11.3.3.2 Graph from Example 4 (using annotations element): (back to Example 4 XML) RDF example B <rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#" xmlns:owl="http://www.w3.org/2002/07/owl#"> <rdf:Description rdf:about="eric.seabloom"> ### See note below <owl:ObjectProperty rdf:about="http://www.w3.org/1999/02/22-rdf-syntax-ns#type"> <owl:Class rdf:about="https://schema.org/Person" /> </owl:ObjectProperty> <owl:ObjectProperty rdf:about="https://schema.org/memberOf"> <owl:Class rdf:about="https://ror.org/017zqws13" /> </owl:ObjectProperty> </rdf> </rdf:RDF> Note: The subject described in the rdf:Description about= element attribute should ideally be a globally unique URI issued for ‘eric.seabloom’. The URL for Eric’s ORCID ID would be a good candidate for filling this role. Methods for constructing this HTTP URI are being developed by EDI, NCEAS, and others, for referencing datasets and their components (e.g. specific attributes), in their various sponsored data repositories. Unlike EML, there are not restrictions on re-using “identifiers” in this way 11.3.4 Check for Logical Consistency With semantic annotation, you are adding precise definitions of concepts and relationships that can be traversed with computer logic. Annotations are not simply a set of loosely structured keywords! This is a really powerful addition to EML, and so it comes with some risk. The main thing you should ensure is that your annotations are logically consistent. The simplest way to check your logic is to write out the RDF triple components and see if it makes sense as a sentence. [subject (element-id)] [predicate (propertyURI)] [object (valueURI)] [att.4] [contains measurements of type] [plant cover percentage] The graph examples (Example 3 RDF graph, Example 4 RDF graph) make ‘true’ statements that are logically consistent: att.4 contains measurements of the type plant cover percentage eric.seabloom is a person eric.seabloom, member of University of Minnesota However, below is the kind of statement you would NOT want to make: [eric.seabloom] [is a type of] [measurement] If you suspect your RDF triple might look like this, you should go back and examine the way you structured the annotation. Things to check: Be sure you have used the right classes, properties, or vocabularies for your annotation components Become familiar with the vocabularies in your annotation, especially any labels, definitions, and relationships associated with your term(s) of interest. Check with your community for specific recommendations on the best vocabularies to use for annotations at different levels. Our examples use well-constructed vocabularies. In additionalMetadata, don’t combine annotations with more than one describes element. EML allows 1:many describes elements in a single additionalMetadata section. So if you have 2 describes and 2 annotations, you will have 4 RDF statements. Make sure they are all true, and if not, break them up into multiple additionalMetadata sections. 11.3.5 Glossary dereference: To interpret a URI, and retrieve information about the resource identified by that URI See resolve. IRI: Internationalized Resource Identifier (IRI), and an extension of ASCII characters subset of the Uniform Resource Identifier (URI) protocol. JSON-LD (JavaScript Object Notation for Linked Data), is a method of mapping from JSON to an RDF model. It is administered by the RDF Working Group and is a World Wide Web Consortium Recommendation. knowledge graph: Any knowledge base that is represented as a mathematical graph. In the mathematical sense, a graph is simply a collection of points connected by lines. The points are called nodes or vertices, while the lines are called edges or links. In an informatics sense, this structure is used to store information about a set of objects, including the identity of the objects (as nodes), and the relationships among the objects (as links). Note that the use of the word “object” here is very general, and is not the same sense as when we describe triples. In an RDF (semantic) triple, the subject and object (the word object here in the specific RDF sense!) are represented as nodes, and the relationship between the nodes is represented as an edge or link. Note however that a subject of one triple can serve as an object of another triple, and vice-versa. The term Knowledge Graph is generally used nowadays to refer not so much to an underlying controlled vocabulary or ontology, but rather to the assertions about various objects and how these relate to ontology terms, and other objects. Thus, as a set of semantic annotations grows, for example, assertions (triples) about datasets, these would be stored in a growing knowledge graph. The most famous Knowledge Graph as of today is the one that informs search results for Google. ontology: In an informatics sense, an ontology is a representation of a corpus of knowledge. The W3C-recommendation is that these representations be constructed using an RDF data model, that has a graph structure. The ontology provides a representation of a set of terms, including their names, and descriptions of the categories, properties, and relationships among those terms. pointer: A kind of reference to a datum stored in computer memory. resolve: To interpret a URI and determine a course of action for dereferencing the URI. See dereference Resource Description Framework (RDF): A World Wide Web Consortium (W3C) recommendation that enables the encoding, exchange, and reuse of structured metadata using a graph model. The RDF data model employs semantic triples composed of a subject, predicate, and object to share and integrate data across different applications and communities through the Web. uniform resource identifier (URI): In its most general sense, a URI is simply a string of characters that unambiguously identifies a particular resource. Much more commonly, it refers to an identifier for a resource on the Web, but, e.g. ISBN numbers are also URIs. For semantic annotations, the components of semantic triples are ideally HTTP URIs that dereference using Web technology, to an appropriate representation of a resource, e.g. metadata about the dataset in the case of the subject, and definitions and descriptions of the meaning of the predicate and object terms that provide information about the subject. 11.3.6 Vocabularies and repositories used in examples Communities using EML annotations will develop recommendations for suitable vocabularies, based on their own requirements (e.g., domain coverage, structure, adaptability, reliabliity and maintenance model). The following ontologies are already widely used, were employed in the examples above, and are in use by (and in some cases managed by) the authors.: ECSO (Ecosystem Ontology) (https://github.com/DataONEorg/sem-prov-ontologies/tree/master/observation). An ontology for ecosystem measurements under development by the Arctic Data Center and DataONE. EnvO (Environment Ontology) (http://www.obofoundry.org/ontology/envo.html) An OBO Foundry ontology for the concise, controlled description of environments. IAO (Information Artifact Ontology) (http://www.obofoundry.org/ontology/iao.html) An OBO Foundry ontology of information entities. NCBITaxon Ontology http://www.obofoundry.org/ontology/ncbitaxon.html An OBO Foundry ontology representation of the National Center for Biotechnology Information organismal taxonomy. OBOE (Extensible Ontology for Observations) (https://github.com/NCEAS/oboe) An ontology for scientific observations and measurements developed by DataONE and NCEAS. ROR (Research Organization Registry) (https://ror.org/) A global registry of research organizations. schema.org (https://schema.org/) An initiative to create and support common sets of structured data markup on web pages. Extensions work with the core vocabulary to provide more specialized and/or deeper vocabularies. 11.3.7 Additional background information Following are tutorials and supplemental background reading LinkedDataTools tutorial: http://www.linkeddatatools.com/introducing-rdf RDF data model: https://www.w3.org/TR/WD-rdf-syntax-971002/ W3C RDF primer: https://www.w3.org/TR/rdf11-primer/ A tidyverse lover’s intro to RDF https://ropensci.github.io/rdflib/articles/rdf_intro.html Tim Berners-Lee’s article on the semantic web: Berners-Lee, T., Hendler, J., & Lassila, O. (2001). The semantic web. Scientific american, 284(5), 34-43. 11.4 Frequently asked questions Below are answers to questions some readers had, which may be helpful to you. If you have additional questions, please bring them up in your community for feedback. Q: Why do EML elements with annotations need id attributes? A: EML elements that have annotation children need id so that they can be used to construct the subject of an RDF triple. See above. Q: What is the difference between ‘dereference’ and ‘resolve’? A: Within the context of semantic annotation, “dereferencing” refers to the process of interpreting a URI, and providing “useful information” back about the Resource of interest. The phrase “resolving a URI” is often used synonymously with “dereferencing”, but technically “resolution” refers to the process of determining HOW and WHAT to do with the URI, whereas “dereferencing” is explicitly about the action taken, which is typically retrieving a representation of the Resource of interest. The formal specification for these terms and what they mean is found in the IETF’s (Internet Engineering Task Force) RFC (Request for Comment) 3986 (https://tools.ietf.org/html/rfc3986). Q: What is the difference between an URI and a URL? Example URIs look a lot like URLs… What about IRIs? A: The distinctions among URIs (Uniform Resource Identifiers), URLs (Uniform Resource Locators), and URNs (Uniform Resource Names), relate to differentiating the functionalities of identifying a Resource, as opposed to locating a Resource, or doing both. URLs are all URIs (with some edge case exceptions subject to argument), and URNs are also URIs. In many cases, URIs serve both to name and locate a Resource. Within the vision of the Semantic Web, URIs are ideally unique, persistent URNs identifying some Web Resource, that can also serve to locate and retrieve (dereference) a representation of that Resource (URLs). The formal specification for these terms and what they mean is found in the IETF’s RFC 3986, section 1.1.3 (https://tools.ietf.org/html/rfc3986#section-1.1.3). Another acronym one may encounter with increasing frequency is IRI (Internationalized Resource Identifier) that extends the concept of an HTTP URI to allow for use of the full Unicode character set, rather than just ASCII, in its construction (https://tools.ietf.org/html/rfc3987). Q: What is SKOS? A: SKOS (Simple Knowledge Management System) is a W3C recommendation for organizing a vocabulary in thesauri, taxonomies, and other classification schemes. SKOS provides a set of concepts and properties, that, when expressed in a formal RDF-compatible syntax, can assist with interpreting the relationship of terms with one another, such as defining some category as broader than another. For example, one could state in SKOS syntax, that “animals” is a broader concept than “mammals”. Definitive specification of SKOS can be found at https://www.w3.org/TR/2009/REC-skos-reference-20090818/. SKOS does not provide strong semantics (see RDFS example below), but SKOS concepts and properties can be used within more expressive knowledge organization frameworks, such as RDFS/OWL ontologies. Q: What is RDFS? A: RDFS stands for Resource Description Framework Schema. It extends the formal vocabulary for describing Resources expressed in an RDF data model (i.e., a graph). “Base RDF” is the set of concepts for creating a graph model of data (triples relating a subject, predicate, and object). RDFS adds to the base RDF model by specifying other well-defined concepts and properties, such as rdfs:Label, rdfs:Class and rdfs:subClassOf. These and other RDFS classes and properties, enable data and knowledge modellers to express many relationships between the Subject and Object of a Triple. In the context of the Semantic Web, the RDF model relies extensively on dereferenceable URIs in the subject and predicate positions, and URIs or literals in the object position (there are small formal exceptions to this not immediately relevant here). RDF triples can be expressed in several syntaxes, including XML, JSON-LD, and Turtle, among others. RDFS then can be used to enrich the precision and expressivity of the components of a triple, as well as clarify the relationships among these. Base RDF: https://www.w3.org/TR/2014/REC-rdf11-concepts-20140225/ RDFS: https://www.w3.org/TR/rdf-schema/ Q: Are all EML dataTable attributes “measurements”? A: Yes, in the context of a data table and for annotation purposes, any attribute (observation or column of data) can be considered ‘a measurement’. A philosopher might disagree, saying that some content you might see in data columns (e.g., unique identifiers) are not really measurements; but many other nominals, i.e. text strings identifying some class types (e.g. predator, lizard, tundra), imply quantification and can be construed as measurements. Q: Can you provide an example of a controlled vocabulary with an rdfs:label or skos:label? A: Most Semantic Web vocabularies make extensive use of rdfs:label or SKOS label properties. For example, this URI: http://purl.dataone.org/odo/ECSO_00000536 is from the ECSO ontology, under development at NCEAS by NSF’s DataONE and Arctic Data Center. Within that ontology, the URI is associated with an rdfs:label of “Carbon Dioxide Flux”, and a skos:altLabel of “CO2 flux”. If you dereference the URI, you will see how the BioPortal ontology repository displays this information– providing a human-readable representation of the underlying RDF/OWL language in which the ontology is stored. Q: How do computer use EML annotations? A: Annotations can be extracted from the EML document, and re-expressed (formally, “serialized”) into a Semantic Web language such as RDF or JSON-LD. Annotations (also called “assertions” or “triples” in RDF) collectively contribute to a knowledge graph, that captures understanding of the relationship of the contents of datasets (as “instances”) with the concepts represented by terms in ontologies (as “classes”). Q: An image of an RDF graph is great, but a computer doesn’t parse that. What does the RDF look like? A: Actual RDF (XML) is shown in the code blocks of Example 3 and Example 4. RDF is a data model based on triples, each of which has three components: a subject, predicate, and object, that are constructed of dereferenceable URIs. RDF triples can be “serialized” in several syntaxes, including XML, JSON-LD, Turtle, N-Triples, and others. These syntaxes are isomorphic, such that translations of RDF graphs from one serialization to another are available– enabling consistent interpretation by machines. For human interpretation the most straightforward serialization of RDF graphs is N-Triples, where an RDF triple could look like this: http://purl.obolibrary.org/obo/CHEBI_16526 http://purl.obolibrary.org/obo/RO_0000087 http://purl.obolibrary.org/obo/CHEBI_76413 . These are three URIs here– representing the Subject, Predicate, and Object of a Triple. The “.” indicates the end of the Triple. Of course, you would need to know that these three URI’s are intended to be interpreted as an RDF Triple. Dereferencing these URIs (e.g. a Web browser or specialized application) one can see that this Triple represents the statement: “Carbon dioxide”(Subject) “has role”(Predicate) “Greenhouse Gas”(Object) While the phrasing is a bit awkward sounding, the meaning is clear by simply depicting the rdfs:labels of those terms from the ChEBI (Chemical Entities of Biological Interest) and RO (Relation) ontologies, that are both robust OBO Foundry ontologies. As another example: http://purl.obolibrary.org/obo/NCIT_C20461 http://purl.org/dc/elements/1.1/creator https://orcid.org/0000-0003-1279-3709 . that asserts: “World Wide Web”(Subject) “creator”(Predicate) “Timothy Berners Lee”(Object) . …although some semantic purists might question whether the Dublin Core property “Creator” can be used in this way as an RDF predicate, since it is not semantically defined– would its rdfs:label be “creatorOf” or “hasCreator”? (Dublin Core does not say explicitly, but implicitly is indicative of “hasCreator”!). Regardless of the formal semantic well-formedness of this Triple, however, one can see the expressive power of the RDF data model, and the value of dereferenceable URIs. A better solution would be to use the semantically defined term from SIO (the Semantic Science Integrated Ontology) http://semanticscience.org/resource/SIO_000364 as the predicate, with an rdfs:label “has creator” http://purl.obolibrary.org/obo/NCIT_C20461 http://semanticscience.org/resource/SIO_000364 https://orcid.org/0000-0003-1279-3709 . …that would translate as (based on content of the rdfs:label): World Wide Web(Subject) has creator(Predicate) Tim Berners-Lee(Object) or inversely, one could use http://semanticscience.org/resource/SIO_000365 as the predicate, that has rdfs:label “is creator of” Tim Berners-Lee(Subject) is creator of(Predicate) World Wide Web(Object) https://orcid.org/0000-0003-1279-3709 http://semanticscience.org/resource/SIO_000365 http://purl.obolibrary.org/obo/NCIT_C20461. Within the SIO ontology, SIO_000364 and SIO_000365 are defined as inverses of one another. This enables one (a person or a computer!) to ask either question– “who created the Web?” (A: Tim Berners-Lee), or “what did Tim Berners-Lee create” (A: the Web)– even though you only asserted one of the Triples. Finally, it is worth noting that one’s choice of which Ontologies to use is important. Within the Ecological and Environmental sciences, there are several highly-recommended vocabularies, including those from the OBO Foundry (e.g. ChEBI, EnvO, RO, and PATO), as well as SIO. Specifically for annotating scientific measurements, the Arctic Data Center and DataONE are developing an Ontology for Ecosystem Measurements, ECSO. These use, where possible, terms from the OBO Foundry ontologies mentioned here. We have used all these in the examples. Q: Are there tools available to help data managers select subjects, predicates, and objects to annotate with? A: Yes, tools are being built to assist with the semantic annotation of EML documents, within the DataONE and Arctic Data Center data repository projects, and others. In addition, tools are being built to enable semantic search, that use the annotations to expand searches to capture synonyms, differentiate homonyms, and enable the discovery of sub-classes of the terms that you might originally be searching for. "],
["internationalization-metadata-in-multiple-languages.html", "12 Internationalization - Metadata in multiple languages", " 12 Internationalization - Metadata in multiple languages EML supports internationalization using the i18nNonEmptyStringType. This allows an element in EML to contain text in a default language, as well as optional representations of that element in other languages. Fields defined as this type include: Title Keyword Contact information (e.g. names, organizations, addresses) TextType fields also support language translations. These fields include: Abstract Methods Protocol Core metadata should be provided in English. The core elements can be augmented with translations in a native language. Detailed metadata can be provided in the native language as declared using the xml:lang attribute. Authors can opt to include English translations of this detailed metadata as they see fit. Example 2.1. Internationalization techniques The following example metadata document is provided primarily in Portuguese but includes English translations of core metadata fields. The xml:lang="pt_BR" attribute at the root of the EML document indicates that, unless otherwise specified, the content of the document is supplied in Portuguese (Brazil). The xml:lang="en_US" attributes on child elements denote that the content of that element is provided in English. Core metadata (i.e. title) is provided in English, supplemented with a Portuguese translation using the value tag with an xml:lang attribute. Note that child elements can override the root language declaration of the document as well as the language declaration of their containing elements. The abstract element is primarily given in Portuguese (as inherited from the root language declaration), with an English translation. Many EML fields are repeatable (i.e. keyword) so that multiple values can be provided for the same concept. Translations for these fields should be included as nested value tags to indicate that they are equivalent concepts expressed in different languages rather than entirely different concepts. <?xml version="1.0"?> <eml:eml packageId="eml.1.1" system="knb" xml:lang="pt_BR" xmlns:eml="https://eml.ecoinformatics.org/eml-2.2.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="https://eml.ecoinformatics.org/eml-2.2.0 eml.xsd"> <dataset id="ds.1"> <!-- English title with Portuguese translation --> <title xml:lang="en-US"> Sample Dataset Description <value xml:lang="pt-BR">Exemplo Descrição Dataset</value> </title> ... <!-- Portuguese abstract with English translation --> <abstract> <para> Neste exemplo, a tradução em Inglês é secundário <value xml:lang="">In this example, the English translation is secondary</value> </para> </abstract> ... <!-- two keywords, each with an equivalent translation --> <keywordSet> <keyword keywordType="theme"> árvore <value xml:lang="en-US">tree</value> </keyword> <keyword keywordType="theme"> água <value xml:lang="en-US">water</value> </keyword> </keywordSet> ... </dataset> </eml:eml> "],
["release-notes.html", "13 Release Notes", " 13 Release Notes (see also http://github.com/NCEAS/eml/issues) 13.0.1 2.2.0 13.0.1.1 Major New Features 13.0.1.2 Schema changes: 13.0.2 2.1.1 13.0.2.1 Internationalization in EML 2.1.1 EML 2.1.1 introduces internationalization capabilities that can be used in most text-based elements. Version 2.1.1 remains backward-compatible with the previous 2.1.0 release. Authors can safely upgrade existing 2.1.0 documents to 2.1.1 without altering any content, though adding additional language translations is encouraged. By allowing mixed element content, nested translation elements can be included without altering or introducing ambiguity with respect to EML element cardinality. Translation elements use standard xml:lang attributes to specify the language used for their content. Translation elements can be nested such that child elements may inherit or override the language used by their ancestors. The top-level EML element may include an xml:lang attribute which will apply to every element in the document unless a child element includes a different xml:lang attribute to override the document default. Multi-lingual authors of EML should carefully consider their primary target audience when deciding the default document language. Early adopters should be aware search tools like Metacat will require custom configuration in order to search arbitrarily nested translations. The internationalization feature allows authors to place any language in tags nested within most EML text fields. The xml:lang attribute should be used to explicitly declare the language used. Additional documentation and examples are available in the EML specification. The i18nNonEmptyStringType is used for simple text, while i18nString for more structured text elements. 13.0.2.2 Schema changes: - [76](https://github.com/NCEAS/eml/issues/76): internationalization needed in EML 13.0.3 2.1.0 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) This release addresses bugs which caused the schema to be invalid with respect to the W3C specifications using modern validators (e.g., http://www.w3.org/2001/03/webdata/xsv). Although the changes were minor, one was incompatible with 2.0 releases, which necessitated the version number “2.1”. In the 2.0 series, the content model for additionalMetadata included an element <describes> whose cardinality was 0..many, alongside <xs:any>. This construct is non-deterministic, and so a child element was added to the additionalMetadata section to contain the <xs:any> content. Additionally, several elements of txt:TypeText required additional definition so that mixed content could be accommodated. These errors were not apparent with validation software available in 2004-2005, but were brought to light more recently. Several small changes were made to the enumeration list and unitTypes for standard units and stmml descriptions of customUnits. Two elements in the literature schema were allowed to be optional so that articles-in-press could be described. The named type for element gRing was changed to GRingType. EML makes use of the STMML schema (stmml.xsd) for describing custom units and describing its included list of standardUnits (unitList). The STMML schema was also found to be non-deterministic, and the most reasonable fix for this bug was not compatible with earlier versions. This error was NOT related to elements used by EML (unitList or unitType). However, given that authors of EML instance documents may have made use of other parts of stmml.xsd, it was decided to the advance the namespace used for stmml-related files to “stmml-1.1”, in keeping with the pattern of version naming in EML. The stmml authors have been contacted. Schema changes: 1132: eml.xsd, physical.xsd: fix access rule ambiguities 2054: eml.xsd: added the tag to additionalMetadata 1154: resource.xsd: required element offline has no required children 3480: resource.xsd, physical.xsd: nearly duplicate complexTypes, DistributionType and PhysicalDistributionType 3165: resource.xsd: provide a place for a url description 3227: coverage.xsd: gRing was declared as GRingPointType, is now GRingType 1019: coverage.xsd: altitudeUnits should use eml-unitDictionary 3500: coverage.xsd: restrict boundingCoordinates to realistic lat/lon ranges 1152: attribute.xsd: dateTime elements are named inconsistently; standarized on dateTime 2272: attribute.xsd: base types in BoundsGroup changed to xs:float 3051: attribute.xsd: missing units were added to enumeration list to match eml-unitDitionary 2568: attribute.xsd, entity.xsd: inconsistent naming of methods elements, standardized to 2703: text.xsd: refined element declarations in txt:TextType for para, section; added ulink, citetitle 3163: literature.xsd: cardinality of volume and pageRange is now 0..1 3164: literature.xsd: literature needs a contact tree 3445: stmml.xsd: non-deterministic 2083: stmml.xsd: dimension ‘current’ was wrongly entered as ‘charge’ Parser : 3232: EML parser should use full-schema-checking 3836: runEMLParser script should include sax-validate Stylesheets: 3508: create a stylesheet for EML2.0.x to EML 2.1.0 3590: eml-documentation stylesheet problem with derived content. 2048: param attributeindex defined twice in eml-settings.xsl 2085: Access control rules adapted for 2.0.1 and 2.1 (currently not shown) 2147: EML Stylesheet problem with web address URL’s 2226: EML2 style sheet double the number of complex delimited f… 3492: the word ‘unit’ should be pluralized by default 13.0.4 2.0.1 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) 249: Update XSLT stylesheets for EML 2.0 modules 939: spelling errors for ‘its’ in index 960: parser not correctly parsing tag in additiona… 1008: inline element doesn’t support character child 1017: documentation error in eml-methods 1031: enumeratedDomain doesn’t define value order for ordinals 1035: Technical documentation on eml-methods has an error 1124: update precision field definition and cardinality 1129: Change temporalCoverage calendarDate type 1132: fix access control rule ambiguities 1136: kelvin conversion incorrect in unit dictionary 1149: BoundsGroup bounds min & max have incorrect cardinality 1150: documentation for KeyTypeCode is wrong 1151: misspelled element name 1153: dateTimeDomain element should be optional 1155: Documentation incorrect for dateTimeDomainType bounds 1195: tracking bug for 2.0.1 release 1233: dateTime formatString Documentation contains incorrect ex… 1529: no tag to specify how to handle mutltiple, repeated delimimeters 1652: eml-constraint documentation error 13.0.5 2.0.0 - (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) 670: DateTimeDomain id/reference validation 924: make date time its own measurement scale 661: spell check eml-attribute.xsd and synchronize with unitDi 918: example tag in eml:documentation 13.0.6 2.0.0rc3 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) 471: eml spec overview document 624: eml-methods/methodsType needs clarification on choice/seq… 627: links broken in EML FAQ 629: unit conversion coefficients need checking 637: attributeDomain should be required 638: request for id/ref in attributeDomain 654: scope of the unit element 655: need better model for numeric domains for attributes 625: Cardinality regarding eml-methods should be corrected in … 626: ProcedureStepType schema needs revision to protect sequen… 628: eml-physical has lit: rather than cit: references 632: broken link in faq 634: Documentation of reference elements in the schemas 656: physical should be repeatable 13.0.7 RC2 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) 568: accommodate of stateful connection information 586: resolve validation problem with missing keys 588: Remove lineage tags in documentation stylesheets 589: eml-coverage: convert element references to types 592: fix validation error with xs:anyType 594: change cardinality for designDescription and studyAreaDes… 596: Proposal: make attribute optional in OtherEntityType. 597: In eml-dataTable caseSensitive and orientation are modele… 598: literature namespace references are inconsistent 599: storageType is repeatable in eml-attribute 600: eml-storedProcedure - problems & proposal 601: element names in spatial modules do not follow guidelines 602: eml-physical fixed textFormat to allow mixed fixed/delimited 608: release preparation tasks for EML2.0.0rc2 622: redundancy in eml-physical/binaryRaster 13.0.8 RC1 (numbers refer to the corresponding Bugzilla bug id, not the GitHub #) 471: created an EML specification overview document 495: created FAQ for EML 588: removed lineage tags from documentation stylesheet 484: eml-attribute changes to unit and attributeDomain 579: fixed eml-docbook validation problems 491: eml-coverage changed to correctly import types and to fix singleDateTime model 485: eml-physical changed to fix fixed ascii descriptors and distribution 477: complexTypes imports changed to consistent model 486: fixed spelling errors in eml-constraint 492: eml-literature changed for EndNote consistency 496: copyright updated throughout 557: textual elements changed to use docbook subset define in eml-text.xsd 563: changed id types from xs:ID to xs:string to allow numeric ids 482: eml-dataset changed to include method element 489: eml-protocol completely revised based on feedback, eml-method.xsd created 544: eml-attribute storageType and attributeDomain documentation clarified 556: format of eml namespaces changed to include ecoinformatics.org 539: added additionalInfo and alternateIdentifier to eml-dataTable.xsd 568: redesigned DistributionType to allow richer connection descriptions 566: changed imports in eml-resource to import resource types not elements 567: created eml sample documents and XML validation framework using ant/junit 13.0.9 Beta9 Fixes- Changed packaging concept to use internal id and references instead of triples Review and revised all modules according to agreed upon changes from the April, 2002 EML meeting at Sevilleta Field Station 13.0.10 Beta 8 Fixes- Fixed illegal declaration of type and extension in eml-entity Updated all PNG image files 13.0.11 Beta 7 Fixes- Added a ‘style’ subdirectory with a style sheet for most modules . to translate the metadata to HTML Changed names of coverage elements to be human readable Updated the namespaces to reflect the current version number of EML Added an eml-data module for the in-lining of data. Added the eml module for creating packages all in one file. It is a single node with a model of ANY so any of the eml modules can be put into it. Numerous bug fixes (see bugzilla.ecoinformatics.org) "],
["about-this-site.html", "14 About this site 14.1 Building the site 14.2 Deploying the site", " 14 About this site This site was build using Bookdown (Xie 2015) from Yihui Xie. Thanks! 14.1 Building the site Source code for the book is maintained in the docs directory of the EML repository in markdown format. To edit the site, make changes to the markdown files and configuration files in docs, and then run the build_book.R script which builds the bookdown version of the site and places the files in the dist directory. The configuration file _bookdown.yml controls the inclusion and order of the chapters. Generally, there is one markdown file for each chapter, and so it should start with a single level 1 heading which will act as the chapter title in the table of contents. Note that if you have also made changes to the XSD schema files for EML, then you should also regenerate the schema documentation using Oxygen. This requires a trial or licensed version of Oxygen, and can be run using the shell script bin/build_schema_documentation.sh. Here are example commands for updating the site after you’ve changed the markdown documentation and XSD files. $ ./bin/build_schema_documentation.sh $ cd docs $ R -e 'build_book.R' $ cd .. $ git add dist $ git commit $ git pull --rebase $ git push 14.2 Deploying the site Once the changes are committed and pushed in the dist directory, it is ready to be deployed on the web by pushing the files to the gh_pages branch. Publishing gh_pages content to the web is currently handled by Netlify which publishes the site to the custom domain https://eml.ecoinformatics.org. To deploy a new version of the site, first edit, build, and commit the site to the master branch as described in the previous section, and then deploy the site using the provided deployment shell script which updates the gh_pages branch for you: $ ./bin/deploy_site.sh This will copy the currently commited files in the dist directory to the gh_pages branch, which will be picked up and deployed by Netlify shortly thereafter. References "],
["references.html", "15 References", " 15 References "]
]