SAR additions

stac-extensions · May 7, 2024 · d0b6a3b · d0b6a3b
1 parent 07bfee4
commit d0b6a3b
Show file tree

Hide file tree

Showing 3 changed files with 132 additions and 22 deletions.
diff --git a/json-schema/radar/product.json b/json-schema/radar/product.json
@@ -0,0 +1,3 @@
+{
+
+}
diff --git a/json-schema/radar/source.json b/json-schema/radar/source.json
@@ -0,0 +1,3 @@
+{
+
+}
diff --git a/radar.md b/radar.md
@@ -1,7 +1,9 @@
 # CEOS-ARD for Radar data <!-- omit in toc -->
 
 - **Title:** CEOS-ARD for Radar
-- **Identifier:** <https://stac-extensions.github.io/ceos-ard/v0.2.0/radar.json>
+- **Identifier:**
+  - Product: <https://stac-extensions.github.io/ceos-ard/v0.2.0/radar/product.json>
+  - Source(s): <https://stac-extensions.github.io/ceos-ard/v0.2.0/radar/source.json>
 - **Field Name Prefix:** -
 - **Scope:** Item
 - **Extension [Maturity Classification]:** Proposal
@@ -31,10 +33,16 @@ and includes the specifications for:
 - [Document Structure](#document-structure)
 - [STAC Extensions](#stac-extensions)
 - [STAC Collections](#stac-collections)
-- [STAC Items](#stac-items)
+- [STAC Items (ARD Product)](#stac-items-ard-product)
+  - [Extensions](#extensions)
   - [Common Metadata](#common-metadata)
   - [Projection](#projection)
-- [Links](#links)
+  - [Links](#links)
+- [STAC Items (Source Data)](#stac-items-source-data)
+  - [Extensions](#extensions-1)
+  - [Common Metadata](#common-metadata-1)
+  - [Assets](#assets)
+    - [Data](#data)
 - [Notes](#notes)
 
 ## Document Structure
@@ -60,13 +68,13 @@ fields are present, but this could be checked manually in the CEOS assessment/re
 
 The following STAC extensions are relevant for this profile:
 
-| Name              | Schema URI for `stac_extensions`                                        | Required |
-| ----------------- | ----------------------------------------------------------------------- | :------: |
-| [CEOS-ARD]        | `https://stac-extensions.github.io/ceos-ard/v0.2.0/optical/schema.json` | ✓        |
-| [Processing]      | `https://stac-extensions.github.io/processing/v1.1.0/schema.json`       | ✗        |
-| [Projection]      | `https://stac-extensions.github.io/projection/v1.0.0/schema.json`       | ✓        |
-| [Raster]          | `https://stac-extensions.github.io/raster/v2.0.0/schema.json`           | ✗        |
-| [SAR]             | `https://stac-extensions.github.io/sar/v1.0.0/schema.json`              | ✓        |
+| Name         | Schema URI for `stac_extensions`                             |
+| ------------ | ------------------------------------------------------------ |
+| [CEOS-ARD]   | `https://stac-extensions.github.io/ceos-ard/v0.2.0/optical/schema.json` |
+| [Processing] | `https://stac-extensions.github.io/processing/v1.1.0/schema.json` |
+| [Projection] | `https://stac-extensions.github.io/projection/v1.0.0/schema.json` |
+| [Raster]     | `https://stac-extensions.github.io/raster/v2.0.0/schema.json` |
+| [SAR]        | `https://stac-extensions.github.io/sar/v1.0.0/schema.json`   |
 
 For details about the CEOS-ARD extension, please see the separate [CEOS-ARD extension README](README.md#fields).
 The CEOS-ARD extension fields can either be provided in the Collection or in the Items.
@@ -81,24 +89,43 @@ you can de-duplicate links and assets by putting common links once into the STAC
 Also, common assets can be just put once into the STAC Collection using [Collection Assets].
 All this is still CEOS-ARD compliant as it doesn't require all information to be in a single file.
 
-## STAC Items
+## STAC Items (ARD Product)
 
 STAC Items must always be valid, but not all STAC Item requirements are covered here,
 only additional requirements and mappings to fulfill the CEOS-ARD requirements are listed here:
 
-| Field Name      | Req.  | Description |
-| --------------- | ----- | ----------- |
+| Field Name      | Req.  | Description                                                  |
+| --------------- | ----- | ------------------------------------------------------------ |
 | stac_extensions | *n/a* | **REQUIRED.** Must contain [all STAC extensions](#stac-extensions) implemented. |
-| geometry        | 1.4   | **REQUIRED.** The geometry of the acquisition. |
-| bbox            | 1.7.8 | **REQUIRED.** The bounding box of the acquisition in WGS84. |
+| geometry        | 1.4   | **REQUIRED.** The geometry of the acquisition.               |
+| bbox            | 1.7.8 | **REQUIRED.** The bounding box of the acquisition in WGS84.  |
 
 Generally, CEOS-ARD requests to provide DOIs for various resources.
 For STAC, DOIs (e.g. `10.1109/5.771073`) must be converted to URLs (e.g. `https://doi.org/10.1109/5.771073`).
 See [Resolve a DOI name](https://dx.doi.org/) for details.
 
+### Extensions
+
+The following STAC extensions are relevant for the product Items:
+
+| Name         | Required |
+| ------------ | :------: |
+| [CEOS-ARD]   |    ✓     |
+| [Processing] |    ✗     |
+| [Projection] |    ✓     |
+| [Raster]     |    ✗     |
+| [SAR]        |    ✓     |
+
+Providing the CEOS-ARD [fields](README.md#fields) and [links](README.md#relation-types) fulfills req. 1.3 and 1.4.
+The fields can be provided either in the [Collection](#stac-collections) or in each Item.
+
 ### Common Metadata
 
-...
+| Field Name     | Req. | Description                                                  |
+| -------------- | ---- | ------------------------------------------------------------ |
+| start_datetime | 1.5  | **REQUIRED.** The datetime of the earliest start datetime of all relevant acquisitions. |
+| end_datetime   | 1.5  | **REQUIRED.** The datetime of the latest end datetime of all relevant acquisitions. |
+| attribution    | 1.3  | Attribution / Copyright information if required by the data provider. |
 
 ### Projection
 
@@ -108,18 +135,95 @@ either `proj:epsg` or one of the alternatives. The map projection is not require
 **Deprecation Notice:** In a future version of the version of the projection extension `proj:epsg` will be replaced by `proj:code`.
 It is recommended to provide both for now.
 
-| Field Name                            | Req.      | Description                                                  |
-| ------------------------------------- | --------- | ------------------------------------------------------------ |
-| proj:epsg / proj:wkt2 / proj:projjson | 1.7.11    | **REQUIRED**. One of the fields is required to be provided, recommended is `proj:epsg`. If there's no suitable EPSG code, set `proj:epsg` to `null` and add either `proj:wkt2` or `proj:projjson`. |
-| proj:bbox                             | 1.7.7     | **REQUIRED**. The bounding box of the acquisition in the projection defined in proj:epsg / proj:wkt2 / proj:projjson. |
+| Field Name                            | Req.   | Description                                                  |
+| ------------------------------------- | ------ | ------------------------------------------------------------ |
+| proj:epsg / proj:wkt2 / proj:projjson | 1.7.11 | **REQUIRED**. One of the fields is required to be provided, recommended is `proj:epsg`. If there's no suitable EPSG code, set `proj:epsg` to `null` and add either `proj:wkt2` or `proj:projjson`. |
+| proj:bbox                             | 1.7.7  | **REQUIRED**. The bounding box of the acquisition in the projection defined in proj:epsg / proj:wkt2 / proj:projjson. |
 
-## Links
+### Links
 
-...
+All links can be provided either in the Collection or in the Item,
+unless the links are specific for each Item and/or differ between the Items (such as `derived_from`).
+If that's the case, they must be provided per Item.
+
+In addition to the links defined in specific extensions above, the following relation types are relevant:
+
+| Relation Type | Req. | Description                                                  |
+| ------------- | ---- | ------------------------------------------------------------ |
+| derived_from  | 1.5  | **REQUIRED.** URL to the source data acquisitions, ideally as STAC metadata. The source metadata files must comply to the requirements [below](#stac-items-source-data). The number of links with this relation type identify the number of source data acquisitions. |
+
+## STAC Items (Source Data)
+
+STAC Items must always be valid, but not all STAC Item requirements are covered here,
+only additional requirements and mappings to fulfill the CEOS-ARD requirements are listed here:
+
+| Field Name      | Req.  | Description                                                  |
+| --------------- | ----- | ------------------------------------------------------------ |
+| stac_extensions | *n/a* | **REQUIRED.** Must contain [all STAC extensions](#stac-extensions) implemented. |
+| geometry        | 1.4   | **REQUIRED.** The geometry of the acquisition.               |
+| bbox            | ?     | **REQUIRED.** The bounding box of the acquisition in WGS84.  |
+
+Generally, CEOS-ARD requests to provide DOIs for various resources.
+For STAC, DOIs (e.g. `10.1109/5.771073`) must be converted to URLs (e.g. `https://doi.org/10.1109/5.771073`).
+See [Resolve a DOI name](https://dx.doi.org/) for details.
+
+### Extensions
+
+The following STAC extensions are relevant for the product Items:
+
+| Name       | Required |
+| ---------- | :------: |
+| [CEOS-ARD] |    ✓     |
+
+Providing the CEOS-ARD [fields](README.md#fields) and [links](README.md#relation-types) fulfills req. 1.3 and 1.4.
+The fields can be provided either in the [Collection](#stac-collections) or in each Item.
+
+### Common Metadata
+
+| Field Name  | Req.  | Description                                                  |
+| ----------- | ----- | ------------------------------------------------------------ |
+| datetime    | 1.6.3 | **REQUIRED.** The start date and time of the source data. Can also be expressed as `start_datetime` and `end_datetime` instead. |
+| instruments | 1.6.2 | **REQUIRED.** Instruments in lower-case.                     |
+| platform    | 1.6.2 | **REQUIRED.** Satellite name in lower-case.                  |
+
+Requirement 1.6.2 asks to provide links to:
+- [CEOS Missions Database] record(s)
+- [CEOS Instruments Database] record(s)
+- [CEOS Measurements Database] record(s)
+
+### Assets
+
+**Data Access:** Requirement 1.6.1 **requires** information about data access.
+This requirement is automatically fulfilled by STAC if the referenced assets are publicly accessible.
+If authentication or other steps are required to access the data, this should at least be described in the Collection or Item description.
+For a more machine-readable way implementors could also use other means, such as the [Authentication] extension.
+
+**Roles:** The role names specify the values to be used in the Asset's `roles`.
+Each of the assets can either be exposed individually or grouped together in any form.
+In the latter case the role names can simply be merged to a set of unique role names.
+Roles can also be combined for a single file.
+
+#### Data
+
+For non-metadata requirements that refer to how the data must be created and processed
+please consult the relevant CEOS-ARD specification.
+There can be one or multiple data assets per acquisition.
+
+For data assets, the following properties are relavant in the context of CEOS-ARD:
+
+| Field Name | Req.      | Description                                                  |
+| ---------- | --------- | ------------------------------------------------------------ |
+| roles      | *various* | **REQUIRED.** All data assets must to include the `data` role. |
 
 ## Notes
 
+- Req. 1.5 / 1.6 / 2.8: It is not clear how to specify the Acquisition ID Image
+  as the `derived_from` links don't contain a numeric indice. See also [#26].
+
 ...
+
+[#26]: <https://github.com/libbyrose/ceos-ard/issues/26>
+
 [CEOS-ARD product family specifications]: <http://ceos.org/ard/>
 [Combined CEOS-ARD for Synthetic Aperture Radar, version 1.0]: <https://ceos.org/ard/files/PFS/SAR/v1.0/CEOS-ARD_PFS_Synthetic_Aperture_Radar_v1.0.pdf>