Module Documentation: eml-attribute

The content model for attribute is a CHOICE between "references" and all of the elements that let you describe the attribute (e.g., attributeName, attributeDefinition, precision). The attribute element allows a user to document the characteristics that describe a 'field' or 'variable' in a data entity (e.g. dataTable). Complete attribute descriptions are perhaps the most important aspect to making data understandable to others. An attribute element describes a single attribute or an attribute element can contain a reference to an attribute defined elsewhere. Using a reference means that the referenced attribute is (semantically) identical, not just in name but identical in its complete description. For example, if attribute "measurement1" in dataTable "survey1" has a precision of 0.1 and you are documenting dataTable survey2 which has an attribute called "measurement1" but the survey2's measurement1 has a precision of 0.001 then these are different attributes and must be described separately.

Attribute name is official name of the attribute. This is usually a short, sometimes cryptic name that is used to refer to the attribute. Many systems have restrictions on the length of attribute names, and on the use of special characters like spaces in the name, so the attribute name is often not particularly useful for display (use attributeLabel for display). The attributeName is usually the name of the variable that is found in the header of a data file.
Example(s):
spden
spatialden
site
spcode

A descriptive label that can be used to display the name of an attribute. This is often a longer, possibly multiple word name for the attribute than the attributeName. It is not constrained by system limitations on length or special characters. For example, an attribute with a name of 'spcode' might have an attributeLabel of 'Species Code'.
Example(s):
Species Density
Spatial Density
Name of Site
Species Code

This element gives a precise definition of attribute in the data entity (dataTable, spatialRaster, spatialVector, storedProcedure, view or otherEntity) being documented. It explains the contents of the attribute fully so that a data user could interpret the attribute accurately. Some additional information may also be found in the methods element as well.
Example(s):
"spden" is the number of individuals of all macro invertebrate species found in the plot

This element describes the storage type, for data in a RDBMS (or other data management system) field. As many systems do not provide for fine-grained restrictions on types, this type will often be a superset of the allowed domain defined in attributeDomain. Values for this field are by default drawn from the XML Schema Datatypes standard values, such as: integer, double, string, etc. If the XML Schema Datatypes are not used, the type system from which the values are derived should be listed in the 'typeSystem' attribute described below. This field represents a 'hint' to processing systems as to how the attribute might be represented in a system or language, but is distinct from the actual expression of the domain of the attribute. The field is repeatable so that the storageType can be indicated for multiple type systems (e.g., Oracle data types and Java data types).
Example(s):
integer
int

The measurementScale element indicates the type of scale from which values are drawn for the attribute. This provides information about the scale in which the data was collected.
Example(s):
Nominal is used when numbers have only been assigned to a variable for the purpose of categorizing the variable. An example of a nominal scale is assigning the number 1 for male and 2 for female.
Ordinal is used when the categories have a logical or ordered relationship to each other. These types of scale allow one to distinguish the order of values, but not the magnitude of the difference between values. An example of an ordinal scale is a categorical survey where you rank a variable 1=good, 2=fair, 3=poor.
Interval is used for data which consist of equidistant points on a scale. The Celsius scale is an interval scale, since each degree is equal but there is no natural zero point (so, 20 C is not twice as hot as 10 C).
Ratio is used for data which consists not only of equidistant points but also has a meaningful zero point, which allows ratios to have meaning. An example of a ratio scale would be the Kelvin temperature scale (200K is half as hot as 400K), and length in meters (e.g., 10 meters is twice as long as 5 meters).

This field is used for defining the characteristics of this variable if it is a nominal scale variable, which are variables that are categorical in nature. Nominal is used when numbers have only been assigned to a variable for the purpose of categorizing the variable. An example of a nominal scale is assigning the number 1 for male and 2 for female.

This field is used for defining the characteristics of this variable if it is an ordinal scale variable, which specify ordered values without specifying the magnitude of the difference between values. Ordinal is used when the categories have a logical or ordered relationship to each other. These types of scale allow one to distinguish the order of values, but not the magnitude of the difference between values. An example of an ordinal scale is a categorical survey where you rank a variable 1=good, 2=fair, 3=poor.

