Merge branch 'main' into m-mohr-patch-1

stac-extensions · Jul 9, 2024 · b061b75 · b061b75
2 parents 808bdbb + 42bad15
commit b061b75
Show file tree

Hide file tree

Showing 5 changed files with 177 additions and 115 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -6,9 +6,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+### Added
+
+- Added a new field `name` to the Alternate Asset Object
+
+### Changed
+
+- The fields `title` and `description` are inherited from STAC Common Metadata
+  - No minimum length for `title`
+  - A minimum length of 1 for `description`
+- At least one alternate asset is required
+
+### Fixed
+
+- Improved the JSON Schema to follow the written documentation
+
 ## [v1.1.0] - 2021-07-08
 
 ### Changed
+
 - No longer reference a STAC version
 - Alternate objects are not of type `Asset` but rather `AlternateAsset` which is just a restrictive version of an `Asset`
 

diff --git a/README.md b/README.md
@@ -3,13 +3,15 @@
 - **Title:** Alternate Assets
 - **Identifier:** <https://stac-extensions.github.io/alternate-assets/v1.1.0/schema.json>
 - **Field Name Prefix:** -
-- **Scope:** Asset
+- **Scope:** Item, Collection
 - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Pilot
 - **Owner**: @matthewhanson
 
-The Alternate Assets extension to STAC provides a way to specify alternate locations (e.g., URLs) for assets. Sometimes, assets can be retrieved
-via multiple methods. For example an asset on AWS may have a public facing http URL but also a direct access s3 URL. Or an asset is mirrored
-on multiple servers that have different URLs. The file the asset points to must always be exactly the same (i.e. both assets have the same checksum),
+The Alternate Assets extension to STAC provides a way to specify alternate locations (e.g., URLs) for assets.
+Sometimes, assets can be retrieved via multiple methods.
+For example an asset on AWS may have a public facing http URL but also a direct access s3 URL.
+Or an asset is mirrored on multiple servers that have different URLs.
+The file the asset points to must always be exactly the same (i.e. both assets have the same checksum and file size),
 but different protocols, authentication mechanisms or cloud services may be used to access it.
 
 - Examples:
@@ -18,20 +20,24 @@ but different protocols, authentication mechanisms or cloud services may be used
 - [JSON Schema](json-schema/schema.json)
 - [Changelog](./CHANGELOG.md)
 
-## Asset Properties
+## Fields
 
