Merge pull request #4 from stac-extensions/mah/alternate_as_dict

Make 'alternate' a dictionary

README.md

@@ -14,14 +14,15 @@ to access it.
 
 - Examples:
   - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item
+  - [Collection example](examples/collection.json): Shows usage in Collection assets and [item assets](https://github.com/stac-extensions/item-assets)
 - [JSON Schema](json-schema/schema.json)
 - [Changelog](./CHANGELOG.md)
 
 ## Asset Properties
 
 | Field Name           | Type                      | Description |
 | -------------------- | ------------------------- | ----------- |
-| alternate         | [[Asset Object](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#asset-object)] | An array of alternate location information for an asset |
+| alternate         | Map<string, [Asset Object](https://github.com/radiantearth/stac-spec/blob/master/item-spec/item-spec.md#asset-object)> | An array of alternate location information for an asset |
 
 The alternate Assets are like any other Asset object, except should 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 other fields if they do not specify
@@ -30,6 +31,22 @@ a different asset. Fields like `title` or `description` can be used to provide i
 Considering other extensions, the fields from the [Storage Extension](https://github.com/stac-extensions/storage) 
 could be used in an alternative asset to provide additional details on it's location.
 
+The key to each alternate asset, e.g.,
+
+```json
+"alternate": {
+  "s3": {
+    "href": "s3://bucket/key"
+  }
+}
+```
+
+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.
+
+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.
+
 ## Contributing
 
 All contributions are subject to the

examples/collection.json

@@ -0,0 +1,71 @@
+{
+  "stac_version": "1.0.0",
+  "stac_extensions": [
+    "https://stac-extensions.github.io/item-assets/v1.0.0/schema.json",
+    "https://stac-extensions.github.io/alternate-assets/v1.0.0/schema.json"
+  ],
+  "type": "Collection",
+  "id": "collection-1",
+  "title": "Ode to the Collection",
+  "description": "Mysterious",
+  "license": "Apache-2.0",
+  "extent": {
+    "spatial": {
+      "bbox": [
+        [
+          172.9,
+          1.3,
+          173,
+          1.4
+        ]
+      ]
+    },
+    "temporal": {
+      "interval": [
+        [
+          "2015-06-23T00:00:00Z",
+          null
+        ]
+      ]
+    }
+  },
+  "assets": {
+    "collection-data": {
+      "href": "https://example.com/collection/file.xyz",
+      "alternate": {
+        "s3": {
+          "title": "s3 Access",
+          "href": "s3://mycoolsat-bucket/collection/file.xyz"
+        }
+      }
+    }
+  },
+  "item_assets": {
+    "data": {
+      "roles": [
+        "data"
+      ],
+      "alternate": {
+        "s3": {
+          "title": "s3 Access"
+        }
+      }
+    }
+  },
+  "summaries": {
+    "datetime": {
+      "minimum": "2015-06-23T00:00:00Z",
+      "maximum": "2019-07-10T13:44:56Z"
+    }
+  },
+  "links": [
+    {
+      "href": "https://example.com/examples/collection.json",
+      "rel": "self"
+    },
+    {
+      "href": "https://example.com/examples/item.json",
+      "rel": "item"
+    }
+  ]
+}

examples/item.json

@@ -50,12 +50,12 @@
   "assets": {
     "data": {
       "href": "https://mycoolsat.com/examples/file.xyz",
-      "alternate": [
-        {
-          "title": "Mirror 1",
-          "href": "https://mycoolsat-mirror1.com/examples/file.xyz"
+      "alternate": {
+        "s3": {
+          "title": "s3 Access",
+          "href": "s3://mycoolsat-bucket/examples/file.xyz"
         }
-      ]
+      }
     }
   }
 }

json-schema/schema.json

@@ -45,13 +45,13 @@
             "assets": {
               "type": "object",
               "additionalProperties": {
-                "$ref": "#/definitions/assets"
+                "$ref": "#/definitions/asset"
               }
             },
             "item_assets": {
               "type": "object",
               "additionalProperties": {
-                "$ref": "#/definitions/assets"
+                "$ref": "#/definitions/item_asset"
               }
             }
           }
@@ -78,7 +78,7 @@
       }
     },
     "assets": {
-      "title": "Asset links",
+      "title": "Assets",
       "description": "Links to assets",
       "type": "object",
       "additionalProperties": {
@@ -92,13 +92,20 @@
       ],
       "properties": {
         "alternate": {
-          "type": "array",
-          "items": {
-            "type": "object",
+          "type": "object",
+          "additionalProperties": {
             "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/item.json#/definitions/asset"
           }
         }
       }
+    },
+    "item_asset": {
+      "type": "object",
+      "properties": {
+        "alternate": {
+          "type": "object"
+        }
+      }
     }
   }
 }