diff --git a/CHANGELOG.md b/CHANGELOG.md index 3487576..07592d6 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,9 +6,23 @@ 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 +- 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 index 97e7964..4a9eae9 100644 --- a/README.md +++ b/README.md @@ -7,10 +7,12 @@ - **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. In this case the asset is exactly the same, but different protocols or cloud services may be used -to access it. +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. +In this case the asset is exactly the same, but different protocols or cloud services may be used to access it. +The content of the asset should be the same, i.e., the checksum of the data should be the same as well as e.g. the media type or the file size. - Examples: - [Item example](examples/item.json): Shows the basic usage of the extension in a STAC Item @@ -20,18 +22,13 @@ to access it. ## Asset Properties -| Field Name | Type | Description | -| -------------------- | ------------------------- | ----------- | -| alternate | Map | An array of alternate location information for an asset | +| Field Name | Type | Description | +| ---------- | ---- | ----------- | +| alternate | Map | An array of alternate location information for an asset | -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. - -The key to each alternate asset, e.g., +Each alternate asset consists of a key and an Alternate Asset Object. +Example: ```json "alternate": { "s3": { @@ -40,19 +37,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 index 6c7a1ec..c8d600b 100644 --- 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 index bc0d9c8..7811c7e 100644 --- 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." } } } diff --git a/json-schema/schema.json b/json-schema/schema.json index 671ea52..c577230 100644 --- a/json-schema/schema.json +++ b/json-schema/schema.json @@ -3,129 +3,138 @@ "$id": "https://stac-extensions.github.io/alternate-assets/v1.1.0/schema.json#", "title": "Alternate Assets Extension", "description": "STAC Alternate Assets Extension for STAC Items and STAC Collections.", + "type": "object", + "required": ["stac_extensions"], + "properties": { + "stac_extensions": { + "type": "array", + "contains": { + "const": "https://stac-extensions.github.io/alternate-assets/v1.1.0/schema.json" + } + } + }, "oneOf": [ { "$comment": "This is the schema for STAC Items.", - "allOf": [ - { + "type": "object", + "required": ["type", "assets"], + "properties": { + "type": { + "const": "Feature" + }, + "assets": { "type": "object", - "required": [ - "type", - "assets" - ], "properties": { - "type": { - "const": "Feature" + "name": { + "$ref": "#/definitions/name" }, - "assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/alternate_assets" - } + "alternate": { + "$ref": "#/definitions/alternate_assets" } } - }, - { - "$ref": "#/definitions/stac_extensions" } - ] + } }, { "$comment": "This is the schema for STAC Collections.", - "allOf": [ - { + "type": "object", + "required": ["type"], + "properties": { + "type": { + "const": "Collection" + }, + "assets": { + "$ref": "#/definitions/assets" + }, + "item_assets": { "type": "object", - "required": [ - "type" - ], - "properties": { - "type": { - "const": "Collection" - }, - "assets": { - "type": "object", - "additionalProperties": { - "$ref": "#/definitions/alternate_assets" - } - }, - "item_assets": { - "type": "object", - "additionalProperties": { + "additionalProperties": { + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "alternate": { "$ref": "#/definitions/alternate_item_assets" } } } - }, - { - "$ref": "#/definitions/stac_extensions" } - ] + } } ], "definitions": { - "stac_extensions": { + "name": { + "type": "string", + "minLength": 1 + }, + "object_without_href": { "type": "object", - "required": [ - "stac_extensions" - ], "properties": { - "stac_extensions": { - "type": "array", - "contains": { - "const": "https://stac-extensions.github.io/alternate-assets/v1.1.0/schema.json" + "name": { + "$ref": "#/definitions/name" + } + }, + "allOf": [ + { + "$ref": "https://schemas.stacspec.org/v1.0.0/item-spec/json-schema/basics.json" + } + ] + }, + "assets": { + "type": "object", + "additionalProperties": { + "type": "object", + "properties": { + "name": { + "$ref": "#/definitions/name" + }, + "alternate": { + "$ref": "#/definitions/alternate_assets" } } } }, "alternate_assets": { - "title": "Assets", - "description": "Links to assets", "type": "object", - "properties": { - "alternate": { - "type": "object", - "additionalProperties": { + "minProperties": 1, + "additionalProperties": { + "allOf": [ + { + "$comment": "Require href in alternate assets in normal assets", + "type": "object", "required": ["href"], "properties": { "href": { - "title": "Asset reference", "type": "string", "format": "iri-reference", "minLength": 1 - }, - "title": { - "title": "Asset title", - "type": "string" - }, - "description": { - "title": "Asset description", - "type": "string" } } + }, + { + "$ref": "#/definitions/object_without_href" } - } + ] } }, "alternate_item_assets": { - "title": "Assets", - "description": "Links to assets", "type": "object", - "properties": { - "alternate": { - "type": "object", - "additionalProperties": { + "minProperties": 1, + "additionalProperties": { + "allOf": [ + { + "$comment": "Disallow href in alternate assets in item assets", + "type": "object", "properties": { - "title": { - "title": "Asset title", - "type": "string" - }, - "description": { - "title": "Asset description", - "type": "string" - } + "href": { + "not": {} + } } + }, + { + "$ref": "#/definitions/object_without_href" } - } + ] } } }