gistfile1.txt

base_keys: {
    'capacity_in_gb': 1000,
    'allocated_capacity_in_gb': 5,
    ...
    
capabilities: {
    'compression': {'capability_type': 'well_defined',
                    'default': 'true',
                    options: {'compression_type': ['lossy', 'lossless', 'special'],
                              'compression': ['true', 'false']}}

    'fireproof': {'capability_type': 'vendor-unique',
                  'default': 'true',
                  options: {}}

    'thin_provisioning': {'capability_type': 'well_defined',
                          'default': 'true',
                          options: {'thin_provisioning': ['true', 'false']}}

    'quality_of_service': {'capability_type': 'well_defined',
                           'default': 'true',
                           options: {'quality_of_service': ['true', 'false'],
                                     'vendor_keys': ['minIOPS', 'maxIOPS', 'burstIOPS']}}
    'persona': {'capability_type': 'vendor_unique',
                'default': 'GENERIC',
                'options': ["Generic",
                           "ONTAP-legacy",
                           "VMware",
                           "OpenVMS",
                           "HPUX",
                           "WindowsServer",
                           "Generic-ALUA",
                           "Generic-legacy",
                           "HPUX-legacy",
                           "AIX-legacy",
                           "EGENERA"]}
....

NOTE, not an exhaustive list, just examples.  There's also nothing from keeping a 
vendor reporting fewer or more keys, but the structure and information in the keys 
and the data structure must be strictly enforced.

Explanations:
base_keys are the base things we do today that have nothing to do with "options",
for example reporting capacities, backend_name etc.  These are not things that
have "options" per-say.  NOTE base_keys is not what I envision the name being,
we'll want something better than that but for now it's for illustration.

The "well_defined keys", indicate fairly standard base keys for Cinder backends.  We expect
most devices to report at least a standard "true/false" for these keys.

Let's look at "compression" here:
  This is a well defined key, we expect devices to report "true" or "false" regarding whether
  they support it or not.  In the case where not only does a device support it, but
  it can be configured, the option keys are listed under the "options" portion.  This is
  simply the <key-name> of the option, and a list of valid values that can be specified for it.
  NOTE, if the options key is empty ({}) that means there are NO options that can be set
  on that capability key.

The fireproof capability is a good example:
  This is a vendor-uniqe capability, and has a capability_type tag indicating as such.
  Also, note that the default is "true" and that there are NO options.  The example indicates
  that this device is ALWAYS fireproof, you can't change that, it just is, what it is.

The quality_of_service capability handles describes some corner cases for us:
  This key is a well_defined key, that's very customizable via options.  Well defined portion is
  whether the capability is supported or not (again true/false), again, some devices
  may allow deploying volumes with or without QoS on the same device, so you can specify
  that with <capability-key-name>=true|false.

  If a device doesn't support this (ie always true), then this entry is omitted.


  The other key piece is vendor_keys.  For those that allow additional special keys to
  set QoS those key names are provided in list format as valid keys that can be specified
  and set as related to Quality of Service.  NOTE!!!  We do not want or need to document
  all the possible values, options and description of these keys here.  That should be
  left out of this data structure.  Just presenting the valid keys should be enough,
  their meaning and valid values should be left to vendor/drier documentation (at least, and
  especially when it comes to vendor_unique keys).

The persona key is another good example of a vendor_unique capability:
  This is very much like QoS, and again, note that we're just providing what the valid
  values are for the "capability_type" key.

  You'll notice that the data-structure follows the settings you would put in your extra-specs.
  This particular case doesn't have any options other than the base key itself, so
  the structure is rather simple.
  
**  Seems everybody wants "description" in there as well; seems easy enough to add that entry and a brief description of wha the key does.