Merge branch 'dev' into summaries

CHANGELOG.md

@@ -9,15 +9,19 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Added
 
+- Summaries are allowed to specify JSON Schema in addition to ranges and sets of values. ([#1045](https://github.com/radiantearth/stac-spec/issues/1045))
 - Added `preview` relation type for interoperable thumbnails to best practices. ([#1090](https://github.com/radiantearth/stac-spec/issues/1090))
+- Recommendation to include both `root` and `parent` relation types when they point at the same file.
 
 ### Changed
 
 - 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)
+- 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))
+- The Stats Object for Summaries has been renamed to Range Object (no functional change).
 - `changed`, `created` (common metadata) and temporal extents (collections): Timestamps must be always in UTC ([#1095](https://github.com/radiantearth/stac-spec/issues/1095))
 - Clarified that collection summaries do not require that all property fields are summarized. ([#1106](https://github.com/radiantearth/stac-spec/issues/1106))
+- Clarified that gsd should only be used on an asset to represent the sensor, not just different processing. ([#1105](https://github.com/radiantearth/stac-spec/pull/1105))
 
 ## [v1.0.0-rc.2] - 2021-03-30
 
@@ -52,7 +56,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 
 ### Changed
 
-- The [Stats Object](collection-spec/collection-spec.md#stats-object) for Collection `summaries` changed `min` to `minimum` and `max` to `maximum` to align with JSON Schema. ([#967](https://github.com/radiantearth/stac-spec/pull/967))
+- The [Stats Object](collection-spec/collection-spec.md#range-object) for Collection `summaries` changed `min` to `minimum` and `max` to `maximum` to align with JSON Schema. ([#967](https://github.com/radiantearth/stac-spec/pull/967))
 - URIs (usually found int properties like `href`, `url`) are now validated using the `iri-reference` format in JSON Schema (allows international characters in URIs) ([#953](https://github.com/radiantearth/stac-spec/pull/953))
 - Enhanced the way the spec talks about ID's to encourage more global uniqueness. ([#883](https://github.com/radiantearth/stac-spec/pull/883))
 - Clarified how collection-level asset object properties do not remove the need for item-level asset object properties in the `item-assets` extension ([#880](https://github.com/radiantearth/stac-spec/pull/880))

best-practices.md

@@ -255,8 +255,10 @@ providing them at at the Asset level can prove to be very useful for using the d
 
 - `datetime`: Provide individual timestamp on an Item, in case the Item has a `start_datetime` and `end_datetime`,
   but an Asset is for one specific time.
-- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets with different spatial resolution 
-than the overall best resolution.
+- `gsd` ([Common Metadata](item-spec/common-metadata.md#instrument)): Specify some assets that represent instruments 
+  with different spatial resolution than the overall best resolution. Note this should not be used for different 
+  spatial resolutions due to specific processing of assets - look into the [raster 
+  extension](https://github.com/stac-extensions/raster) for that use case.
 - `eo:bands` ([EO extension](https://github.com/stac-extensions/eo/)):
   Provide spectral band information, and order of bands, within an individual asset.
 - `proj:epsg`/`proj:wkt2`/`proj:projjson` ([projection extension](https://github.com/stac-extensions/projection/)):
@@ -641,6 +643,10 @@ a number of the common official relations that are used in production STAC imple
 | 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. |
 
+Being liberal with the `links` also means that it's ok to have repeated links with the same `href`. For example the
+`parent` and `root` relation types will point at the same file when the child is directly below the root, and it is
+recommended to include both. 
+
 ### Versioning for Catalogs
 
 In the Item and Collection STAC JSON, versions and deprecation can be indicated with the

catalog-spec/catalog-spec.md

@@ -50,7 +50,7 @@ values for `type` and `stac_extensions`.
 | id              | string        | **REQUIRED.** Identifier for the Catalog.                    |
 | title           | string        | A short descriptive one-line title for the Catalog.          |
 | description     | string        | **REQUIRED.** Detailed multi-line description to fully explain the Catalog. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
-| summaries       | Map<string, \[*]\|[Stats Object](../collection-spec/collection-spec.md#stats-object)> | A map of property summaries, either a set of values or statistics such as a range. More info in the [Collection spec](../collection-spec/collection-spec.md#summaries). |
+| summaries       | Map<string, \[\*]\|[Range Object](../collection-spec/collection-spec.md#range-object)\|[JSON Schema Object](../collection-spec/collection-spec.md#json-schema-object)> | A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). More info in the [Collection spec](../collection-spec/collection-spec.md#summaries). |
 | links           | [[Link Object](#link-object)] | **REQUIRED.** A list of references to other documents.       |
 
 ### Additional Field Information

catalog-spec/json-schema/catalog-core.json

@@ -99,9 +99,19 @@
     "summaries": {
       "type": "object",
       "additionalProperties": {
-        "oneOf": [
+        "anyOf": [
           {
-            "title": "Stats",
+            "title": "JSON Schema",
+            "type": "object",
+            "minProperties": 1,
+            "allOf": [
+              {
+                "$ref": "http://json-schema.org/draft-07/schema"
+              }
+            ]
+          },
+          {
+            "title": "Range",
             "type": "object",
             "required": [
               "minimum",
@@ -129,7 +139,7 @@
             "type": "array",
             "minItems": 1,
             "items": {
-              "description": "Any data type could occur."
+              "description": "For each field only the original data type of the property can occur (except for arrays), but we can't validate that in JSON Schema yet. See the sumamry description in the STAC specification for details."
             }
           }
         ]

collection-spec/collection-spec.md

@@ -16,7 +16,8 @@
   - [Link Object](#link-object)
     - [Relation types](#relation-types)
   - [Asset Object](#asset-object)
-  - [Stats Object](#stats-object)
+  - [Range Object](#range-object)
+  - [JSON Schema Object](#json-schema-object)
 - [Media Type for STAC Collections](#media-type-for-stac-collections)
 - [Standalone Collections](#standalone-collections)
 
@@ -54,7 +55,7 @@ specified in [*OGC API - Features*](https://ogcapi.ogc.org/features/), but they
 | license         | string                                           | **REQUIRED.** Collection's license(s), either a SPDX [License identifier](https://spdx.org/licenses/), `various` if multiple licenses apply or `proprietary` for all other cases. |
 | providers       | \[[Provider Object](#provider-object)]           | A list of providers, which may include all organizations capturing or processing the data or the hosting provider. Providers should be listed in chronological order with the most recent provider being the last element of the list. |
 | extent          | [Extent Object](#extent-object)                  | **REQUIRED.** Spatial and temporal extents.                  |
-| summaries       | Map<string, \[*]\|[Stats Object](#stats-object)> | STRONGLY RECOMMENDED. A map of property summaries, either a set of values or statistics such as a range. |
+| summaries       | Map<string, \[\*]\|[Range Object](#range-object)\|[JSON Schema Object](#json-schema-object)> | STRONGLY RECOMMENDED. A map of property summaries, either a set of values, a range of values or a [JSON Schema](https://json-schema.org). |
 | links           | \[[Link Object](#link-object)]                   | **REQUIRED.** A list of references to other documents.       |
 | assets          | Map<string, [Asset Object](#asset-object)>       | Dictionary of asset objects that can be downloaded, each with a unique key. |
 
@@ -96,15 +97,17 @@ build tailored user interfaces for querying the data, by presenting the potentia
  Fields selected to be included in summaries should capture all the potential values of the 
  field that appear in every Item underneath the collection, including in any nested sub-Catalogs.
 
-A summary for a field can be specified in two ways:
+A summary for a field can be specified in three ways:
 
 1. A set of all distinct values in an array: The set of values must contain at least one element and it is strongly recommended to list all values.
    If the field summarizes an array (e.g. [`instruments`](../item-spec/common-metadata.md#instrument)),
    the field's array elements of each Item must be merged to a single array with unique elements.
-2. Statistics in a [Stats Object](#stats-object): Statistics by default only specify the range (minimum and maximum values),
+2. A Range in a [Range Object](#range-object): Statistics by default only specify the range (minimum and maximum values),
    but can optionally be accompanied by additional statistical values.
    The range specified by the `minimum` and `maximum` properties can specify the potential range of values,
    but it is recommended to be as precise as possible.
+3. Extensible JSON Schema definitions for fine-grained information, see the [JSON Schema Object](#json-schema-object)
+   section for more.
 
 All values must follow the schema of the property field they summarize, unless the field is an array as described in (1) above.
 So the values in the array or the values given for `minimum` and `maximum` must comply to the original data type
@@ -282,9 +285,9 @@ or streamed. The definition provided here, at the Collection level, is the same
 | type        | string    | [Media type](../item-spec/item-spec.md#asset-media-type) of the asset. See the [common media types](../best-practices.md#common-media-types-in-stac) in the best practice doc for commonly used asset types. |
 | roles       | \[string] | The [semantic roles](../item-spec/item-spec.md#asset-role-types) of the asset, similar to the use of `rel` in links. |
 
-### Stats Object
+### Range Object
 
-For a good understanding of the summarized field, statistics can be added.
+For summaries that would normally consist of a lot of continuous values, statistics can be added instead.
 By default, only ranges with a minimum and a maximum value can be specified.
 Ranges can be specified for [ordinal](https://en.wikipedia.org/wiki/Level_of_measurement#Ordinal_scale) values only,
 which means they need to have a rank order.
@@ -296,6 +299,17 @@ Implementors are free to add other derived statistical values to the object, for
 | minimum    | number\|string | **REQUIRED.** Minimum value. |
 | maximum    | number\|string | **REQUIRED.** Maximum value. |
 
+### JSON Schema Object
+
+For a full understanding of the summarized field, a JSON Schema can be added for each summarized field.
+This allows very fine-grained information for each field and each value as JSON Schema is also extensible.
+Each schema must be valid against all corresponding values available for the property in the sub-Items.
+
+It is recommended to use [JSON Schema draft-07](https://json-schema.org/specification-links.html#draft-7)
+to align with the JSON Schemas provided by STAC. Empty schemas are not allowed.
+
+For an introduction to JSON Schema, see "[Learn JSON Schema](https://json-schema.org/learn/)".
+
 ## Media Type for STAC Collections
 
 A STAC Collection is a JSON file ([RFC 8259](https://tools.ietf.org/html/rfc8259)), and thus should use the 

examples/catalog.json

@@ -21,6 +21,12 @@
       "type": "application/json",
       "title": "Collection with no items (standalone)"
     },
+    {
+      "rel": "child",
+      "href": "./collection-only/collection-with-schemas.json",
+      "type": "application/json",
+      "title": "Collection with no items (standalone with JSON Schemas)"
+    },
     {
       "rel": "item",
       "href": "./collectionless-item.json",