From bf8ee8cc1697c15348ff6a4cf56aa865188769f6 Mon Sep 17 00:00:00 2001 From: Chris Holmes Date: Mon, 18 May 2020 10:37:52 -0700 Subject: [PATCH] added best practice for datetime - #801 --- best-practices.md | 18 ++++++++++++++++++ item-spec/item-spec.md | 3 ++- 2 files changed, 20 insertions(+), 1 deletion(-) diff --git a/best-practices.md b/best-practices.md index e0b1191b8..c82285db0 100644 --- a/best-practices.md +++ b/best-practices.md @@ -4,6 +4,7 @@ * [Field and ID formatting](#field-and-id-formatting) * [Field selection and Metadata Linking](#field-selection-and-metadata-linking) +* [Datetime selection](#datetime-selection) * [Representing Vector Layers in STAC](#representing-vector-layers-in-stac) * [Common Use Cases of Additional Fields for Assets](#common-use-cases-of-additional-fields-for-assets) * [Static and Dynamic Catalogs](#static-and-dynamic-catalogs) @@ -49,6 +50,23 @@ catalogs (hundreds of millions of records), every additional field that is index providers are advised to just put the fields to be searched in STAC, so [STAC API](https://github.com/radiantearth/stac-api-spec) providers don't have bloated indices that no one actually uses. +## Datetime selection + +The `datetime` field in a STAC Item's properties is one of the most important parts of a STAC Item, providing the T (temporal) of +STAC. And it can also be one of the most confusing, especially for data that covers a range of times. For many types of data it +is straightforward - it is the capture or acquisition time. But often data is processed from a range of captures - drones usually +gather a set of images over an hour and put them into a single image, mosaics combine data from several months, and data cubes +represent slices of data over a range of time. For all these cases the recommended path is to use `start_datetime` and +`end_datetime` fields from [common metadata](item-spec/common-metadata.md#date-and-time-range). The specification does allow one to set the +`datetime` field to `null`, but it is strongly recommended to populate the single `datetime` field, as that is what many clients +will search on. If it is at all possible to pick a nominal or representative datetime then that should be used. + +Extensions that describe particular types of data can and should define their `datetime` field to be more specific. For example +a MODIS 8 day composite image can define the `datetime` to be the nominal date halfway between the two ranges. Another data type +might choose to have `datetime` be the start. The key is to put in a date and time that will be useful for search, as that is +the focus of STAC. If `datetime` is set to `null` then it is strongly recommended to use it in conjunction with a content extension +that explains why it should not be set for that type of data. + ## Representing Vector Layers in STAC Many implementors are tempted to try to use STAC for 'everything', using it as a universal catalog of all their 'stuff'. diff --git a/item-spec/item-spec.md b/item-spec/item-spec.md index f4a7da3b3..77db51d64 100644 --- a/item-spec/item-spec.md +++ b/item-spec/item-spec.md @@ -79,7 +79,8 @@ In this case it is **required** to specify a temporal interval with the fields ` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range). For example, if your data is a time-series that covers 100 years, it's not very meaningful to set the datetime to a single timestamp as it would not be found in most searches that searches for a decade of data in that -period although the item actually covers the decade. +period although the item actually covers the decade. See [datetime selection](../best-practices.md#datetime-selection) +in the best practices document for more information. #### Additional Fields