'$RCSfile: eml-attribute.xsd,v $'
       Copyright: 1997-2002 Regents of the University of California,
                            University of New Mexico, and
                            Arizona State University
        Sponsors: National Center for Ecological Analysis and Synthesis and
                  Partnership for Interdisciplinary Studies of Coastal Oceans,
                     University of California Santa Barbara
                  Long-Term Ecological Research Network Office,
                     University of New Mexico
                  Center for Environmental Studies, Arizona State University
   Other funding: National Science Foundation (see README for details)
                  The David and Lucile Packard Foundation
     For Details: http://knb.ecoinformatics.org/

        '$Author: obrien $'
          '$Date: 2009-02-25 23:51:54 $'
      '$Revision: 1.123 $'

    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

moduleName: eml-attribute

moduleDescription: 
          
            
            The eml-attribute module - Attribute level information within
            dataset entities
          
          
        

recommendedUsage: any dataset that uses dataTable, spatialRaster,
        spatialVector, storedProcedure, view or otherEntity or in a custom
        module where one wants to document an attribute
        (variable)

standAlone: yes

tooltip: Attribute name

summary: The name of the attribute
              

description: 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: spden

example: spatialden

example: site

example: spcode

tooltip: Attribute label

summary: A label for displaying an attribute name.
              

description: 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: Species Density

example: Spatial Density

example: Name of Site

example: Species Code

tooltip: Attribute definition

summary: Precise definition of the attribute
              

description: 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: "spden" is the number of individuals of all
              macro invertebrate species found in the plot

tooltip: Storage Type

summary: Storage type hint for this field

description: 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: integer

example: int

tooltip: Measurement Scale

summary: The measurement scale for the attribute.
              

description: 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: 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.

example: 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.

example: 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).
              

example: 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).

tooltip: Nominal scale

summary: Characteristics used to define nominal
                    (categorical) scale attributes

description: 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.

tooltip: Enumerated domain

summary: Description of any coded values associated
              with the attribute.

description: 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.

tooltip: Code Definition

summary: A codes and its definition

description: 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.

tooltip: Code

summary: Code value allowed in the
                          domain

description: The code element specifies a
                          code value that can be used in the domain
                          

example: 1

example: HIGH

example: BEPA

example: 24

tooltip: Code definition

summary: Definition of the associated code
                          

description: The definition describes the
                          code with which it is associated in enough
                          detail for scientists to interpret the meaning
                          of the coded values.

example: high density, above 10 per square
                          meter

tooltip: Source of code

summary: The name of the source for this
                          code and its definition

description: 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: ISO country codes

tooltip: External code set

summary: A reference to an externally defined set
                    of codes used in this attribute

description: 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.

tooltip: Code Set Name

summary: The name of an externally defined
                          code set

description: The codesetName element is the
                          name of an externally defined code
                          set.

example: FIPS State Abbreviation
                          Codes

tooltip: Citation

summary: A citation for the code set
                            reference

description: The citation element is a
                            citation for the code set
                            reference

tooltip: Code set URL

summary: A URL for the code set
                            reference

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

tooltip: Entity Code List

summary: A code list that is defined in a data
                    table

description: 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.

tooltip: Entity Reference

summary: A reference to the id of the
                          entity in which the code list has been
                          defined

description: 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.

tooltip: Value Attribute
                          Reference

summary: A reference to the id of the
                          attribute that contains the list of
                          codes

description: 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.

tooltip: Definition Attribute
                          Reference

summary: A reference to the id of the
                          attribute that contains the definition of
                          codes

description: 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.

tooltip: Order Attribute
                          Reference

summary: A reference to the id of the
                          attribute that contains the order of
                          codes

description: 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.

tooltip: Text domain

summary: Description of a free-text domain pattern for
              the attribute

description: 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: 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.

tooltip: Text domain definition

summary: Definition of what this text domain
                    represents

description: 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: US telephone numbers in the format
                    "(999) 888-7777"

tooltip: Text pattern

summary: Regular expression pattern constraining
                    the attribute

description: 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: '[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'

tooltip: Source of text domain

summary: The name of the source for this text
                    domain.

description: 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: ISO country codes

tooltip: Ordinal scale

summary: Characteristics used to define ordinal
                    (ordered) scale attributes

description: 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.

tooltip: Interval scale

summary: Characteristics used to define interval
                    scale attributes

description: 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).

tooltip: Standard Unit

summary: The name of a standard unit used to make this
            measurement

description: 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: meter

example: second

example: joule

tooltip: Custom Unit

summary: The name of a custom unit used to make this
            measurement.

description: 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: gramsPerOneThirdMeter

tooltip: number type

tooltip: Bounds

summary: Elements for specifying allowed
        values range.

description: 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.

tooltip: Minimum numeric bound

summary: Minimum numeric bound of
                attribute

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

tooltip: Maximum numeric bound

summary: Maximum numeric bound of
                attribute

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

tooltip: Ratio scale

summary: Characteristics used to define ratio
                    scale attributes

description: 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).

tooltip: Date/Time scale

summary: Characteristics used to define date and
                    time attributes

description: 
                      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 they 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.

tooltip: Date/Time Format

summary: A format string that describes the
                          format for a date-time value from the Gregorian
                          calendar.

description: 
                            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 Datetime   YYYY-MM-DDThh:mm:ss-hh 2002-10-14T09:13:45-07                  
                  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-MMM-DD            2002-OCT-14
                  Non-standard   YYYYMMMDD              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 date components, their order, and the separators;
              e.g., date parts are upper case, and time parts are lower case.
              If no UTC relation information is given, the time is assumed to be in local
              time. Assuming local time is ambiguous even when communicating within a
              single time zone, given variations in Daylight Saving Time.
              Best practice is to follow the ISO 8601 format precisely and accurately.
                            
                            
              In particular, please note that these are all non-standard
                according to ISO:
              
                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,
                placing any of the components out of descending order
              
                            
                            

              However, we recognize that existing data contain
              non-standard dates, and existing equipment (e.g., sensors) may
              still be producing non-standard dates.
              Further, data parsers often apply individual interpretations. E.g., Java
              interprets HH on a 24-hr clock and hh on a 12-hr clock, and MM as a
              padded integer for month but MMM as a 3-letter abbreviation.
              Consequently, the formatting string can contain characters as needed
               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: YYYY-MM-DDThh:mm:ss

example: YYYY-MM-DD

example: YYYY

example: hh:mm:ss

example: hh:mm:ss.sss

tooltip: DateTime Precision

summary: An indication of the precision of a
                          date or time value

description: 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: 0.1

example: 0.01

tooltip: DateTime Domain

summary: See the summary for the type: DateTimeDomainType

description: See the description for the type: DateTimeDomainType

tooltip: Bounds

summary: Elements for specifying allowed
        date range.

description: 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.

tooltip: Minimum date bound

summary: Minimum date bound of
                attribute

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

tooltip: Maximum date bound

summary: Maximum date bound of
                attribute

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