From 04c6d9a491ddc394994010f0d2a383577ca08dca Mon Sep 17 00:00:00 2001 From: Steven Chong Date: Thu, 13 Dec 2018 16:31:03 -0800 Subject: [PATCH] add documentation to attribute annotation section Added documentation to the attribute annotation section. Also changed order of the document --- docs/eml-semantic-annotations-primer.md | 74 ++++++++++++------------- 1 file changed, 34 insertions(+), 40 deletions(-) diff --git a/docs/eml-semantic-annotations-primer.md b/docs/eml-semantic-annotations-primer.md index 354cf2ce..991258ee 100644 --- a/docs/eml-semantic-annotations-primer.md +++ b/docs/eml-semantic-annotations-primer.md @@ -1,47 +1,9 @@ # Semantic Annotations Primer insert introductory text here + * URIs should be resolvable - -## attribute - -An attribute annotation represents a precisely-defined semantic statement that applies to an attribute (e.g. a characteristic of an object such as a column name in a spreadsheet). This semantic statement is used to associate precise measurement semantics with the attribute, such as the property that is being measured, the entity that is being measured, and the measurement standard for interpreting values for the attribute. - -A typical attribute annotation is embedded in a containing EML `attribute` element. Each annotation consists of a propertyURI and valueURI that define the property and value of the semantic statement. The subject of the statement is the EML `attribute` that contains the annotation. The associated labels can be used to display the statement to users. Each URI is resolvable to a controlled vocabulary that provides a definition, relationships to other terms, and multiple labels for displaying the statement. - - -In the example EML `attribute` element annotation below, the subject of the annotation is "att.4". - - - -- describe that this annotation is embedded within an EML `attribute` element and the annotation subject is the `attribute` id attribute value -- describe the propertyURI and valueURI elements in the annotation, the label attributes of these elements, and the content of these elements - -Example EML `attribute` element annotation: - -``` - - pctcov - percent cover - The percent ground cover on the field - - http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#containsMeasurementsOfType - http://purl.dataone.org/odo/ECSO_00001197 - - - -``` - - -## entity - -- describe that this annotation is embedded within an EML `dataTable` (?) element and the annotation subject is the `dataTable` id attribute value -- describe the propertyURI and valueURI elements in the annotation, the label attributes of these elements, and the content of these elements -- show an example annotation - - - -## dataset +## dataset level - describe that this annotation is embedded within an EML `dataset` element and the subject is the `dataset` id attribute value - describe the propertyURI and valueURI elements in the annotation, the label attributes of these elements, and the content of these elements @@ -68,6 +30,38 @@ Example `dataset` annotation: ``` +## entity level + +- describe that this annotation is embedded within an EML `dataTable` (?) element and the annotation subject is the `dataTable` id attribute value +- describe the propertyURI and valueURI elements in the annotation, the label attributes of these elements, and the content of these elements +- show an example annotation + + + +## attribute level + +An attribute is a characteristic that describes a 'field' or 'variable' in a data entity, such as a column name in a spreadsheet. An attribute annotation represents a precisely-defined semantic statement that applies to an attribute. This semantic statement is used to associate precise measurement semantics with the attribute, such as the property being measured, the entity being measured, and the measurement standard for interpreting values for the attribute. + +A typical attribute annotation is embedded in a containing EML `attribute` element. Each annotation consists of a propertyURI and valueURI that define the property and value of the semantic statement. The subject of the statement is the EML `attribute` that contains the annotation. The associated labels can be used to display the statement to users. Each URI is resolvable to a controlled vocabulary that provides a definition, relationships to other terms, and multiple labels for displaying the statement. + +In the following EML `attribute` element annotation below, the subject of the semantic statement is the `id` element attribute value, "att.4". The object property of the statement is `http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#containsMeasurementsOfType`. Note that the URI for the object property resolves to a specific term in the OBOE ontology (https://github.com/NCEAS/oboe). Finally, the object in the semantic statement is `http://purl.dataone.org/odo/ECSO_00001197`, which resolves to the "Plant Cover Percentage" term in the ECSO Ontology (https://github.com/DataONEorg/sem-prov-ontologies/tree/master/observation). Taken together, the semantic statement can be interpreted as "att.4 contains measurements of type plant cover percentage". + +Example EML `attribute` element annotation: + +``` + + pctcov + percent cover + The percent ground cover on the field + + http://ecoinformatics.org/oboe/oboe.1.2/oboe-core.owl#containsMeasurementsOfType + http://purl.dataone.org/odo/ECSO_00001197 + + + +``` + + ## /eml/annotations - describe how a `references` attribute (of the annotation element) points to the `id` of the subject of the annotation