Merge branch 'dev' into preview-rel-type

CHANGELOG.md

@@ -16,6 +16,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 - The first extent in a Collection is always the overall extent, followed by more specific extents. ([#1064](https://github.com/radiantearth/stac-spec/issues/1064), [opengeospatial/ogcapi-features#520](https://github.com/opengeospatial/ogcapi-features/pull/520))
 - Updated examples for automatic collection creation from code and validation ([#1080](https://github.com/radiantearth/stac-spec/pull/1080)
 - Clarified that stac_extensions should also list extensions that are used in Collection summaries. ([#1077](https://github.com/radiantearth/stac-spec/issues/1077))
+- `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095))
 
 ## [v1.0.0-rc.2] - 2021-03-30
 

best-practices.md

@@ -72,8 +72,8 @@ So to enable all the great web tools (like [stacindex.org](http://stacindex.org)
 [Google Cloud Storage](https://cloud.google.com/storage/docs/cross-origin), or [Apache Server](https://enable-cors.org/server_apache.html). 
 Many more are listed on [enable-cors.org](https://enable-cors.org/server.html). We recommend enabling CORS for all requests ('\*'),
 so that diverse online tools can access your data. If you aren't sure if your server has CORS enabled you can use 
-[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) JSON 
-and make sure it gets a response.
+[test-cors.org](https://www.test-cors.org/). Enter the URL of your STAC root [Catalog](catalog-spec/catalog-spec.md) or
+[Collection](collection-spec/collection-spec.md) JSON and make sure it gets a response.
 
 ### STAC on the Web
 
@@ -82,7 +82,7 @@ surprised that there is nothing about HTML in the entire specification. This is
 should be on web pages without ending up with very bad looking pages. But the importance of having web-accessible versions
 of every STAC Item is paramount.
 
-The main recommendation is to have an HTML page for every single STAC Item and Catalog. They should be visually pleasing, 
+The main recommendation is to have an HTML page for every single STAC Item, Catalog and Collection. They should be visually pleasing, 
 crawlable by search engines and ideally interactive. The current best practice is to use a tool in the STAC ecosystem called
 [STAC Browser](https://github.com/radiantearth/stac-browser/). It can crawl most any valid STAC implementation and generate unique web
 pages for each Item and Catalog (or Collection). While it has a default look and feel, the design can easily be 
@@ -394,6 +394,10 @@ file that just has the bands needed for display
 
 ## Catalog & Collection Practices
 
+*Note: This section uses the term 'Catalog' (with an uppercase C) to refer to the JSON entity specified in the 
+[Catalog spec](catalog-spec/catalog-spec.md), and 'catalog' (with a lowercase c) to refer to any full STAC implementation, 
+which can be any mix of Catalogs Collections and Items.*
+
 ### Static and Dynamic Catalogs
 
 As mentioned in the main [overview](overview.md), there are two main types of catalogs - static
@@ -447,7 +451,7 @@ providers, and users could browse down to both. The leaf Items should just be li
 
 ### Catalog Layout
 
-Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, items
+Creating a catalog involves a number of decisions as to what folder structure to use to represent sub-catalogs, Items
 and assets, and how to name them. The specification leaves this totally open, and you can link things as you want. But 
 it is recommended to be thoughtful about the organization of sub-catalogs, putting them into a structure that a person
 might reasonably browse (since they likely will with [STAC on the Web](#stac-on-the-web) recommendations). For example
@@ -464,14 +468,14 @@ if you follow these recommendations.
 1. Root documents (Catalogs / Collections) should be at the root of a directory tree containing the static catalog.
 2. Catalogs should be named `catalog.json` and Collections should be named `collection.json`.
 3. Items should be named `<id>.json`.
-4. Sub-Catalogs should be stored in subdirectories of their parent
+4. Sub-Catalogs or sub-Collections should be stored in subdirectories of their parent
    (and only 1 subdirectory deeper than a document's parent, e.g. `.../sample/sub1/catalog.json`).
-5. Items should be stored in subdirectories of their parent Catalog. 
-This means that each Item and its assets are contained in a unique subdirectory.
-6. Limit the number of Items in a Catalog or sub-Catalog, grouping / partitioning as relevant to the dataset.
+5. Items should be stored in subdirectories of their parent Catalog or Collection. 
+   This means that each Item and its assets are contained in a unique subdirectory.
+6. Limit the number of Items in a Catalog or Collection, grouping / partitioning as relevant to the dataset.
 7. Use structural elements (Catalog and Collection) consistently across each 'level' of your hierarchy.
    For example, if levels 2 and 4 of the hierarchy only contain Collections, 
-don't add a Catalog at levels 2 and 4.
+   don't add a Catalog at levels 2 and 4.
 
 #### Dynamic Catalog Layout
 
@@ -484,7 +488,7 @@ different sub-catalog organization structures. For example one catalog could div
 by providers, and users could browse down to both. The leaf Items should just be linked to in a single canonical location 
 (or at least use a rel link that indicates the location of the canonical one). It is recommended that dynamic catalogs 
 provide multiple 'views' to allow users to navigate in a way that makes sense to them, providing multiple 'sub-catalogs'
-from the root Catalog that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the 
+from the root that enable different paths to browse (country/state, date/time, constellation/satellite, etc). But the 
 canonical 'rel' link should be used to designate the primary location of the Item to search engine crawlers.
 
 #### Mixing STAC Versions
@@ -609,9 +613,9 @@ implement it.
 #### Relative Published Catalog
 
 This is a self-contained catalog as described above, except it includes an absolute `self` link at
-the root catalog, to identify its online location. This is designed so that a self-contained catalog (of either type, with its 
+the root to identify its online location. This is designed so that a self-contained catalog (of either type, with its 
 assets or just metadata) can be 'published' online
-by just adding one field (the self link) to its root catalog. All the other links should remain the same. The resulting catalog
+by just adding one field (the self link) to its root (Catalog or Collection). All the other links should remain the same. The resulting catalog
 is no longer compliant with the self-contained catalog recommendations, but instead transforms into a 'relative published catalog'. 
 With this, a client may resolve Item and sub-catalog self links by traversing parent and root links, but requires reading 
 multiple sources to achieve this. 
@@ -633,8 +637,8 @@ a number of the common official relations that are used in production STAC imple
 | alternate | It is recommended that STAC Items are also available as HTML, and should use this rel with `"type" : "text/html"` to tell clients where they can get a version of the Item or Collection to view in a browser. See [STAC on the Web in Best Practices](#stac-on-the-web) for more information. |
 | canonical | The URL of the [canonical](https://en.wikipedia.org/wiki/Canonical_link_element) version of the Item or Collection. API responses and copies of catalogs should use this to inform users that they are direct copy of another STAC Item, using the canonical rel to refer back to the primary location. |
 | via       | The URL of the source metadata that this STAC Item or Collection is created from. Used similarly to canonical, but refers back to a non-STAC record (Landsat MTL, Sentinel tileInfo.json, etc) |
-| prev      | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs. |
-| next      | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs. |
+| prev      | Indicates that the link's context is a part of a series, and that the previous in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. |
+| next      | Indicates that the link's context is a part of a series, and that the next in the series is the link target. Typically used in STAC by API's, to return smaller groups of Items or Catalogs/Collections. |
 | preview   | Refers to a resource that serves as a preview (see [RFC 6903, sec. 3](https://tools.ietf.org/html/rfc6903#section-3)), usually a lower resolution thumbnail. In STAC this would usually be the same URL as the [thumbnail](#thumbnail) asset, but adding it as a link in addition enables OGC API clients that can't read assets to make use of it. It also adds support for thumbnails to STAC Catalogs as they can't list assets. |
 
 ### Versioning for Catalogs

catalog-spec/catalog-spec.md

@@ -36,8 +36,9 @@ and fields to be compliant.
 This Catalog specification primarily defines a structure for information to be discoverable. Any use 
 that is publishing a set of related spatiotemporal assets is strongly recommended to also use the 
 STAC Collection specification to provide additional information about the set of Items 
-contained in a Catalog, in order to give contextual information to aid in discovery. Every STAC Collection is 
-also a valid STAC Catalog.
+contained in a Catalog, in order to give contextual information to aid in discovery.
+STAC Collections all have the same fields as STAC Catalogs, but with different allowed 
+values for `type` and `stac_extensions`.
 
 ## Catalog fields
 
@@ -89,11 +90,11 @@ The following types are commonly used as `rel` types in the Link Object of a STA
 | ------- | ----------- |
 | self    | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Catalog file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
 | root    | STRONGLY RECOMMENDED. URL to the root STAC Catalog or [Collection](../collection-spec/README.md). Catalogs should include a link to their root, even if it's the root and points to itself. |
-| parent  | URL to the parent STAC Catalog or Collection. Non-root Catalogs should include a link to their parent. |
-| child   | URL to a child STAC Catalog or Collection. |
+| parent  | URL to the parent STAC entity (Catalog or Collection). Non-root Catalogs should include a link to their parent. |
+| child   | URL to a child STAC entity (Catalog or Collection). |
 | item    | URL to a STAC Item. |
 
-**Note:** A link to at least one `item` or `child` Catalog is **REQUIRED**.
+**Note:** A link to at least one `item` or `child` (Catalog or Collection) is **REQUIRED**.
 
 There are additional `rel` types in the [Using Relation Types](../best-practices.md#using-relation-types) best practice, but as 
 they are more typically used in Collections, as Catalogs tend to just be used to structure STAC organization, so tend to just use

collection-spec/collection-spec.md

@@ -197,7 +197,7 @@ Clients only interested in the overall extent will only need to access the first
 It is recommended to only use multiple temporal extents if a union of them would then include a large
 uncovered time span (e.g. only having data for the years 2000, 2010 and 2020).
 
-Each inner array consists of exactly two dates and times.
+Each inner array consists of exactly two dates and times, each in UTC.
 Each date and time MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
 The temporal reference system is the Gregorian calendar.
 
@@ -252,9 +252,9 @@ This is done where there is not a clear official option, or where STAC uses an o
 | Type    | Description                                                  |
 | ------- | ------------------------------------------------------------ |
 | self    | STRONGLY RECOMMENDED. *Absolute* URL to the location that the Collection file can be found online, if available. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
-| root    | URL to the root STAC Catalog or Collection. Collections should include a link to their root, even if it's the root and points to itself. |
-| parent  | URL to the parent STAC Catalog or Collection. Non-root Collections should include a link to their parent. |
-| child   | URL to a child STAC Catalog or Collection. |
+| root    | URL to the root STAC entity (Catalog or Collection). Collections should include a link to their root, even if it's the root and points to itself. |
+| parent  | URL to the parent STAC entity (Catalog or Collection). Non-root Collections should include a link to their parent. |
+| child   | URL to a child STAC entity (Catalog or Collection). |
 | item    | URL to a STAC Item. All Items linked from a Collection MUST refer back to its Collection with the [`collection` relation type](../item-spec/item-spec.md#relation-types). |
 | license | The license URL(s) for the Collection SHOULD be specified if the `license` field is set to `proprietary` or `various`. If there is no public license URL available, it is RECOMMENDED to put the license text in a separate file and link to this file. |
 | derived_from | URL to a STAC Collection that was used as input data in the creation of this Collection. See the note in [STAC Item](../item-spec/item-spec.md#derived_from) for more info. |

collection-spec/json-schema/collection.json

@@ -153,7 +153,8 @@
                         "string",
                         "null"
                       ],
-                      "format": "date-time"
+                      "format": "date-time",
+                      "pattern": "(\\+00:00|Z)$"
                     }
                   }
                 }

item-spec/common-metadata.md

@@ -43,8 +43,8 @@ Fields to provide additional temporal information such as ranges with a start an
 | Field Name | Type         | Description |
 | ---------- | ------------ | ----------- |
 | datetime   | string\|null | See the [Item Spec Fields](item-spec.md#properties-object) for more information. |
-| created    | string       | Creation date and time of the corresponding data (see below). |
-| updated    | string       | Date and time the corresponding data (see below) was updated last. |
+| created    | string       | Creation date and time of the corresponding data (see below), in UTC. |
+| updated    | string       | Date and time the corresponding data (see below) was updated last, in UTC. |
 
 All timestamps MUST be formatted according to [RFC 3339, section 5.6](https://tools.ietf.org/html/rfc3339#section-5.6).
 

item-spec/item-spec.md

@@ -84,7 +84,7 @@ It is important that an Item identifier is unique within a Collection, and that
 [Collection identifier](../collection-spec/collection-spec.md#id) in turn is unique globally. Then the two can be combined to
 give a globally unique identifier. Items are *[strongly recommended](#collections)* to have Collections, and not having one makes
 it more difficult to be used in the wider STAC ecosystem.
-If an Item does not have a Collection, then the Item identifier should be unique within its root Catalog.
+If an Item does not have a Collection, then the Item identifier should be unique within its root Catalog or root Collection.
 
 As most geospatial assets are already uniquely defined by some 
 identification scheme from the data provider it is recommended to simply use that ID.
@@ -127,7 +127,7 @@ resources below.
 
 | 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   | string\|null | **REQUIRED.** The searchable date and time of the assets, which must be 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
 
@@ -136,7 +136,8 @@ or representative time in the case of assets that are combined together. Though
 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.
+datetime fields. **All times in STAC metadata should be in [Coordinated Universal 
+Time](https://en.wikipedia.org/wiki/Coordinated_Universal_Time) (UTC).**
 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
@@ -192,8 +193,8 @@ This happens where there is not a clear official option, or where STAC uses an o
 | Type         | Description                                                  |
 | ------------ | ------------------------------------------------------------ |
 | self         | STRONGLY RECOMMENDED. *Absolute* URL to the Item if it is available at a public URL. This is particularly useful when in a download package that includes metadata, so that the downstream user can know where the data has come from. |
-| root         | URL to the root STAC Catalog or Collection. |
-| parent       | URL to the parent STAC Catalog or Collection. |
+| root         | URL to the root STAC entity (Catalog or Collection). |
+| parent       | URL to the parent STAC entity (Catalog or Collection). |
 | collection   | STRONGLY RECOMMENDED. URL to a Collection. *Absolute* URLs should be used whenever possible. The referenced Collection is STRONGLY RECOMMENDED to implement the same STAC version as the Item. A link with this `rel` type is *required* if the `collection` field in properties is present. |
 | derived_from | URL to a STAC Item that was used as input data in the creation of this Item. |
 

item-spec/json-schema/datetime.json

@@ -20,29 +20,34 @@
       "title": "Date and Time",
       "description": "The searchable date/time of the assets, in UTC (Formatted in RFC 3339) ",
       "type": ["string", "null"],
-      "format": "date-time"
+      "format": "date-time",
+      "pattern": "(\\+00:00|Z)$"
     },
     "start_datetime": {
       "title": "Start Date and Time",
       "description": "The searchable start date/time of the assets, in UTC (Formatted in RFC 3339) ",
       "type": "string",
-      "format": "date-time"
+      "format": "date-time",
+      "pattern": "(\\+00:00|Z)$"
     }, 
     "end_datetime": {
       "title": "End Date and Time", 
       "description": "The searchable end date/time of the assets, in UTC (Formatted in RFC 3339) ",                  
       "type": "string",
-      "format": "date-time"
+      "format": "date-time",
+      "pattern": "(\\+00:00|Z)$"
     },
     "created": {
       "title": "Creation Time",
       "type": "string",
-      "format": "date-time"
+      "format": "date-time",
+      "pattern": "(\\+00:00|Z)$"
     },
     "updated": {
       "title": "Last Update Time",
       "type": "string",
-      "format": "date-time"
+      "format": "date-time",
+      "pattern": "(\\+00:00|Z)$"
     }
   }
 }