Deprecate more fields, add warning

stac-extensions · Jun 10, 2024 · 9fb8138 · 9fb8138
1 parent a484c57
commit 9fb8138
Show file tree

Hide file tree

Showing 6 changed files with 37 additions and 34 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -14,6 +14,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Deprecated
 
 - `s1:processing_datetime` in favor of `processing:datetime`
+- `s1:product_timeliness` in favor of `product:timeliness_category` and `product:timeliness`
+- `s1:resolution` in favor of `gsd`, `spatial_resolution` (raster extension), and/or `sar:resolution_range` `sar:resolution_azimuth` (SAR extension)
+- `s1:product_identifier` in favor of `id` or links to source products (e.g. relation types `via` or `derived_from`)
 
 ### Removed
 

diff --git a/README.md b/README.md
@@ -10,12 +10,14 @@
 This document explains the Sentinel-1 Extension to the
 [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
 
-The intention of the first version of the specification is to define the existing behavior of
-the properties prefixed with `s1` as created by the [stactools-sentinel1](https://github.com/stactools-packages/sentinel1)
-package and used by [Earth Search](https://earth-search.aws.element84.com/v1) and
-[Microsoft Planetary Computer](https://planetarycomputer.microsoft.com/api/stac/v1). Future versions
-will aspire to standardize fields such as the numerous coverage calculations into separate extensions
-that are not specific to Sentinel-1.
+> [!CAUTION]
+> The intention of the first version of the specification was to reflect the existing behavior of
+the properties prefixed with `s1`
+> as implemented by the [stactools-sentinel1](https://github.com/stactools-packages/sentinel1) package.
+> The following version deprecated most of the fields in favor of other extensions that are not specific to Sentinel-1.
+> The remaining fields are highly specific and usually not of interest of an average user.
+> As such implementors should only implement the fields that they think bring value to their users.
+> Many implementations may not need to implement this extension at all.
 
 - Examples:
   - [Item: Microsoft Planetary Computer, Sentinel-1 GRD](examples/mspc-s1-grd.json)
@@ -39,14 +41,17 @@ The fields in the table below can be used in these parts of STAC documents:
 | s1:datatake_id                 | string    | e.g. `420895`                                                |
 | s1:instrument_configuration_ID | string    | e.g. `7`                                                     |
 | s1:orbit_source                | string    | e.g. `PREORB`                                                |
-| s1:product_identifier          | string    | e.g. `S1A_IW_GRDH_1SDV_20240318T153023_20240318T153035_053038_066C1F_F913` |
-| s1:product_timeliness          | string    | e.g. `NRT-3h`, `Fast-24h`                                    |
-| s1:resolution                  | string    | e.g. `high`                                                  |
 | s1:slice_number                | string    | e.g. `17`                                                    |
 | s1:total_slices                | string    | e.g. `17`                                                    |
-| s1:processing_datetime         | string    | **DEPRECATED** Use processing:datetime instead               |
-| s1:processing_level            | string    | **DEPRECATED** Use processing:level instead                  |
-| s1:shape                       | [integer] | **DEPRECATED** Use proj:shape instead                        |
+| s1:resolution                  | string    | **DEPRECATED** Expose `gsd`, `spatial_resolution` (raster extension), and/or `sar:resolution_range` `sar:resolution_azimuth` (SAR extension) instead. The mapping is available in Table B.1 of the [Sentinel-1 documentation](https://sentinel.esa.int/documents/247904/349449/s1_sp-1322_1.pdf). |
+| s1:product_identifier          | string    | **DEPRECATED** Use Item `id` or link to source products instead (e.g. relation types `via` or `derived_from`) |
+| s1:product_timeliness          | string    | **DEPRECATED** Use `product:timeliness_category` and `product:timeliness` instead |
+| s1:processing_datetime         | string    | **DEPRECATED** Use `processing:datetime` instead             |
+| s1:processing_level            | string    | **DEPRECATED** Use `processing:level` instead                |
+| s1:shape                       | [integer] | **DEPRECATED** Use `proj:shape` instead                      |
+
+**s1:resolution:** Either `full` (Full Resolution - SM mode), `high` (High Resolution - SM, IW and EW mode),
+or `medium` (Medium Resolution - SM, IW, EW and WV modes)
 
 ## Contributing
 

diff --git a/examples/earthsearch-s1-grd.json b/examples/earthsearch-s1-grd.json
@@ -50,18 +50,14 @@
     "constellation": "sentinel-1",
     "start_datetime": "2024-03-25T09:46:55.852211Z",
     "end_datetime": "2024-03-25T09:48:11.472734Z",
+    "processing:level": "L1",
+    "product:timeliness": "PT24H",
+    "product:timeliness_category": "Fast-24h",
     "s1:instrument_configuration_ID": "7",
     "s1:datatake_id": "421851",
-    "s1:product_timeliness": "Fast-24h",
-    "s1:processing_level": "1",
-    "s1:resolution": "medium",
     "s1:orbit_source": "RESORB",
     "s1:slice_number": "1",
     "s1:total_slices": "1",
-    "s1:shape": [
-      10309,
-      12777
-    ],
     "s1:product_identifier": "S1A_EW_GRDM_1SDH_20240325T094655_20240325T094811_053136_066FDB_411C",
     "processing:datetime": "2024-03-25T11:02:44.000000Z",
     "storage:platform": "AWS",
@@ -331,6 +327,7 @@
     "https://stac-extensions.github.io/storage/v1.0.0/schema.json",
     "https://stac-extensions.github.io/sar/v1.0.0/schema.json",
     "https://stac-extensions.github.io/processing/v1.2.0/schema.json",
+    "https://stac-extensions.github.io/product/v0.1.0/schema.json",
     "https://stac-extensions.github.io/sat/v1.0.0/schema.json",
     "https://stac-extensions.github.io/raster/v1.1.0/schema.json",
     "https://stac-extensions.github.io/sentinel-1/v0.1.0/schema.json"

diff --git a/examples/mspc-s1-grd.json b/examples/mspc-s1-grd.json
@@ -179,13 +179,12 @@
   "properties": {
     "datetime": "2024-03-25T05:50:50.645981Z",
     "platform": "SENTINEL-1A",
-    "s1:shape": [
+    "proj:shape": [
       26457,
       16665
     ],
     "end_datetime": "2024-03-25 05:51:03.145498+00:00",
     "constellation": "Sentinel-1",
-    "s1:resolution": "high",
     "s1:datatake_id": "421828",
     "start_datetime": "2024-03-25 05:50:38.146465+00:00",
     "s1:orbit_source": "PREORB",
@@ -202,11 +201,12 @@
     "sar:frequency_band": "C",
     "sat:absolute_orbit": 53134,
     "sat:relative_orbit": 37,
-    "s1:processing_level": "1",
+    "processing:level": "L1",
     "sar:instrument_mode": "IW",
     "sar:center_frequency": 5.405,
     "sar:resolution_range": 20,
-    "s1:product_timeliness": "NRT-3h",
+    "product:timeliness": "PT3H",
+    "product:timeliness_category": "NRT-3h",
     "sar:resolution_azimuth": 22,
     "sar:pixel_spacing_range": 10,
     "sar:observation_direction": "right",
@@ -218,7 +218,10 @@
   "stac_extensions": [
     "https://stac-extensions.github.io/sar/v1.0.0/schema.json",
     "https://stac-extensions.github.io/sat/v1.0.0/schema.json",
-    "https://stac-extensions.github.io/sentinel-1/v0.1.0/schema.json"
+    "https://stac-extensions.github.io/sentinel-1/v0.1.0/schema.json",
+    "https://stac-extensions.github.io/projection/v1.1.0/schema.json",
+    "https://stac-extensions.github.io/processing/v1.2.0/schema.json",
+    "https://stac-extensions.github.io/product/v0.1.0/schema.json"
   ],
   "stac_version": "1.0.0"
 }
diff --git a/examples/mspc-s1-rtc.json b/examples/mspc-s1-rtc.json
@@ -135,10 +135,6 @@
   "properties": {
     "datetime": "2024-03-25T05:50:50.645981Z",
     "platform": "SENTINEL-1A",
-    "s1:shape": [
-      29533,
-      22203
-    ],
     "proj:bbox": [
       130640,
       5618570,
@@ -152,7 +148,6 @@
     ],
     "end_datetime": "2024-03-25 05:51:03.145498+00:00",
     "constellation": "Sentinel-1",
-    "s1:resolution": "high",
     "proj:transform": [
       10,
       0,
@@ -180,11 +175,12 @@
     "sar:frequency_band": "C",
     "sat:absolute_orbit": 53134,
     "sat:relative_orbit": 37,
-    "s1:processing_level": "1",
+    "processing:level": "L1",
     "sar:instrument_mode": "IW",
     "sar:center_frequency": 5.405,
     "sar:resolution_range": 20,
-    "s1:product_timeliness": "NRT-3h",
+    "product:timeliness_category": "NRT-3h",
+    "product:timeliness": "PT3H",
     "sar:resolution_azimuth": 22,
     "sar:pixel_spacing_range": 10,
     "sar:observation_direction": "right",
@@ -197,6 +193,8 @@
     "https://stac-extensions.github.io/sar/v1.0.0/schema.json",
     "https://stac-extensions.github.io/sat/v1.0.0/schema.json",
     "https://stac-extensions.github.io/projection/v1.1.0/schema.json",
+    "https://stac-extensions.github.io/processing/v1.2.0/schema.json",
+    "https://stac-extensions.github.io/product/v0.1.0/schema.json",
     "https://stac-extensions.github.io/file/v2.0.0/schema.json",
     "https://stac-extensions.github.io/raster/v1.1.0/schema.json",
     "https://stac-extensions.github.io/sentinel-1/v0.1.0/schema.json"

diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -63,9 +63,6 @@
         {"required": ["s1:datatake_id"]},
         {"required": ["s1:instrument_configuration_ID"]},
         {"required": ["s1:orbit_source"]},
-        {"required": ["s1:product_identifier"]},
-        {"required": ["s1:product_timeliness"]},
-        {"required": ["s1:resolution"]},
         {"required": ["s1:slice_number"]},
         {"required": ["s1:total_slices"]}
       ]