From 8b9267429e908d079fb7524e2da0e54c942e2fe3 Mon Sep 17 00:00:00 2001
From: Matthias Mohr <webmaster@mamo-net.de>
Date: Tue, 27 Aug 2024 11:51:41 +0200
Subject: [PATCH] Better describe Statistics Object #1318

---
 CHANGELOG.md                |  1 +
 commons/common-metadata.md  | 10 ++++++++++
 examples/collection.json    | 20 ++++++++++++++++++++
 examples/extended-item.json |  8 +++++++-
 4 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 030e197f..a86e7399 100644
--- a/CHANGELOG.md
+++ b/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
 
diff --git a/commons/common-metadata.md b/commons/common-metadata.md
index 84a9ca65..1096650b 100644
--- a/commons/common-metadata.md
+++ b/commons/common-metadata.md
@@ -290,6 +290,16 @@ 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 extensions such as the EO extension.
+
 | 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. |
diff --git a/examples/collection.json b/examples/collection.json
index 697243dc..f503c53d 100644
--- a/examples/collection.json
+++ b/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": [
diff --git a/examples/extended-item.json b/examples/extended-item.json
index 45ad0128..8037700a 100644
--- a/examples/extended-item.json
+++ b/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"
     }
   }
-}
+}
\ No newline at end of file