Make datetime nullable for stac items for which a nominal datatime ma…

…kes no sense #792

CHANGELOG.md

@@ -23,6 +23,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - Moved item recommendations to best practices, and added a bit more in item spec about 'search'
 - Moved `eo:gsd` from `eo` extension to core `gsd` field in Item common metadata
 - `asset` extension renamed to `item-assets` and renamed `assets` field in Collections to `item_assets`
+- `datetime` allows `null` as value, but requires `start_datetime` and `end_datetime` then
 
 ### Fixed
 

item-spec/common-metadata.md

@@ -29,17 +29,21 @@ Descriptive fields to give a basic overview of a STAC Item.
 
 ## Date and Time
 
+- [JSON Schema](json-schema/datetime.json)
+
 Fields to provide additional temporal information such as ranges with a start and an end datetime stamp.
 
-### Date and Time Range
+| Field Name | Type         | Description |
+| ---------- | ------------ | ----------- |
+| datetime   | string\|null | See the [Item Spec Fields](item-spec.md#properties-object) for more information. |
 
-- [JSON Schema](json-schema/datetimerange.json)
+### Date and Time Range
 
 While a STAC item can have a nominal datetime describing the capture, these properties allow an item to have a range
 of capture datetimes. An example of this is the [MODIS 16 day vegetation index product.](https://lpdaac.usgs.gov/products/mod13q1v006/).
 The datetime property in a STAC item and these fields are not mutually exclusive.
 
-**Important:** Using one of the fields REQUIRES to include the other field as well to enable a user to search STAC records by the provided times. So if you use `start_datetime` you need to add `end_datetime` and vice-versa.
+**Important:** Using one of the fields REQUIRES to include the other field as well to enable a user to search STAC records by the provided times. So if you use `start_datetime` you need to add `end_datetime` and vice-versa. Both fields are also REQUIRED if the `datetime` field is set to `null`.
 
 | Field Name     | Type   | Description                                                  |
 | -------------- | ------ | ------------------------------------------------------------ |

item-spec/item-spec.md

@@ -64,16 +64,22 @@ Additional metadata fields can be added to the GeoJSON Object Properties. The on
 is `datetime` but it is recommended to add more fields, see [Additional Fields](#additional-fields) 
 resources below.
 
-| Field Name | Type   | Description                                                  |
-| ---------- | ------ | ------------------------------------------------------------ |
-| datetime   | string | **REQUIRED.** The searchable date and time of the assets, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). |
+| Field Name | Type         | Description                                                  |
+| ---------- | ------------ | ------------------------------------------------------------ |
+| datetime   | string\|null | **REQUIRED.** The searchable date and time of the assets, in UTC. It is formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6). `null` is allowed, but requires `start_datetime` and `end_datetime` from [common metadata](common-metadata.md#date-and-time-range) to be set. |
 
 **datetime** is likely the acquisition (in the case of single camera type captures) or the 'nominal'
 or representative time in the case of assets that are combined together. Though time can be a
 complex thing to capture, for this purpose keep in mind the STAC spec is primarily searching for
 data, so use whatever single date and time is most useful for a user to search for. STAC content
 extensions may further specify the meaning of the main `datetime` field, and many will also add more
 datetime fields.
+If there's clearly no meaningful single 'nominal' time, it is allowed to use `null` instead.
+In this case it is **required** to specify a temporal interval with the fields `start_datetime`
+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.
 
 #### Additional Fields
 

item-spec/json-schema/datetime.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "schema.json#",
+  "title": "Date and Time Fields",
+  "type": "object",
+  "anyOf": [
+    {
+      "required": [
+        "datetime"
+      ],
+      "properties": {
+        "datetime": {
+          "$ref": "#/definitions/datetime_string"
+        },
+        "start_datetime": {
+          "$ref": "#/definitions/start_datetime"
+        }, 
+        "end_datetime": {
+          "$ref": "#/definitions/end_datetime"
+        }
+      },
+      "dependencies": {
+        "start_datetime": {
+          "required": [
+            "end_datetime"
+          ]
+        },
+        "end_datetime": {
+          "required": [
+            "start_datetime"
+          ]
+        }
+      }
+    },
+    {
+      "required": [
+        "datetime",
+        "start_datetime",
+        "end_datetime"
+      ],
+      "properties": {
+        "datetime": {
+          "oneOf": [
+            {
+              "$ref": "#/definitions/datetime_string"
+            },
+            {
+              "type": ["null"],
+              "const": null
+            }
+          ]
+        },
+        "start_datetime": {
+          "$ref": "#/definitions/start_datetime"
+        }, 
+        "end_datetime": {
+          "$ref": "#/definitions/end_datetime"
+        }
+      }
+    }
+  ],
+  "definitions": {
+    "datetime_string": {
+      "title": "Date and Time",
+      "type": "string",
+      "format": "date-time"
+    },
+    "start_datetime": {
+      "title": "Start Date and Time",
+      "type": "string",
+      "format": "date-time"
+    }, 
+    "end_datetime": {
+      "title": "End Date and Time",                
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

item-spec/json-schema/item.json

@@ -17,7 +17,7 @@
           "$ref": "basics.json"
         },
         {
-          "$ref": "datetimerange.json"
+          "$ref": "datetime.json"
         },
         {
           "$ref": "instrument.json"
@@ -116,25 +116,7 @@
               }
             },
             "properties": {
-              "allOf": [
-                {
-                  "type": "object",
-                  "required": [
-                    "datetime"
-                  ],
-                  "properties": {
-                    "datetime": {
-                      "title": "Date and Time",
-                      "description": "The searchable date/time of the assets, in UTC (Formatted in RFC 3339) ",
-                      "type": "string",
-                      "format": "date-time"
-                    }
-                  }
-                },
-                {
-                  "$ref": "#/definitions/common_metadata"
-                }
-              ]
+              "$ref": "#/definitions/common_metadata"
             },
             "collection": {
               "title": "Collection ID",