Difference between revisions of "Date Documentation"

From Earth Science Information Partners (ESIP)
m (Scgordon moved page Dates to Date Documentation)
Line 1: Line 1:
 +
=Overview=
 +
:<big>I need to document different types of dates.</big>
 +
=Implementation=
 +
==Content Standard for Digital Geospatial Metadata (CSDGM)==
 +
===Structure===
 +
===Usage===
 +
==Directory Interchange Format (DIF)==
 +
===Structure===
 +
===Usage===
 +
==EOS Clearinghouse (ECHO)==
 +
===Structure===
 +
===Usage===
 +
==International Organization for Standardization 19115 (ISO19115)==
 +
There are many dates included in the ISO Metadata Standards and they have several different types - each with its own characteristics. This page has information about valid formats for those dates.  Ron Lake's blog includes a helpful [[http://www.galdosinc.com/archives/151 description]] of time in GML.
 +
===Structure===
 +
===Usage===
 +
''' gco:Date Type
 +
 +
----
 +
 +
 Date: gives values for year, month and day. Character encoding of a date is a string which shall follow the format for date specified by [[http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]]. A full date is formatted as YYYYMMDD or YYYY-MM-DD. This type is used in the following fields:
 +
 +
* MI_Metadata.dateStamp - The ISO definition of this field is "date that the metadata was created". Common usage seems to be evolving towards "date that the metadata was created or updated" because it seems reasonable that, once the metadata have been updated, the date of that update is more interesting than the original creation date. Also, the update actually creates the current metadata, so this usage seems consistent with the ISO definition.  Note: ISO 19115-1 replaces the datestamp/Date field with the dateinfo/CI_Date object, which enables the type of date to be specified.  ISO 19115-1 expands the date type codelist from 3 values to 16.
 +
* MD_MaintenanceInformation.dateOfNextUpdate
 +
* CI_Citation.editionDate - The ISO edition field is synonymous with the concept of version, so this is the release date for the version of the resource being cited.
 +
''' gco:DateTime Type
 +
 +
