First draft for the CEOS ARD specific fields, migrated mostly from th…

…e CARD4L extension.
stac-extensions · Oct 17, 2023 · 8a00f66 · 8a00f66
1 parent 70b7191
commit 8a00f66
Show file tree

Hide file tree

Showing 6 changed files with 101 additions and 108 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -16,4 +16,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Fixed
 
-[Unreleased]: <https://github.com/stac-extensions/template/compare/v1.0.0...HEAD>
+[Unreleased]: <https://github.com/stac-extensions/ceos-ard/compare/v0.2.0...HEAD>
diff --git a/README.md b/README.md
@@ -1,20 +1,20 @@
-# Template Extension Specification
+# CEOS ARD Extension Specification
 
-- **Title:** Template
-- **Identifier:** <https://stac-extensions.github.io/template/v1.0.0/schema.json>
-- **Field Name Prefix:** template
+- **Title:** CEOS-ARD
+- **Identifier:** <https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json>
+- **Field Name Prefix:** ceos_ard
 - **Scope:** Item, Collection
 - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Proposal
-- **Owner**: @your-gh-handles @person2
+- **Owner**: @m-mohr
 
-This document explains the Template Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
-This is the place to add a short introduction.
+This document explains the CEOS-ARD Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
+It specifies how to create STAC Items and Collections that comply to the various CEOS ARD product family specifications.
 
 - Examples:
-  - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
-  - [Collection example](examples/collection.json): Shows the basic usage of the extension in a STAC Collection
-- [JSON Schema](json-schema/schema.json)
-- [Changelog](./CHANGELOG.md)
+  - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item (ToDo)
+  - [Collection example](examples/collection.json): Shows the basic usage of the extension in a STAC Collection (ToDo)
+- [JSON Schema](json-schema/schema.json) (ToDo)
+- [Changelog](./CHANGELOG.md) (ToDo)
 
 ## Fields
 
@@ -23,39 +23,69 @@ The fields in the table below can be used in these parts of STAC documents:
 - [ ] Catalogs
 - [x] Collections
 - [x] Item Properties (incl. Summaries in Collections)
