Add type field and validation

README.md

@@ -5,7 +5,7 @@
 - **Field Name Prefix:** storage
 - **Scope:** Item, Catalog, Collection
 - **Extension [Maturity Classification](https://github.com/radiantearth/stac-spec/tree/master/extensions/README.md#extension-maturity):** Pilot
-- **Owner**: @davidraleigh @matthewhanson
+- **Owner**: @matthewhanson @m-mohr
 
 This document explains the Storage Extension to the [SpatioTemporal Asset Catalog](https://github.com/radiantearth/stac-spec) (STAC) specification.
 It allows adding details related to cloud object storage access and costs to be associated with STAC Assets.
@@ -53,6 +53,7 @@ The fields in the table below can be used in these parts of STAC documents:
 
 | Field Name     | Type    | Description |
 | -------------- | ------- | ----------- |
+| type           | string  | **REQUIRED.** Type identifier for the platform, see below. |
 | platform       | string  | **REQUIRED.** The cloud provider where data is stored as URI or URI template to the API. |
 | region         | string  | The region where the data is stored. Relevant to speed of access and inter region egress costs (as defined by PaaS provider). |
 | requester_pays | boolean | Is the data "requester pays" (`true`) or is it "data manager/cloud provider pays" (`false`). Defaults to `false`. |
@@ -65,11 +66,12 @@ The properties `title` and `description` as defined in Common Metadata should be
 The `platform` field identifies the cloud provider where the data is stored as URI or URI template to the API of the service.
 
 If a URI template is provided, all variables must be defined in the Storage Scheme Object as a property with the same name.
-For example, the URI template `https://{bucket}.{region}.example.com` must have at least the properties 
+For example, the URI template `https://{bucket}.{region}.example.com` must have at least the properties
 `bucket` and `region` defined:
 
 ```json
 {
+  "type": "example",
   "platform": "https://{bucket}.{region}.example.com",
   "region": "eu-fr",
   "bucket": "john-doe-stac",
@@ -82,19 +84,27 @@ the `platform` property must identify the host so that the URL can be resolved w
 For example, this is especially useful to provide the endpoint URL for custom S3 providers.
 In this case the `platform` could effectively provide the endpoint URL.
 
+#### type
+
 We try to collect pre-defined templates and best pratices for as many providers as possible
-in this repository, but be aware that these are not part of the official extension releases
-and are not validated. This extension just provides the framework, the provider best pratices
+in this repository, but be aware that these are not part of the official extension releases.
+This extension just provides the framework, the provider best pratices
 may change at any time without a new version of this extension being released.
 
 The following providers have defined best pratices at this point:
 
-- [AWS S3](platforms/aws-s3.md)
-- [Generic S3 (non-AWS)](platforms/custom-s3.md)
-- [Microsoft Azure](platforms/ms-azure.md)
+| `type`      | Provider and Documentation |
+| ----------- | -------------------------- |
+| `aws-s3`    | [AWS S3](platforms/aws-s3.md) |
+| `custom-s3` | [Generic S3 (non-AWS)](platforms/custom-s3.md) |
+| `ms-azure`  | [Microsoft Azure](platforms/ms-azure.md) |
 
 Feel encouraged to submit additional platform specifications via Pull Requests.
 
+The `type` fields can be any value chosen by the implementor,
+but the types defined in the table above should be used as defined in the best practices.
+This ensures proper schema validation.
+
 ## Contributing
 
 See the [Contributor documentation](CONTRIBUTING.md) for details.

examples/catalog-link.json

@@ -9,6 +9,7 @@
   "description": "An example catalog with a link to documentation on object storage.",
   "storage:schemes": {
     "aws": {
+      "type": "aws-s3",
       "platform": "https://{bucket}.s3.{region}.amazonaws.com",
       "bucket": "mybucket",
       "region": "us-west-2",

examples/collection.json

@@ -11,6 +11,7 @@
   "license": "CC-0",
   "storage:schemes": {
     "aws": {
+      "type": "aws-s3",
       "platform": "https://{bucket}.s3.{region}.amazonaws.com",
       "bucket": "mybucket",
       "region": "us-west-2",

examples/item-naip.json

@@ -43,21 +43,23 @@
   "properties": {
     "datetime": "2016-09-28T00:00:00+00:00",
     "mission": "NAIP",
-    "platform": "UNKNOWN_PLATFORM",
     "gsd": 1,
     "storage:schemes": {
       "az-wus2-ar": {
+        "type": "ms-azure",
         "platform": "https://{account}.blob.core.windows.net",
         "account": "jon-doe-123",
         "region": "westus2"
       },
       "aws-std": {
+        "type": "aws-s3",
         "platform": "https://{bucket}.s3.{region}.amazonaws.com",
         "bucket": "naip-visualization",
         "region": "us-west-2",
         "requester_pays": true
       },
       "minio": {
+        "type": "custom-s3",
         "platform": "https://play.min.io:9000"
       }
     }

json-schema/platforms/aws-s3.json

@@ -0,0 +1,29 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stac-extensions.github.io/storage/v2.0.0/platforms/aws-s3.json",
+  "title": "AWS S3",
+  "type": "object",
+  "if": {
+    "properties": {
+      "type": {
+        "const": "aws-s3"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "platform": {
+        "const": "https://{bucket}.s3.{region}.amazonaws.com"
+      },
+      "bucket": {
+        "$comment": "See https://docs.aws.amazon.com/AmazonS3/latest/userguide/bucketnamingrules.html",
+        "type": "string",
+        "pattern": "^[a-z0-9][a-z0-9-.]{1,61}[a-z0-9]$"
+      },
+      "region": {
+        "type": "string",
+        "pattern": "^[a-z0-9-]+$"
+      }
+    }
+  }
+}

json-schema/platforms/custom-s3.json

@@ -0,0 +1,16 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stac-extensions.github.io/storage/v2.0.0/platforms/custom-s3.json",
+  "title": "Generic S3",
+  "type": "object",
+  "if": {
+    "properties": {
+      "type": {
+        "const": "custom-s3"
+      }
+    }
+  },
+  "then": {
+    "$comment": "No specific validation rules apply"
+  }
+}

json-schema/platforms/ms-azure.json

@@ -0,0 +1,23 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://stac-extensions.github.io/storage/v2.0.0/platforms/ms-azure.json",
+  "title": "Microsoft Azure",
+  "type": "object",
+  "if": {
+    "properties": {
+      "type": {
+        "const": "ms-azure"
+      }
+    }
+  },
+  "then": {
+    "properties": {
+      "platform": {
+        "const": "https://{account}.blob.core.windows.net"
+      },
+      "account": {
+        "type": "string"
+      }
+    }
+  }
+}

json-schema/schema.json

@@ -96,9 +96,14 @@
           "patternProperties": {
             "^.{1,}$": {
               "required": [
+                "type",
                 "platform"
               ],
               "properties": {
+                "type": {
+                  "title": "Type identifier",
+                  "type": "string"
+                },
                 "platform": {
                   "title": "Platform",
                   "type": "string",
@@ -115,6 +120,17 @@
                   "default": false
                 }
               },
+              "allOf": [
+                {
+                  "$ref": "./platforms/aws-s3.json"
+                },
+                {
+                  "$ref": "./platforms/custom-s3.json"
+                },
+                {
+                  "$ref": "./platforms/ms-azure.json"
+                }
+              ],
               "additionalProperties": true
             }
           },

package.json

@@ -4,8 +4,8 @@
   "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/storage/v2.0.0/schema.json=./json-schema/schema.json",
-    "format-examples": "stac-node-validator . --format --schemaMap https://stac-extensions.github.io/storage/v2.0.0/schema.json=./json-schema/schema.json"
+    "check-examples": "stac-node-validator examples --verbose --lint --config ./validator-config.json",
+    "format-examples": "stac-node-validator examples --format --config ./validator-config.json"
   },
   "dependencies": {
     "remark-cli": "^8.0.0",
@@ -15,6 +15,6 @@
     "remark-preset-lint-markdown-style-guide": "^3.0.0",
     "remark-preset-lint-recommended": "^4.0.0",
     "remark-validate-links": "^10.0.0",
-    "stac-node-validator": "^1.1.0"
+    "stac-node-validator": "^2.0.0-beta.12"
   }
 }

validator-config.json

@@ -0,0 +1,8 @@
+{
+  "schemaMap": {
+    "https://stac-extensions.github.io/storage/v2.0.0/schema.json": "./json-schema/schema.json",
+    "https://stac-extensions.github.io/storage/v2.0.0/platforms/aws-s3.json": "./json-schema/platforms/aws-s3.json",
+    "https://stac-extensions.github.io/storage/v2.0.0/platforms/custom-s3.json": "./json-schema/platforms/custom-s3.json",
+    "https://stac-extensions.github.io/storage/v2.0.0/platforms/ms-azure.json": "./json-schema/platforms/ms-azure.json"
+  }
+}