----
 +
 +
 DateTime: combination of a date and a time type (given by an hour, minute and second). Character encoding of a DateTime shall follow [[http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]]. Combined dates and times should be formatted as YYYYMMDDThh:mm:ss, YYYYMMDDThhmmss, or YYYY-MM-DDThh:mm:ss. These representations include no TimeZone indicator, so they are assumed to be local time. YYYYMMDDThh:[[http://mmssZ mm:ssZ]] would indicate universal time.
 +
 +
* MD_Usage.usageDateTime
 +
* DQ_Element.dateTime
 +
* LI_ProcessStep.dateTime
 +
* MD_StandardOrderProcess.plannedAvailableDateTime
 +
<pre style="margin-left:20px; border:solid; border-color:#3C78B5; border-width:1px; font-size:1.4em; background-color:#fff">
 +
<gmd:dateTime>
 +
  <gco:DateTime>2001-01-01T00:00:00</gco:DateTime>
 +
</gmd:dateTime>
 +
 +
</pre>
 +
 +
Note: This element was incorrectly defined in the ISO 19139 nschema as an [[http://xsdateTime xs:dateTime]]. That type does not allow all of the ISO 8601 options. Specifically, it does not allow the specification of a time range. It will likely be deprecated in the revision of the standard and replaced with stepDateTime.
 +
 +
''' gmd:CI_Date Type
 +
 +
----
 +
 +
This type is used only in the CI_Citation and is the only date type that includes a code from the CI_DateTypeCode codelist. Valid values from the CI_DateTypeCode CodeList are: creation (001), publication (002), and revision (003).  Note: ISO 19115-1 adds an additional 13 date type code list values to the code list.  In figure, see values highlighted in red.
 +
 +
 
 +
 +
<pre style="margin-left:20px; border:solid; border-color:#3C78B5; border-width:1px; font-size:1.4em; background-color:#fff">
 +
<gmd:CI_Date>
 +
  <gmd:date>
 +
    <gco:Date>2000-01-01</gco:Date>
 +
  </gmd:date>
 +
  <gmd:dateType>
 +
                <gmd:CI_DateTypeCode
 +
                  codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode"
 +
                  codeListValue="creation">creation</gmd:CI_DateTypeCode>
 +
              </gmd:dateType>
 +
</gmd:CI_Date> 
 +
</pre>
 +
 +
~~ATTACHED_IMAGE~~DateTypeCodes.PNG
 +
''' On-Going Datasets
 +
 +
----
 +
 +
 Many datasets are collected continuously through time. In these cases, a clear publication date does not exist. This situation can be indicated by a combination of "inapplicable" for the citation date, a status code = onGoing, and an endPosition with indeterminatePosition=now:
 +
 +
<pre style="margin-left:20px; border:solid; border-color:#3C78B5; border-width:1px; font-size:1.4em; background-color:#fff">
 +
<gmd:date>
 +
  <gmd:CI_Date>
 +
    <gmd:date gco:nilReason="inapplicable"/>
 +
    <gmd:dateType>
 +
      <gmd:CI_DateTypeCode codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode"
 +
        codeListValue="publication">publication</gmd:CI_DateTypeCode>
 +
    </gmd:dateType>
 +
  </gmd:CI_Date>
 +
</gmd:date>
 +
...
 +
<gmd:status>
 +
  <gmd:MD_ProgressCode codeListValue="onGoing" codeList="http://www.isotc211.org/2005/resources
 +
    /codeList.xml#MD_ProgressCode">onGoing</gmd:MD_ProgressCode>
 +
</gmd:status>
 +
...
 +
<gmd:temporalElement>
 +
  <gmd:EX_TemporalExtent id="boundingTemporalExtent">
 +
    <gmd:extent>
 +
      <gml:TimePeriod gml:id="d1e50">
 +
        <gml:beginPosition>2003-01-18T00:23:00.000Z</gml:beginPosition>
 +
        <gml:endPosition indeterminatePosition="now"/>
 +
      </gml:TimePeriod>
 +
    </gmd:extent>
 +
  </gmd:EX_TemporalExtent>
 +
</gmd:temporalElement>
 +
 +
</pre>
 +
 +
''' Relative Times
 +
 +
----
  
I need to document different types of dates.
+
 In some situations it is necessary to express a time in terms of a fixed period before the present. For example, on-going data processing systems might use observation sets and products from the previous day in the creation of a product for today. In these cases the duration and the end of the time period are known, so the XML looks like:
  
There are many dates included in the ISO Metadata Standards and they have several different types - each with its own characteristics. This page has information about valid formats for those dates.  Ron Lake's blog includes a helpful [[http://www.galdosinc.com/archives/151 description]] of time in GML.
+
<pre style="margin-left:20px; border:solid; border-color:#3C78B5; border-width:1px; font-size:1.4em; background-color:#fff">
 +
<gmd:temporalElement>
 +
  <gmd:EX_TemporalExtent>
 +
    <gmd:extent>
 +
      <gml:TimePeriod gml:id="id">
 +
        <b><gml:duration>P1D</gml:duration></b>
 +
        <gml:endPosition indeterminatePosition="now"/>
 +
      </gml:TimePeriod>
 +
    </gmd:extent>
 +
  </gmd:EX_TemporalExtent>
 +
</gmd:temporalElement>
 +
 
 +
</pre>
 +
 
 +
See [[http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]] for information on durations.
 +
 
 +
''' Uncertain Times
 +
 
 +
----
 +
 
 +
 The GML elements for describing time positions (beginPosition and endPosition) include the indeterminatePosition attribute that can have values of before, after, now, and unknown. This attribute can be used with a time value to express uncertain times. For example, a dataset that began sometime before 1980 and continues to the present could be described as:
 +
 
 +
<pre style="margin-left:20px; border:solid; border-color:#3C78B5; border-width:1px; font-size:1.4em; background-color:#fff">
 +
<gmd:extent>
 +
  <gml:TimePeriod gml:id="id">
 +
      <gml:beginPosition indeterminatePosition="before">1980</gml:beginPosition>
 +
      <gml:endPosition indeterminatePosition="now"/>
 +
  </gml:TimePeriod>
 +
</gmd:extent>
 +
</pre>
 +
=Crosswalks=
 +
=Notes=
  
== gco:Date Type ==
+
''' gco:Date Type  
  
 
----
 
----
Line 13: Line 148:
 
* MD_MaintenanceInformation.dateOfNextUpdate
 
* MD_MaintenanceInformation.dateOfNextUpdate
 
* CI_Citation.editionDate - The ISO edition field is synonymous with the concept of version, so this is the release date for the version of the resource being cited.
 
* CI_Citation.editionDate - The ISO edition field is synonymous with the concept of version, so this is the release date for the version of the resource being cited.
== gco:DateTime Type ==
+
''' gco:DateTime Type  
  
 
----
 
----
Line 32: Line 167:
 
Note: This element was incorrectly defined in the ISO 19139 nschema as an [[http://xsdateTime xs:dateTime]]. That type does not allow all of the ISO 8601 options. Specifically, it does not allow the specification of a time range. It will likely be deprecated in the revision of the standard and replaced with stepDateTime.
 
Note: This element was incorrectly defined in the ISO 19139 nschema as an [[http://xsdateTime xs:dateTime]]. That type does not allow all of the ISO 8601 options. Specifically, it does not allow the specification of a time range. It will likely be deprecated in the revision of the standard and replaced with stepDateTime.
  
== gmd:CI_Date Type ==
+
''' gmd:CI_Date Type  
  
 
----
 
----
Line 54: Line 189:
  
 
~~ATTACHED_IMAGE~~DateTypeCodes.PNG
 
~~ATTACHED_IMAGE~~DateTypeCodes.PNG
== On-Going Datasets ==
+
''' On-Going Datasets  
  
 
----
 
----
Line 89: Line 224:
 
</pre>
 
</pre>
  
== Relative Times ==
+
''' Relative Times  
  
 
----
 
----
Line 111: Line 246:
 
See [[http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]] for information on durations.
 
See [[http://en.wikipedia.org/wiki/ISO_8601 ISO 8601]] for information on durations.
  
== Uncertain Times ==
+
''' Uncertain Times  
  
 
----
 
----

Revision as of 14:41, September 18, 2015

Overview

I need to document different types of dates.

Implementation

Content Standard for Digital Geospatial Metadata (CSDGM)

Structure

Usage

Directory Interchange Format (DIF)

Structure

Usage

EOS Clearinghouse (ECHO)

Structure

Usage

International Organization for Standardization 19115 (ISO19115)

There are many dates included in the ISO Metadata Standards and they have several different types - each with its own characteristics. This page has information about valid formats for those dates.  Ron Lake's blog includes a helpful [description] of time in GML.

Structure

Usage

gco:Date Type


 Date: gives values for year, month and day. Character encoding of a date is a string which shall follow the format for date specified by [ISO 8601]. A full date is formatted as YYYYMMDD or YYYY-MM-DD. This type is used in the following fields:

  • MI_Metadata.dateStamp - The ISO definition of this field is "date that the metadata was created". Common usage seems to be evolving towards "date that the metadata was created or updated" because it seems reasonable that, once the metadata have been updated, the date of that update is more interesting than the original creation date. Also, the update actually creates the current metadata, so this usage seems consistent with the ISO definition.  Note: ISO 19115-1 replaces the datestamp/Date field with the dateinfo/CI_Date object, which enables the type of date to be specified.  ISO 19115-1 expands the date type codelist from 3 values to 16.
  • MD_MaintenanceInformation.dateOfNextUpdate
  • CI_Citation.editionDate - The ISO edition field is synonymous with the concept of version, so this is the release date for the version of the resource being cited.

gco:DateTime Type


 DateTime: combination of a date and a time type (given by an hour, minute and second). Character encoding of a DateTime shall follow [ISO 8601]. Combined dates and times should be formatted as YYYYMMDDThh:mm:ss, YYYYMMDDThhmmss, or YYYY-MM-DDThh:mm:ss. These representations include no TimeZone indicator, so they are assumed to be local time. YYYYMMDDThh:[mm:ssZ] would indicate universal time.

  • MD_Usage.usageDateTime
  • DQ_Element.dateTime
  • LI_ProcessStep.dateTime
  • MD_StandardOrderProcess.plannedAvailableDateTime
<gmd:dateTime>
  <gco:DateTime>2001-01-01T00:00:00</gco:DateTime>
</gmd:dateTime>

Note: This element was incorrectly defined in the ISO 19139 nschema as an [xs:dateTime]. That type does not allow all of the ISO 8601 options. Specifically, it does not allow the specification of a time range. It will likely be deprecated in the revision of the standard and replaced with stepDateTime.

gmd:CI_Date Type


This type is used only in the CI_Citation and is the only date type that includes a code from the CI_DateTypeCode codelist. Valid values from the CI_DateTypeCode CodeList are: creation (001), publication (002), and revision (003).  Note: ISO 19115-1 adds an additional 13 date type code list values to the code list.  In figure, see values highlighted in red.

 

<gmd:CI_Date>
  <gmd:date>
    <gco:Date>2000-01-01</gco:Date>
  </gmd:date>
  <gmd:dateType>
                <gmd:CI_DateTypeCode
                  codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode"
                  codeListValue="creation">creation</gmd:CI_DateTypeCode>
              </gmd:dateType>
</gmd:CI_Date>  

~~ATTACHED_IMAGE~~DateTypeCodes.PNG On-Going Datasets


 Many datasets are collected continuously through time. In these cases, a clear publication date does not exist. This situation can be indicated by a combination of "inapplicable" for the citation date, a status code = onGoing, and an endPosition with indeterminatePosition=now:

<gmd:date>
  <gmd:CI_Date>
    <gmd:date gco:nilReason="inapplicable"/>
    <gmd:dateType>
      <gmd:CI_DateTypeCode codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode"
        codeListValue="publication">publication</gmd:CI_DateTypeCode>
    </gmd:dateType>
  </gmd:CI_Date>
</gmd:date>
...
<gmd:status>
  <gmd:MD_ProgressCode codeListValue="onGoing" codeList="http://www.isotc211.org/2005/resources
    /codeList.xml#MD_ProgressCode">onGoing</gmd:MD_ProgressCode>
</gmd:status>
...
<gmd:temporalElement>
  <gmd:EX_TemporalExtent id="boundingTemporalExtent">
    <gmd:extent>
      <gml:TimePeriod gml:id="d1e50">
        <gml:beginPosition>2003-01-18T00:23:00.000Z</gml:beginPosition>
        <gml:endPosition indeterminatePosition="now"/>
      </gml:TimePeriod>
    </gmd:extent>
  </gmd:EX_TemporalExtent>
</gmd:temporalElement>

Relative Times


 In some situations it is necessary to express a time in terms of a fixed period before the present. For example, on-going data processing systems might use observation sets and products from the previous day in the creation of a product for today. In these cases the duration and the end of the time period are known, so the XML looks like:

<gmd:temporalElement>
  <gmd:EX_TemporalExtent>
    <gmd:extent>
      <gml:TimePeriod gml:id="id">
        <b><gml:duration>P1D</gml:duration></b>
        <gml:endPosition indeterminatePosition="now"/>
      </gml:TimePeriod>
    </gmd:extent>
  </gmd:EX_TemporalExtent>
</gmd:temporalElement>

See [ISO 8601] for information on durations.

Uncertain Times


 The GML elements for describing time positions (beginPosition and endPosition) include the indeterminatePosition attribute that can have values of before, after, now, and unknown. This attribute can be used with a time value to express uncertain times. For example, a dataset that began sometime before 1980 and continues to the present could be described as:

<gmd:extent>
   <gml:TimePeriod gml:id="id">
      <gml:beginPosition indeterminatePosition="before">1980</gml:beginPosition>
      <gml:endPosition indeterminatePosition="now"/>
   </gml:TimePeriod>
</gmd:extent>

Crosswalks

Notes

gco:Date Type


 Date: gives values for year, month and day. Character encoding of a date is a string which shall follow the format for date specified by [ISO 8601]. A full date is formatted as YYYYMMDD or YYYY-MM-DD. This type is used in the following fields:

  • MI_Metadata.dateStamp - The ISO definition of this field is "date that the metadata was created". Common usage seems to be evolving towards "date that the metadata was created or updated" because it seems reasonable that, once the metadata have been updated, the date of that update is more interesting than the original creation date. Also, the update actually creates the current metadata, so this usage seems consistent with the ISO definition.  Note: ISO 19115-1 replaces the datestamp/Date field with the dateinfo/CI_Date object, which enables the type of date to be specified.  ISO 19115-1 expands the date type codelist from 3 values to 16.
  • MD_MaintenanceInformation.dateOfNextUpdate
  • CI_Citation.editionDate - The ISO edition field is synonymous with the concept of version, so this is the release date for the version of the resource being cited.

gco:DateTime Type


 DateTime: combination of a date and a time type (given by an hour, minute and second). Character encoding of a DateTime shall follow [ISO 8601]. Combined dates and times should be formatted as YYYYMMDDThh:mm:ss, YYYYMMDDThhmmss, or YYYY-MM-DDThh:mm:ss. These representations include no TimeZone indicator, so they are assumed to be local time. YYYYMMDDThh:[mm:ssZ] would indicate universal time.

  • MD_Usage.usageDateTime
  • DQ_Element.dateTime
  • LI_ProcessStep.dateTime
  • MD_StandardOrderProcess.plannedAvailableDateTime
<gmd:dateTime>
  <gco:DateTime>2001-01-01T00:00:00</gco:DateTime>
</gmd:dateTime>

Note: This element was incorrectly defined in the ISO 19139 nschema as an [xs:dateTime]. That type does not allow all of the ISO 8601 options. Specifically, it does not allow the specification of a time range. It will likely be deprecated in the revision of the standard and replaced with stepDateTime.

gmd:CI_Date Type


This type is used only in the CI_Citation and is the only date type that includes a code from the CI_DateTypeCode codelist. Valid values from the CI_DateTypeCode CodeList are: creation (001), publication (002), and revision (003).  Note: ISO 19115-1 adds an additional 13 date type code list values to the code list.  In figure, see values highlighted in red.

 

<gmd:CI_Date>
  <gmd:date>
    <gco:Date>2000-01-01</gco:Date>
  </gmd:date>
  <gmd:dateType>
                <gmd:CI_DateTypeCode
                  codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode"
                  codeListValue="creation">creation</gmd:CI_DateTypeCode>
              </gmd:dateType>
</gmd:CI_Date>  

~~ATTACHED_IMAGE~~DateTypeCodes.PNG On-Going Datasets


 Many datasets are collected continuously through time. In these cases, a clear publication date does not exist. This situation can be indicated by a combination of "inapplicable" for the citation date, a status code = onGoing, and an endPosition with indeterminatePosition=now:

<gmd:date>
  <gmd:CI_Date>
    <gmd:date gco:nilReason="inapplicable"/>
    <gmd:dateType>
      <gmd:CI_DateTypeCode codeList="http://www.isotc211.org/2005/resources/Codelist/gmxCodelists.xml#CI_DateTypeCode"
        codeListValue="publication">publication</gmd:CI_DateTypeCode>
    </gmd:dateType>
  </gmd:CI_Date>
</gmd:date>
...
<gmd:status>
  <gmd:MD_ProgressCode codeListValue="onGoing" codeList="http://www.isotc211.org/2005/resources
    /codeList.xml#MD_ProgressCode">onGoing</gmd:MD_ProgressCode>
</gmd:status>
...
<gmd:temporalElement>
  <gmd:EX_TemporalExtent id="boundingTemporalExtent">
    <gmd:extent>
      <gml:TimePeriod gml:id="d1e50">
        <gml:beginPosition>2003-01-18T00:23:00.000Z</gml:beginPosition>
        <gml:endPosition indeterminatePosition="now"/>
      </gml:TimePeriod>
    </gmd:extent>
  </gmd:EX_TemporalExtent>
</gmd:temporalElement>

Relative Times


 In some situations it is necessary to express a time in terms of a fixed period before the present. For example, on-going data processing systems might use observation sets and products from the previous day in the creation of a product for today. In these cases the duration and the end of the time period are known, so the XML looks like:

<gmd:temporalElement>
  <gmd:EX_TemporalExtent>
    <gmd:extent>
      <gml:TimePeriod gml:id="id">
        <b><gml:duration>P1D</gml:duration></b>
        <gml:endPosition indeterminatePosition="now"/>
      </gml:TimePeriod>
    </gmd:extent>
  </gmd:EX_TemporalExtent>
</gmd:temporalElement>

See [ISO 8601] for information on durations.

Uncertain Times


 The GML elements for describing time positions (beginPosition and endPosition) include the indeterminatePosition attribute that can have values of before, after, now, and unknown. This attribute can be used with a time value to express uncertain times. For example, a dataset that began sometime before 1980 and continues to the present could be described as:

<gmd:extent>
   <gml:TimePeriod gml:id="id">
      <gml:beginPosition indeterminatePosition="before">1980</gml:beginPosition>
      <gml:endPosition indeterminatePosition="now"/>
   </gml:TimePeriod>
</gmd:extent>