-| Field Name           | Type                      | Description |
-| -------------------- | ------------------------- | ----------- |
-| alternate         | Map<string, [AlternateAsset Object](#alternate-asset-object)> | An array of alternate location information for an asset |
+The fields in the table below can be used in these parts of STAC documents:
 
-The Alternate Assets are similar to the core Asset object, except only contain fields relevant to the location and access of the asset. 
-In the simplest case, the object consists of a single field, `href`, but could include a title or description to provide additional info
-regarding the alternate location or URL. 
-The fields from the [Storage Extension](https://github.com/stac-extensions/storage) could be used in an AlternateAsset to 
-provide additional details on it's location.
+- [ ] Catalogs
+- [ ] Collections
+- [ ] Item Properties (incl. Summaries in Collections)
+- [x] Assets (for both Collections and Items, incl. Item Asset Definitions in Collections)
+- [ ] Links
 
-The key to each alternate asset, e.g.,
+| Field Name | Type                                                           | Description |
+| ---------- | -------------------------------------------------------------- | ----------- |
+| alternate  | Map<string, [Alternate Asset Object](#alternate-asset-object)> | An array of alternate location information for an asset |
+| name       | string                                                         | A short name to distinguish the asset from the alternate assets. |
 
+Each alternate asset consists of a key and an Alternate Asset Object.
+
+Example:
 ```json
 "alternate": {
   "s3": {
@@ -40,19 +46,34 @@ The key to each alternate asset, e.g.,
 }
 ```
 
-should be used across all assets if from the same source. In other words, if all the assets
-in an Item are all available via s3 direct access, the key for all of them should be the same.
+The Alternate Asset Objects are similar to the
+[Asset Object](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#asset-object)
+as defined in the STAC Item Specification.
 
-It is also recommended that the [item assets](https://github.com/stac-extensions/item-assets)
-extension be used in Collections to convey to users what the options are for alternate access.
+The key should be used consistently across all assets (and items) if from the same source.
+In other words, if all the assets in an Item are all available via s3 direct access, the key for all of them should be the same.
 
 ### Alternate Asset Object
 
-| Field Name  | Type      | Description |
-| ----------- | --------- | ----------- |
-| href        | string    | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. |
-| title       | string    | The displayed title for clients and users. |
-| description | string    | A description of the Asset providing additional details, such as how it was processed or created. [CommonMark 0.29](http://commonmark.org/) syntax MAY be used for rich text representation. |
+The Alternate Asset Object are similar to the core Asset object, except only contain fields relevant to the location and access of the asset. 
+
+| Field Name  | Type   | Description |
+| ----------- | ------ | ----------- |
+| href        | string | **REQUIRED.** URI to the asset object. Relative and absolute URI are both allowed. |
+| name        | string | A short name to distinguish the alternate assets. |
+
+In the simplest case, the object consists of a single `href` field, but could include additional details regarding the alternate location or URL. 
+
+Some fields that are commonly provided:
+
+- `title` and `description` as specified in [STAC's Common Metadata](https://github.com/radiantearth/stac-spec/blob/master/item-spec/common-metadata.md#basics).
+- The [Storage Extension](https://github.com/stac-extensions/storage) could be used to provide additional details on its host or location.
+- The [Authentication Extension](https://github.com/stac-extensions/authentication) could provide details about specific authentication requirements.
+
+It is also recommended that the [Item Assets Definition](https://github.com/stac-extensions/item-assets)
+Extension is provided in Collections to convey to users what the options are for alternate access.
+
+The `name` field could potentially also be provided in the core Asset Object as a short name to distinguish them from the alternate assets.
 
 ## Contributing
 

diff --git a/examples/collection.json b/examples/collection.json
@@ -30,34 +30,41 @@
     }
   },
   "assets": {
-    "collection-data": {
-      "href": "https://example.com/collection/file.xyz",
+    "items": {
+      "href": "https://example.com/collection/items.zip",
+      "type": "application/zip",
+      "title": "A collection of all STAC Items as a ZIP file.",
+      "roles": [
+        "archive"
+      ],
+      "name": "Example Corp. HTTPS",
       "alternate": {
         "s3": {
-          "title": "s3 Access",
-          "href": "s3://mycoolsat-bucket/collection/file.xyz"
+          "href": "s3://mycoolsat-bucket/collection/items.zip",
+          "name": "Amazon S3"
+        },
+        "source": {
+          "href": "https://source.coop/example/collection/items.zip",
+          "name": "Source.coop HTTPS"
         }
       }
     }
   },
   "item_assets": {
     "data": {
+      "type": "image/tiff; application=geotiff",
       "roles": [
         "data"
       ],
+      "name": "HTTPS",
       "alternate": {
         "s3": {
-          "title": "s3 Access"
+          "name": "S3",
+          "description": "Access the files via regular Amazon AWS S3 tooling."
         }
       }
     }
   },
-  "summaries": {
-    "datetime": {
-      "minimum": "2015-06-23T00:00:00Z",
-      "maximum": "2019-07-10T13:44:56Z"
-    }
-  },
   "links": [
     {
       "href": "https://example.com/examples/collection.json",

diff --git a/examples/item.json b/examples/item.json
@@ -5,6 +5,7 @@
   ],
   "type": "Feature",
   "id": "item",
+  "collection": "collection-1",
   "bbox": [
     172.9,
     1.3,
@@ -45,18 +46,26 @@
     {
       "href": "https://mycoolsat.com/examples/item.json",
       "rel": "self"
+    },
+    {
+      "href": "./collection.json",
+      "rel": "collection",
+      "type": "application/json"
     }
   ],
   "assets": {
     "data": {
-      "href": "https://mycoolsat.com/examples/file.xyz",
+      "href": "https://mycoolsat.com/examples/file.tif",
+      "type": "image/tiff; application=geotiff",
       "roles": [
         "data"
       ],
+      "name": "HTTPS",
       "alternate": {
         "s3": {
-          "title": "s3 Access",
-          "href": "s3://mycoolsat-bucket/examples/file.xyz"
+          "href": "s3://mycoolsat-bucket/examples/file.tif",
+          "name": "S3",
+          "description": "Access the files via regular Amazon AWS S3 tooling."
         }
       }
     }