-- [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
+- [ ] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
 - [ ] Links
 
-| Field Name           | Type                      | Description                                  |
-| -------------------- | ------------------------- | -------------------------------------------- |
-| template:new_field   | string                    | **REQUIRED**. Describe the required field... |
-| template:xyz         | [XYZ Object](#xyz-object) | Describe the field...                        |
-| template:another_one | \[number]                 | Describe the field...                        |
+| Field Name                     | Data Type | Description |
+| ------------------------------ | --------- | ----------- |
+| ceos_ard:specification         | string    | **REQUIRED.** The CARD4L product family specification implemented. |
+| ceos_ard:specification_version | string    | **REQUIRED.** The CEOS-ARD product family specification version. |
 
 ### Additional Field Information
 
-#### template:new_field
+#### ceos_ard:specification
 
-This is a much more detailed description of the field `template:new_field`...
+The following values are supported:
 
-### XYZ Object
+**Type 'Optical':**
+- `optical-ar`: Aquatic Reflectance
+- `optical-lidar-tcth`: LiDAR Terrain and Canopy Top Height
+- `optical-sr`: Surface Reflectance
+- `optical-st`: Surface Temperature
 
-This is the introduction for the purpose and the content of the XYZ Object...
+**Type 'Radar':**
+- `radar-gslc`: Geocoded Single-Look Complex (GSLC)
+- `radar-insar`: Interferometric Radar (INSAR)
+- `radar-nrb`: Normalised Radar Backscatter
+- `radar-orb`: Ocean Radar Backscatter
+- `radar-pr`: Polarimetric Radar
 
-| Field Name | Type   | Description                                  |
-| ---------- | ------ | -------------------------------------------- |
-| x          | number | **REQUIRED**. Describe the required field... |
-| y          | number | **REQUIRED**. Describe the required field... |
-| z          | number | **REQUIRED**. Describe the required field... |
+This field was named `card4l:specification` in the STAC CARD4L extension.
+The values translate as follows:
+- `SR` -> `optical-sr`
+- `ST` -> `optical-st`
+- `NRB` -> `radar-nrb`
+- `POL` -> `radar-pr`
+
+#### ceos_ard:specification_version
+
+At the time of writing this document the following versions are the latest versions.
+You can use older or newer versions, but the metadata mapping might not be complete.
+
+**Type 'Optical':**
+- `optical-ar`: 1.0
+- `optical-lidar-tcth`: Unreleased, reserved for future use
+- `optical-sr`: 5.0
+- `optical-st`: 5.0
+
+**Type 'Radar':**
+- `radar-gslc`: Unreleased, reserved for future use
+- `radar-insar`: Unreleased, reserved for future use
+- `radar-nrb`: 5.5
+- `radar-orb`: 1.0
+- `radar-pr`: 3.5
+
+This field was named `card4l:specification_version` in the STAC CARD4L extension.
+The field values can be copied as is.
 
 ## Relation types
 
 The following types should be used as applicable `rel` types in the
 [Link Object](https://github.com/radiantearth/stac-spec/tree/master/item-spec/item-spec.md#link-object).
 
-| Type           | Description                           |
-| -------------- | ------------------------------------- |
-| fancy-rel-type | This link points to a fancy resource. |
+| Type            | Description |
+| --------------- | ----------- |
+| card4l-document | **REQUIRED.** Provides at least one link to the CEOS-ARD product family specification document. Word (media type: `application/vnd.openxmlformats-officedocument.wordprocessingml.document`) and/or PDF (media type: `application/pdf`). |
 
 ## Contributing
 

diff --git a/examples/collection.json b/examples/collection.json
@@ -1,8 +1,7 @@
 {
   "stac_version": "1.0.0",
   "stac_extensions": [
-    "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json",
-    "https://stac-extensions.github.io/template/v1.0.0/schema.json"
+    "https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json"
   ],
   "type": "Collection",
   "id": "collection",
@@ -29,29 +28,11 @@
       ]
     }
   },
-  "template:new_field": "test",
-  "template:xyz": {
-    "x": 1,
-    "y": 2,
-    "z": 3
-  },
-  "template:another_one": [
-    1,
-    2,
-    3
-  ],
+  "ceos_ard:specification": "optical-sr",
+  "ceos_ard:specification_version": "5.0",
   "assets": {
     "example": {
-      "href": "https://example.com/examples/file.xyz",
-      "template:new_field": "test"
-    }
-  },
-  "item_assets": {
-    "data": {
-      "roles": [
-        "data"
-      ],
-      "template:new_field": "test"
+      "href": "https://example.com/examples/file.xyz"
     }
   },
   "summaries": {

diff --git a/examples/item.json b/examples/item.json
@@ -1,7 +1,7 @@
 {
   "stac_version": "1.0.0",
   "stac_extensions": [
-    "https://stac-extensions.github.io/template/v1.0.0/schema.json"
+    "https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json"
   ],
   "type": "Feature",
   "id": "item",
@@ -40,17 +40,8 @@
   },
   "properties": {
     "datetime": "2020-12-11T22:38:32Z",
-    "template:new_field": "test",
-    "template:xyz": {
-      "x": 1,
-      "y": 2,
-      "z": 3
-    },
-    "template:another_one": [
-      1,
-      2,
-      3
-    ]
+    "ceos_ard:specification": "optical-sr",
+    "ceos_ard:specification_version": "5.0"
   },
   "links": [
     {
@@ -60,8 +51,7 @@
   ],
   "assets": {
     "data": {
-      "href": "https://example.com/examples/file.xyz",
-      "template:new_field": "test"
+      "href": "https://example.com/examples/file.xyz"
     }
   }
 }
diff --git a/json-schema/schema.json b/json-schema/schema.json
@@ -1,8 +1,8 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
-  "$id": "https://stac-extensions.github.io/template/v1.0.0/schema.json#",
-  "title": "Template Extension",
-  "description": "STAC Template Extension for STAC Items and STAC Collections.",
+  "$id": "https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json",
+  "title": "CEOS-ARD Extension",
+  "description": "STAC CEOS-ARD Extension for STAC Items and STAC Collections.",
   "oneOf": [
     {
       "$comment": "This is the schema for STAC Items. Remove this object if this extension only applies to Collections.",
@@ -26,7 +26,8 @@
                 {
                   "$comment": "Require fields here for Item Properties.",
                   "required": [
-                    "template:new_field"
+                    "ceos_ard:specification",
+                    "ceos_ard:specification_version"
                   ]
                 },
                 {
@@ -70,7 +71,8 @@
             {
               "$comment": "Require fields here for Collections (top-level).",
               "required": [
-                "template:new_field"
+                "ceos_ard:specification",
+                "ceos_ard:specification_version"
               ]
             },
             {
@@ -152,55 +154,45 @@
         "stac_extensions": {
           "type": "array",
           "contains": {
-            "const": "https://stac-extensions.github.io/template/v1.0.0/schema.json"
+            "const": "https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json"
           }
         }
       }
     },
     "require_any_field": {
       "$comment": "Please list all fields here so that we can force the existence of one of them in other parts of the schemas.",
       "anyOf": [
-        {"required": ["template:new_field"]},
-        {"required": ["template:xyz"]},
-        {"required": ["template:another_one"]}
+        {"required": ["ceos_ard:specification"]},
+        {"required": ["ceos_ard:specification_version"]}
       ]
     },
     "fields": {
       "$comment": "Add your new fields here. Don't require them here, do that above in the corresponding schema.",
       "type": "object",
       "properties": {
-        "template:new_field": {
-          "type": "string"
-        },
-        "template:xyz": {
-          "type": "object",
-          "required": [
-            "x",
-            "y",
-            "z"
-          ],
-          "properties": {
-            "x": {
-              "type": "number"
-            },
-            "y": {
-              "type": "number"
-            },
-            "z": {
-              "type": "number"
-            }
-          }
+        "ceos_ard:specification": {
+          "type": "string",
+          "enum": [
+            "optical-ar",
+            "optical-lidar-tcth",
+            "optical-sr",
+            "optical-st",
+            "radar-gslc",
+            "radar-insar",
+            "radar-nrb",
+            "radar-orb",
+            "radar-pr"
+          ]
         },
-        "template:another_one": {
-          "type": "array",
-          "items": {
-            "type": "number"
-          }
+        "ceos_ard:specification_version": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^\\d+\\.\\d+$"
         }
       },
       "patternProperties": {
-        "^(?!template:)": {
-          "$comment": "Above, change `template` to the prefix of this extension"
+        "^(?!ceos_ard:)": {
+          "$comment": "Above, change `ceos_ard` to the prefix of this extension"
         }
       },
       "additionalProperties": false

diff --git a/package.json b/package.json
@@ -1,11 +1,11 @@
 {
-  "name": "stac-extension-template",
-  "version": "1.0.0",
+  "name": "stac-ceos-ard",
+  "version": "0.2.0",
   "scripts": {
     "test": "npm run check-markdown && npm run check-examples",
     "check-markdown": "remark . -f -r .github/remark.yaml",
-    "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json",
-    "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/template/v1.0.0/schema.json=./json-schema/schema.json"
+    "check-examples": "stac-node-validator . --lint --verbose --schemaMap https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json=./json-schema/schema.json",
+    "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/ceos-ard/v0.2.0/schema.json=./json-schema/schema.json"
   },
   "dependencies": {
     "remark-cli": "^12.0.0",
Original file line number	Diff line number	Diff line change
Expand Up		@@ -16,4 +16,4 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0

		### Fixed

		[Unreleased]: <https://github.com/stac-extensions/template/compare/v1.0.0...HEAD>
		[Unreleased]: <https://github.com/stac-extensions/ceos-ard/compare/v0.2.0...HEAD>