This field is used for defining the characteristics of this variable if it is an interval scale variable, which specifies both the order and magnitude of values, but has no natural zero point. Interval is used for data which consist of equidistant points on a scale. The Celsius scale is an interval scale, since each degree is equal but there is no natural zero point (so, 20 C is not twice as hot as 10 C). zero point (so, 20 C is not twice as hot as 10 C).

This field is used for defining the characteristics of this variable if it is a ratio scale variable, which specifies the order and magnitude of values and has a natural zero point, allowing for ratio comparisons to be valid. Ratio is used for data which consists not only of equidistant points but also has a meaningful zero point, which allows ratios to have meaning. An example of a ratio scale would be the Kelvin temperature scale (200K is half as hot as 400K), and length in meters (e.g., 10 meters is twice as long as 5 meters).

The dateTime field is used for defining the characteristics of the attribute if it contains date and time values. DateTime is used when the values fall on the Gregorian calendar system. DateTime values are special because the have properties of interval values (most of the time it is legitimate to treat them as interval values by converting them to a duration from a fixed point) but they sometimes only behave as ordinals (because the calendar is not predetermined, for some dateTime values one can only find out the order of the points and not the magnitude of the duration between those points). Thus, the dateTime scale provides the information necessary to properly understand and parse date and time values without improperly labeling them under one of the more traditional scales.

Date and time values are unlike any other measured values. Note that the dateTime field would not be used if one is recording time durations. In that case, one should use a standard unit such as seconds, nominalMinute or nominalDay, or a customUnit that defines the unit in terms of its relationship to SI second.

A format string that describes the format for a dateTime value from the Gregorian calendar. DateTime values should be expressed in a format that conforms to the ISO 8601 standard. This field allows one to specify the format string that should be used to decode the date or time value. To describe the format of an attribute containing dateTime values, construct a string representation of the format using the following symbols:

              Y   year
              M   month
              W   month abbreviation (e.g., JAN)
              D   day
              h   hour
              m   minute
              s   second
              T   time designator (demarcates date and time parts of date-time)
              Z   UTC designator, indicating value is in UTC time
              .   indicates a decimal fraction of a unit
              +/- indicates a positive or negative number,
                  or a positive or negative time zone adjustment relative to UTC
              -   indicates a separator between date components
              A/P am or pm designator
              

Any other character in the format string is interpreted as a separator character. Here are some examples of the format strings that can be constructed.

                                 Format string          Example value
                                 -------------------    ------------------
                  ISO Date       YYYY-MM-DD             2002-10-14
                  ISO Datetime   YYYY-MM-DDThh:mm:ss    2002-10-14T09:13:45
                  ISO Time       hh:mm:ss               17:13:45
                  ISO Time       hh:mm:ss.sss           09:13:45.432
                  ISO Time       hh:mm.mm               09:13.42
                  Non-standard   DD/MM/YYYY             14/10/2002
                  Non-standard   MM/DD/YYYY             10/14/2002
                  Non-standard   MM/DD/YY               10/14/02
                  Non-standard   YYYY-WWW-DD            2002-OCT-14
                  Non-standard   YYYYWWWDD              2002OCT14
                  Non-standard   YYYY-MM-DD hh:mm:ss    2002-10-14 09:13:45
              

Some notes about these examples. First, the ISO 8601 standard is strict about the order of date components and the separators that are legal. Best practice is to follow the ISO 8601 format precisely. However, we recognize that existing data contain non-standard dates, and existing equipment (e.g., sensors) may still be producing non-standard dates. Consequently, we have provided the formatting string with additional characters to describe the date formats. In particular note that the use of a slash (/) to separate date components, a space to separate date and time components, using a twelve-hour time with am/pm designator, and placing any of the components out of descending order is non-standard according to ISO. Nevertheless, these formats can be described using the format string to accommodate existing data.

