diff --git a/json-schema/radar/product.json b/json-schema/radar/product.json new file mode 100644 index 0000000..077404a --- /dev/null +++ b/json-schema/radar/product.json @@ -0,0 +1,3 @@ +{ + +} \ No newline at end of file diff --git a/json-schema/radar/source.json b/json-schema/radar/source.json new file mode 100644 index 0000000..077404a --- /dev/null +++ b/json-schema/radar/source.json @@ -0,0 +1,3 @@ +{ + +} \ No newline at end of file diff --git a/radar.md b/radar.md index d76ac7c..9524149 100644 --- a/radar.md +++ b/radar.md @@ -1,7 +1,9 @@ # CEOS-ARD for Radar data - **Title:** CEOS-ARD for Radar -- **Identifier:** +- **Identifier:** + - Product: + - Source(s): - **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]: + [CEOS-ARD product family specifications]: [Combined CEOS-ARD for Synthetic Aperture Radar, version 1.0]: