Document suggested region names per cloud provider as best practice

[kylebarron]

In terms of implementing a client that understands this extension, it's great that storage:platform is an enum, but unfortunate that storage:region is any string. I agree the regions from each platform are too many and can change too frequently to encode in the JSON Schema an enum restriction, but it would be great if we could have a "Best Practices" section of the extension documentation that lists suggested string values for each platform.

For example, regions in AWS could be described either as us-west-2 or US West (Oregon), and right now there's no section that recommends the former. It would be great if we could explicitly suggest the former, with a link to a web document or CLI command with the most updated list of available names. For example in AWS that could be

> aws ec2 describe-regions --all-regions | jq '.Regions[].RegionName'
"af-south-1"
"eu-north-1"
"ap-south-1"
"eu-west-3"
"eu-west-2"
"eu-south-1"
"eu-west-1"
"ap-northeast-3"
"ap-northeast-2"
"me-south-1"
"ap-northeast-1"
"sa-east-1"
"ca-central-1"
"ap-east-1"
"ap-southeast-1"
"ap-southeast-2"
"eu-central-1"
"us-east-1"
"us-east-2"
"us-west-1"
"us-west-2"

[matthewhanson]

Excellent point. I do wish we could make it an Enum, but as you said between different regions and keeping up to date it's problematic.

I think the best approach here would be to have a Best Practices section on each Provider in the README that can state what the valid regions are (or how to get them), what to use as a URL protocol (e.g., gs for google storage, s3, etc.) and other important notes (e.g., Azure doesn't have requester pays).

This doesn't change anything in the spec so we're free to update the README anytime without having to issue a new version.

[m-mohr]

I believe we should split this extension into a generic storage extension and a couple of sub-extensions that are provider dependent and each provider can suggest a platform name and allowed values for the different generic fields. That makes it a bit simpler to manage everything, I hope. The AWS S3 sub-schema could then at least validate something like /^[a-z]{2}-[a-z]{4,}-\d+$/ or so.

[m-mohr]

I think we can't ever solve this issue here. Even if we add an AWS extension that is based on this extension and adds an enum for the region on top, is this really good? AWS adds regions all the time and the extension would like always be outdated once AWS changes something. So I'm tempted to close this issue. Thoughts @kylebarron ?

[m-mohr]

In #24 this could be listed per provider in the respective provider documents/best practices.