Decimal dateTime values can be extended by indicating in the format that additional decimals can be used. Only the final unit (e.g., seconds in a time value) can use the extended digits according to the ISO 8601 standard. For example, to show indicate that seconds are represented to the nearest 1/1000 of a second, the format string would be "hh:mm:ss.sss". Note that this only indicates the number of decimals used to record the value, and not the precision of the measurement (see dateTimePrecision for that).

Date and time values are from an interval scale, but it is extremely complex because of the vagaries of the calendar (e.g., leap years, and leap seconds). The duration between date and time values in the future is not even deterministic because leap seconds are based on current measurements of the earth's orbit. Consequently, date and time values are unlike any other measured values. The format string for dateTime values allows one to accurately calculate the duration in SI second units between two measured dateTime values, assuming that the conversion software has a detailed knowledge of the Gregorian calendar.

Example(s):
YYYY-MM-DDThh:mm:ss
YYYY-MM-DD
YYYY
hh:mm:ss
hh:mm:ss.sss

A quantitative indication of the precision of a date or time measurement. The precision should be interpreted in the smallest units represented by the dateTime format. For example, if a dateTime value has a format of "hh:mm:ss.sss", then "seconds" are the smallest unit and the precision should be expressed in seconds. Thus, a precision value of "0.01" would mean that measurements were precise to the nearest hundredth of a second, even though the format string might indicate that values were written down with 3 decimal places.
Example(s):
0.1
0.01

See the description for the type: DateTimeDomainType

