Better describe Statistics Object #1318 (#1319)

* Better describe Statistics Object #1318

* Update commons/common-metadata.md

CHANGELOG.md

@@ -11,6 +11,7 @@ and this project adheres to [Semantic Versioning](http://semver.org/spec/v2.0.0.
 ### Fixed
 
 - `item_assets` is not required
+- Better describe the Statistics Object ([#1318](https://github.com/radiantearth/stac-spec/issues/1318))
 
 ## [v1.1.0-beta.1] - 2024-08-08
 

commons/common-metadata.md

@@ -290,6 +290,17 @@ It is STRONGLY RECOMMENDED to provide units in one of the following two formats:
 
 ### Statistics Object
 
+Statistics usually specify the range of values by providing the `minimum` and `maximum` values,
+but can optionally be accompanied by additional statistical values.
+Some additional statistical sizes are listed below,
+but the object can also be extended with other statistical sizes that are not listed below.
+For example, it could list additional coverages such as vegetation cover, land cover, etc.
+If statistics are provided in the Item Properties ([example](../examples/extended-item.json)),
+it is recommended to list the statistical sizes with a JSON Schema in the Collection Summaries
+to better describe the sizes ([example](../examples/collection.json)).
+Please note that some statistical sizes such as cloud cover have explicit fields in other extensions such as the EO extension.
+It is recommended to use the fields standardized in extensions in favor of providing them in the Statistics Object.
+
 | Field Name    | Type    | Description                                                                                                                            |
 | ------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------- |
 | minimum       | number  | minimum value of the values in the band. If not present, the minimum value of the given data type or negative infinity can be assumed. |

examples/collection.json

@@ -80,6 +80,26 @@
     "view:sun_azimuth": {
       "minimum": 135.7,
       "maximum": 135.7
+    },
+    "statistics": {
+      "type": "object",
+      "properties": {
+        "vegetation": {
+          "description": "Percentage of pixels that are detected as vegetation, e.g. forests, grasslands, etc.",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "water": {
+          "description": "Percentage of pixels that are detected as water, e.g. rivers, oceans and ponds.",
+          "minimum": 0,
+          "maximum": 100
+        },
+        "urban": {
+          "description": "Percentage of pixels that detected as urban, e.g. roads and buildings.",
+          "minimum": 0,
+          "maximum": 100
+        }
+      }
     }
   },
   "links": [

examples/extended-item.json

@@ -59,6 +59,12 @@
     ],
     "gsd": 0.66,
     "eo:cloud_cover": 1.2,
+    "eo:snow_cover": 0,
+    "statistics": {
+      "vegetation": 12.57,
+      "water": 1.23,
+      "urban": 26.2
+    },
     "proj:code": "EPSG:32659",
     "proj:shape": [
       5558,
@@ -201,4 +207,4 @@
       "title": "Satellite Ephemeris Metadata"
     }
   }
-}
+}