Allow and validate the fields mostly everywhere #5 #7 (#10)

stac-extensions · Jan 5, 2023 · 02da21e · 02da21e
1 parent a1a4846
commit 02da21e
Show file tree

Hide file tree

Showing 6 changed files with 144 additions and 31 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - All timestamps must be in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095))
+- The extension can now be used mostly everywhere (e.g. Catalog, Collections, Items, Assets, Links), which aligns with STAC common metadata.
 
 ### Deprecated
 

diff --git a/README.md b/README.md
@@ -8,15 +8,24 @@
 - **Owner**: @m-mohr
 - **History**: [Prior to March 2, 2021](https://github.com/radiantearth/stac-spec/commits/v1.0.0-rc.1/extensions/timestamps)
 
-This document explains the fields of the Timestamps Extension to a STAC Item.
+This document explains the fields of the Timestamps Extension to all STAC entities.
 Allows to specify numerous timestamps for assets and metadata in addition to [`created`, `updated` and `datetime` (incl. start and end)](https://github.com/radiantearth/stac-spec/tree/master/item-spec/common-metadata.md#date-and-time).
 
 - Examples:
-  - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
+  - [Catalog example](examples/catalog.json)
+  - [Collection example](examples/collection.json)
+  - [Item example](examples/item.json)
 - [JSON Schema](json-schema/schema.json)
 - [Changelog](./CHANGELOG.md)
 
-## Item Properties Fields
+## Fields
+
+The fields in the table below can be used in these parts of STAC documents:
+- [x] Catalogs
+- [x] Collections
+- [x] Item Properties (incl. Summaries in Collections)
+- [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
+- [x] Links
 
 | Field Name  | Type   | Description |
 | ----------- | ------ | ----------- |
@@ -26,9 +35,10 @@ Allows to specify numerous timestamps for assets and metadata in addition to [`c
 
 All timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
 
-The timestamps have different meaning depending on where they are used.
-If those fields are available in the Item `properties`, it's referencing to the timestamps valid for of the metadata.
-Having those fields in the Item `assets` refers to the timestamps valid for the actual data linked to in the Asset Object.
+**NOTE:** The timestamps have different meaning depending on where they are used.
+If those fields are available in a Collection, in a Catalog (both top-level), or in a Item (in the `properties`),
+the fields refer the metadata (e.g., when the STAC metadata was published).
+Having those fields in the Assets or Links, they refer to the actual data linked to (e.g., when the asset was published).
 
 ### Lifecycle
 
@@ -44,13 +54,6 @@ An overview over the lifecycle of data and their corresponding timestamps:
 8. Data valid until: `expires`
 9. Data removed / unpublished: `unpublished`
 
-## Outlook
-
-Once these fields get broadly adopted, it is planned to move them to Common Metadata and place them together with `created` and `updated`.
-As this extension doesn't have a prefix, it doesn't lead to any breaking changes and the thus it is only a structural change for the specification.
-
-This fields - together with `created` and `updated` - also seem relevant for STAC Collections and may be adopted there, too.
-
 ## Contributing
 
 All contributions are subject to the

diff --git a/examples/catalog.json b/examples/catalog.json
@@ -0,0 +1,23 @@
+{
+  "stac_version": "1.0.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/timestamps/v1.0.0/schema.json"
+  ],
+  "id": "landsat-8",
+  "type": "Catalog",
+  "title": "Example L8",
+  "description": "An example catalog...",
+  "created": "2018-10-02T00:00:03Z",
+  "updated": "2020-05-20T12:13:02Z",
+  "published": "2018-10-03T06:45:55Z",
+  "expires": "2025-01-01T00:00:00Z",
+  "links": [
+    {
+      "href": "https://example.com",
+      "rel": "about",
+      "type": "text/html",
+      "title": "Homepage",
+      "updated": "2020-05-20T12:13:01Z"
+    }
+  ]
+}
diff --git a/examples/collection.json b/examples/collection.json
@@ -0,0 +1,46 @@
+{
+  "stac_version": "1.0.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/timestamps/v1.0.0/schema.json"
+  ],
+  "id": "landsat-8",
+  "type": "Collection",
+  "title": "Example L8",
+  "description": "An example collection...",
+  "created": "2009-05-20T02:40:01.042784Z",
+  "updated": "2022-11-03T23:59:55.112875Z",
+  "published": "2009-05-20T02:40:01.042784Z",
+  "links": [
+    {
+      "rel": "item",
+      "href": "item.json",
+      "title": "Example Item",
+      "datetime": "2018-10-01T01:08:32Z",
+      "created": "2018-10-02T00:00:03Z",
+      "updated": "2020-05-20T12:13:02Z",
+      "published": "2018-10-03T06:45:55Z",
+      "expires": "2025-01-01T00:00:00Z"
+    }
+  ],
+  "extent": {
+    "spatial": {
+      "bbox": [
+        [
+          -180,
+          -56,
+          180,
+          83
+        ]
+      ]
+    },
+    "temporal": {
+      "interval": [
+        [
+          "2009-05-20T02:40:01.042784Z",
+          "2022-11-03T23:59:55.112875Z"
+        ]
+      ]
+    }
+  },
+  "license": "PDDL-1.0"
+}
diff --git a/examples/item.json b/examples/item.json
@@ -1,5 +1,5 @@
 {
-  "stac_version": "1.0.0-rc.1",
+  "stac_version": "1.0.0",
   "stac_extensions": [
     "https://stac-extensions.github.io/timestamps/v1.0.0/schema.json"
   ],
@@ -75,14 +75,16 @@
       "title": "Thumbnail image",
       "type": "image/jpeg",
       "created": "2018-10-02T00:00:01Z"
-    },
-    "index": {
+    }
+  },
+  "links": [
+    {
       "href": "https://landsat-pds.s3.amazonaws.com/c1/L8/107/018/LC08_L1TP_107018_20181001_20181001_01_RT/index.html",
+      "rel": "alternate",
       "type": "text/html",
       "title": "HTML index page",
       "created": "2018-10-02T00:00:02Z",
       "updated": "2020-05-20T12:13:01Z"
     }
-  },
-  "links": []
+  ]
 }
diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -12,7 +12,8 @@
           "required": [
             "type",
             "properties",
-            "assets"
+            "assets",
+            "links"
           ],
           "properties": {
             "type": {
@@ -22,10 +23,10 @@
               "$ref": "#/definitions/fields"
             },
             "assets": {
-              "type": "object",
-              "additionalProperties": {
-                "$ref": "#/definitions/fields"
-              }
+              "$ref": "#/definitions/assets"
+            },
+            "links": {
+              "$ref": "#/definitions/links"
             }
           }
         },
@@ -47,19 +48,44 @@
               "const": "Collection"
             },
             "assets": {
-              "type": "object",
-              "additionalProperties": {
-                "$ref": "#/definitions/fields"
-              }
+              "$ref": "#/definitions/assets"
             },
             "item_assets": {
-              "type": "object",
-              "additionalProperties": {
-                "$ref": "#/definitions/fields"
-              }
+              "$ref": "#/definitions/assets"
+            },
+            "links": {
+              "$ref": "#/definitions/links"
             }
           }
         },
+        {
+          "$ref": "#/definitions/fields"
+        },
+        {
+          "$ref": "#/definitions/stac_extensions"
+        }
+      ]
+    },
+    {
+      "$comment": "This is the schema for STAC Catalogs.",
+      "allOf": [
+        {
+          "type": "object",
+          "required": [
+            "type"
+          ],
+          "properties": {
+            "type": {
+              "const": "Catalog"
+            },
+            "links": {
+              "$ref": "#/definitions/links"
+            }
+          }
+        },
+        {
+          "$ref": "#/definitions/fields"
+        },
         {
           "$ref": "#/definitions/stac_extensions"
         }
@@ -81,6 +107,18 @@
         }
       }
     },
+    "links": {
+      "type": "array",
+      "items": {
+        "$ref": "#/definitions/fields"
+      }
+    },
+    "assets": {
+      "type": "object",
+      "additionalProperties": {
+        "$ref": "#/definitions/fields"
+      }
+    },
     "fields": {
       "type": "object",
       "properties": {