add documentation to attribute annotation section

Added documentation to the attribute annotation section. Also changed order of the document
NCEAS · Dec 14, 2018 · 04c6d9a · 04c6d9a
1 parent 0d22555
commit 04c6d9a
Showing 1 changed file with 34 additions and 40 deletions.
diff --git 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:
-
-```
-<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>
-
-```
-
-
-## 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:
+
+```
+<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>
+
+```
+
+
 ## /eml/annotations
 
 - describe how a `references` attribute (of the annotation element) points to the `id` of the subject of the annotation