This element is to specify missing value in the data of the field. It is repeatable to allow for multiple different codes to be present in the attribute. Note that missing value codes should not be considered when determining if the observed values of an attribute all fall within the domain of the attribute (i.e., missing value codes should be parsed out of the data stream before examining the data for domain violations.

The code element is the missing value code itself. Each missing value code should be entered in a separate element instance. The value entered is what is placed into a data grid if the value is missing for some reason.
Example(s):
-9999
-1
N/A
MISSING

The codeExplanation element is an explanation of the meaning of the missing value code that was used, that is, the reason that there is a missing value. For example, an attribute might have a missing value code of '-99' to indicate that the data observation was not actually taken, and a code of '-88' to indicate that the data value was removed because of calibration errors.
Example(s):
Sensor down time.
Technician error.

The accuracy element represents the accuracy of the attribute. This information should describe any accuracy information that is known about the collection of this data attribute. The content model of this metadata is taken directly from FGDC FGDC-STD-001-1998 section 2 with the exception of processContact, sourceCitation, and timePeriodInformation which either user XMLSchema types or use predefined EML types for these purposes.

An explanation of the coverage of the attribute. This specifically indicates the spatial, temporal, and taxonomic coverage of the attribute in question when that coverage deviates from coverages expressed at a higher level (e.g., entity or dataset). Please see the eml-coverage module for complete documentation.

An explanation of the methods involved in the collection of this attribute. These specifically supplement or possibly override methods provided at a higher level such as entity or dataset. Please see the eml-methods module for complete documentation.

The attributeAccuracyReport element is an explanation of the accuracy of the observation recorded in this attribute. It will often include a description of the tests used to determine the accuracy of the observation. These reports are generally prepared for remote sensing or other measurement devices.

The quantitativeAttributeAccuracyAssessment element is composed of two parts, a value that represents the accuracy of the recorded observation an explanation of the tests used to determine the accuracy.

The attributeAccuracyValue element is an estimate of the accuracy of the identification of the entities and assignments of attribute values in the data set.

The attributeAccuracyExplanation element is the identification of the test that yielded the Attribute Accuracy Value.

This is the root element of the eml-attribute module. It is mainly used for testing, but can also be used for creating stand-alone eml-attribute modules where a list of attributes is needed.

Use the standardUnit element if the unit for this attribute has been defined in the Standard Unit Dictionary. The list of "standard" units includes the SI base units and many compound units based on SI, plus and some commonly used units which are not SI. The list is by no means exhaustive. If the unit you need is not part of this list, then the customUnit field should be used instead. Standard units have been described using STMML. See the documentation for the Type for more information.
Example(s):
meter
second
joule

The customUnit element is for units that are not part of the standard list provided with EML. The customUnit must correspond to an id in the document where its definition is provided using the STMML syntax. The customUnit definition will most likely be in the additionalMetadata section.
Example(s):
gramsPerOneThirdMeter

The enumeratedDomain element describes any code that is used as a value of an attribute. These codes can be defined here in the metadata as a list with definitions (preferred), can be referenced by pointing to an external citation or URL where the codes are defined, or can be referenced by pointing at an entity that contains the code value and code definition as two attributes. For example, data might have a variable named 'site' with values 'A', 'B', and 'C', and the enumeratedDomain would explain how to interpret those codes.

This element gives the value of a particular code and its definition. It is repeatable to allow for a list of codes to be provided.

The code element specifies a code value that can be used in the domain
Example(s):
1
HIGH
BEPA
24

The definition describes the code with which it is associated in enough detail for scientists to interpret the meaning of the coded values.
Example(s):
high density, above 10 per square meter

The source element is the name of the source from which this code and its associated definition are drawn. This is commonly used for identifying standard coding systems, like the FIPS standard for postal abbreviations for states in the US. In other cases, the coding may be the researcher's customized way of recording and classifying their data, and no external "source" would exist.
Example(s):
ISO country codes

The externalCodeSet element is a reference to an externally defined set of codes used in this attribute. This can either be a citation (using the eml-citation module) or a URL. Using an externally defined codeset (rather than a codeDefinition) means that interpretation of the data is dependent upon future users being able to obtain the code definitions, so care should be taken to only use highly standardized external code sets that will be available for many years. If at all possible, it is preferable to define the codes inline using the codeDefinition element.

The codesetName element is the name of an externally defined code set.
Example(s):
FIPS State Abbreviation Codes

The citation element is a citation for the code set reference

The codesetURL element is a URL for the code set reference.

The entityCodeList is a list of codes and their definitions in a data entity that is present in this dataset. The fields specify exactly which entity it is, and which attributes of that entity contain the codes, their definitions, and the order of the values.

The entityReference element is a reference to the id of the entity in which the code list has been defined. This entity must have been defined elsewhere in the metadata and have an id that matches the value of this element.

The valueAttributeReference element is a reference to the id of the attribute that contains the list of codes. This attribute must have been defined elsewhere in the metadata and have an id that matches the value of this element.

The definitionAttributeReference element is a reference to the id of the attribute that contains the definition of codes. This attribute must have been defined elsewhere in the metadata and have an id that matches the value of this element.

The orderAttributeReference element is a reference to the id of the attribute that contains the order of codes. The values in this attribute are integers indicating increasing values of the categories. This attribute must have been defined elsewhere in the metadata and have an id that matches the value of this element.

The textDomain element describes a free text domain for the attribute. By default, if a pattern is missing or empty, then any text is allowed. If a pattern is present, then it is interpreted as a regular expression constraining the allowable character sequences for the attribute. This domain type is most useful for describing extensive text domains that match a pattern but do not have a finite set of values. Another use is for describing the domain of textual fields like comments that allow any legal string value.
Example(s):
Typically, a text domain will have an empty pattern or one that constrains allowable values. For example, '[0-9]{3}-[0-9]{3}-[0-9]{4}' allows for only numeric digits in the pattern of a US phone number.

The element definition provides the text domain definition, that is, what kinds of text expressions are allowed for this attribute. If there is a pattern supplied, the definition element expresses the meaning of the pattern, For example, a particular pattern may be meant to represent phone numbers in the US phone system format. A definition element may also be used to extend an enumerated domain.
Example(s):
US telephone numbers in the format "(999) 888-7777"

The pattern element specifies a regular expression pattern that constrains the set of allowable values for the attribute. This is commonly used to define template patterns for data such as phone numbers where the attribute is text but the values are not drawn from an enumeration. If the pattern field is empty or missing, it defaults to '.*', which matches any string, including the empty string. Repeated pattern elements are combined using logical OR. The regular expression syntax is the same as that used in the XML Schema Datatypes Recommendation from the W3C.
Example(s):
'[0-9a-zA-Z]' matches simple alphanumeric strings and '(\d\d\d) \d\d\d-\d\d\d\d' represents telephone strings in the US of the form '(704) 876-1734'

The source element is the name of the source from which this text domain and its associated definition are drawn. This is commonly used for identifying standard coding systems, like the FIPS standard for postal abbreviations for states in the US. In other cases, the coding may be a researcher's custom way of recording and classifying their data, and no external "source" would exist.
Example(s):
ISO country codes

The bounds element in the BoundsGroup contains the minimum and maximum values of a numeric attribute. These are theoretical or permitted values (ie. prescriptive), and not necessarily the actual minimum and maximum observed in a given data set (descriptive). Either or both a minimum and maximum may be set, and each has an attribute "exclusive" to define how the value should be interpreted.

The minimum element specifies the minimum permitted value of a numeric attribute.

The maximum element specifies the maximum permitted value of a numeric attribute.

The bounds element in the BoundsDateGroup contains the minimum and maximum dates of a dateTime attribute. These are theoretical or permitted values (ie. prescriptive), and not necessarily the actual minimum and maximum observed in a given data set (descriptive). Either or both a minimum and maximum may be set, and each has an attribute "exclusive" to define how the value should be interpreted.

The minimum element specifies the minimum permitted value of a date attribute.

The maximum element specifies the maximum permitted value of a date attribute.

Type: res:IDType

Use: optional

Type: xs:string

Use: optional

Default value: http://www.w3.org/2001/XMLSchema-datatypes

The typeSystem attribute is the system used to define the storage types. This should be an identifier of a well known and published typing system. The default and recommended system is the XML Schema data type system. For details go to http://www.w3.org. If another system is used (such as Java or C++ types), typeSystem should be changed to match the system.
Example(s):
http://www.w3.org/2001/XMLSchema-datatypes
java
C
Oracle 8i

Type: res:IDType

Use: optional

Type: res:SystemType

Use: optional

Type: res:ScopeType

Use: optional

Default value: document

Type: xs:long

Use: optional

Ordinal scale measurements have a discrete list of values with a specific ordering of those values. This attributes specifies that order from low to high. For example, for LOW, MEDIUM, HIGH, the order attribute might be "LOW=1, MEDIUM=2 and HIGH=3".

Use: optional

Default value: yes

Derived from: xs:string (by xs:restriction)

Allowed values:

• yes
• no

Indicates whether the enumerated domain values are the only allowable values for the domain. In some exceedingly rare cases, users may wish to present a list of value codes in enumeratedDomain but not formally restrict the value space for the attribute to those values. If so, they can indicate this by setting the enforced attribute to the value no. Acceptable values are yes and no, and the default value is yes.

Type: res:IDType

Use: optional

Type: res:IDType

Use: optional

Type: res:IDType

Use: optional

Type: xs:boolean

Use: required

If exclusive is set to true, then the value specifies a lower bound not including the value itself. Setting exclusive to true is the equivalent of using a less-than or greater-than operator, while setting it to false is the same as using a less-than-or-equals or greater-than-or-equals operator. For example, if the minimum is "5" and exclusive is false, then all values must be greater than or equal to 5, but if exclusive is true than all values must be greater than 5 (not including 5.0 itself).

Type: xs:boolean

Use: required

If exclusive is set to true, then the value specifies a lower bound not including the value itself. Setting exclusive to true is the equivalent of using a less-than or greater-than operator, while setting it to false is the same as using a less-than-or-equals or greater-than-or-equals operator. For example, if the minimum is "5" and exclusive is false, then all values must be greater than or equal to 5, but if exclusive is true than all values must be greater than 5 (not including 5.0 itself).

Type: xs:boolean

Use: required

If exclusive is set to true, then the value specifies a lower bound not including the value itself. Setting exclusive to true is the equivalent of using a less-than or greater-than operator, while setting it to false is the same as using a less-than-or-equals or greater-than-or-equals operator. For example, if the minimum is "5" and exclusive is false, then all values must be greater than or equal to 5, but if exclusive is true than all values must be greater than 5 (not including 5.0 itself).

Type: xs:boolean

Use: required

If exclusive is set to true, then the value specifies a lower bound not including the value itself. Setting exclusive to true is the equivalent of using a less-than or greater-than operator, while setting it to false is the same as using a less-than-or-equals or greater-than-or-equals operator. For example, if the minimum is "5" and exclusive is false, then all values must be greater than or equal to 5, but if exclusive is true than all values must be greater than 5 (not including 5.0 itself).

This complexType defines the structure of the attributeList element. The content model is a choice between one or more attribute elements, and references. References links to an attribute list defined elsewhere.

Type definition for the content of an attribute (variable) that can be part of an entity.

This field identifies the unit of measurement for this attribute. It is a choice of either a standard unit, or a custom unit. If it is a custom unit, the definition of the unit must be provided in the document using the STMML syntax, and the name provided in the customUnit element must reference the id of its associated STMML definition precisely. For further information on STMML (http://www.xml-cml.org/stmml/) or see stmml.xsd which is included with the EML 2.0 distribution for details.

Derived from: xs:float (by xs:extension)

Precision indicates how close together or how repeatable measurements are. A precise measuring instrument will give very nearly the same result each time it is used. This means that someone interpreting the data should expect that if a measurement were repeated, most measured values would fall within the interval specified by the precision. The value of precision should be expressed in the same unit as the measurement. For example, for an attribute with unit "meter", a precision of "0.1" would be interpreted to mean that most repeat measurements would fall within an interval of 1/10th of a meter.
Example(s):
0.1
0.5
1

The non-numeric domain field describes the domain of the attribute being documented. It can describe two different types of domains: enumerated and text. Enumerated domains are lists of values that are explicitly provided as legitimate values. Only values from that list should occur in the attribute. They are often used for response codes such as "HIGH" and "LOW". Text domains are used for attributes that allow more free-form text fields, but still permit some specification of the value-space through pattern matching. A text domain is usually used for comment and notes attributes, and other character attributes that don't have a precise set of constrained values. This is an important field for post processing and error checking of the dataset. It represents a formal specification of the value space for the attribute, and so there should never be a value for the attribute that falls outside of the set of values prescribed by the domain.

The numericDomain element specifies the minimum and maximum values of a numeric attribute. These are theoretical or permitted values (ie. prescriptive), and not necessarily the actual minimum and maximum observed in a given data set (descriptive). The information in numericDomain and in precision together constitute sufficient information to decide upon an appropriate system specific data type for representing a particular attribute. For example, an attribute with a numeric domain from 0-50,000 and a precision of 1 could be represented in the C language using a 'long' value, but if the precision is changed to '0.5' then a 'float' type would be needed.

The DateTimeDomain specifies the minimum and maximum values of a dateTime attribute. These are theoretical or permitted values (ie. prescriptive), and not necessarily the actual minimum and maximum observed in a given data set (descriptive). The domain expressions should be in the same dateTime format as is used in the "formatString" description for the attribute. For example, if the format string is "YYYY-MM-DD", then a valid minimum in the domain would be "2001-05-29". The "bounds" element is optional, and if it is missing then any legitimate value from the Gregorian calendar system is allowed in the attribute as long as its representation matches its corresponding formatString.

Derived from: xs:string (by xs:restriction)

Allowed values:

• natural
• whole
• integer
• real

This is the enumeration for the allowed values of the element numberType.

The bounds element contains the minimum and maximum values of a numeric attribute. These are theoretical or permitted values (ie. prescriptive), and not necessarily the actual minimum and maximum observed in a given data set (descriptive).

The BoundsDateGroup specifies the minimum and maximum dates allowed for a dateTime attribute. These are theoretical or permitted values (ie. prescriptive), and not necessarily the actual minimum and maximum observed in a given data set (descriptive). The domain expressions should be in the same dateTime format as is used in the attribute's "formatString". For example, if the format string is "YYYY-MM-DD", then a valid minimum in the domain would be "2001-05-29". The "bounds" element is optional, and if it is missing then any legitimate value from the Gregorian calendar system is allowed in the attribute as long as its representation matches its corresponding formatString.