12-Capability

Capability objects allow a CDMI™ client to discover what subset of the CDMI standard is implemented by a CDMI provider.

For each URI in a cloud storage system, the set of interactions that the system is capable of performing for that URI are described by the presence of named "capabilities". Each capability present for a given URI indicates what functionality the cloud storage system will allow against that URI. Capabilities are always static.

Capabilities may differ from the operations permitted by an Access Control List (ACL) (see 16.1) associated with a given URI‚ e.g., a read-only cloud may not permit write access to a container or object, despite the presence of an ACL allowing write access.

Cloud clients may use capabilities to discover what operations are supported. If an operation is attempted on a CDMI object that does not have a corresponding capability, an HTTP 400 status code shall be returned to the client. All CDMI-compliant cloud storage systems shall implement the ability to read capabilities, but support for the functionality indicated by each capability is optional.

Requirements throughout this international standard shall be understood in the context of CDMI capabilities. Mandatory requirements on functionality that is conditioned on a CDMI capability shall not be interpreted to require implementation of that capability, but rather shall be interpreted to apply only to implementations that support the functionality required by that capability.

Every CDMI data object, container object, domain object, and queue object shall have a capabilitiesURI field that contains a valid URI that points to a capabilities object. Within the capabilities object, the name of each capability confers a specific meaning that has been agreed to between the cloud storage provider and the cloud storage consumer.

The capabilities defined as part of this international standard are described later in Clause 12. Capabilities not listed in this standard shall not begin with the prefix "cdmi_", but are otherwise permitted so that cloud storage system implementors have the ability to extend the use of capabilities in ways that are outside the scope of this international standard.

Figure 7 shows the hierarchy of capabilities in an offering and how the capabilitiesURI links data objects and container objects into the capabilities tree.

The capabilities container within the capabilities tree to which an object is linked is based on the type of the object and the data system metadata fields present in the object.

EXAMPLE A container with no data system metadata fields specified may map to the "container" capabilities entry.

As an option, a CDMI implementation may map a container to a "gold_container" capabilities entry, if a data system metadata field is present and set to a given value, such as if the cdmi_data_redundancy field was set to the value of "4". This permits a cloud provider to create profiles of data system metadata fields and values.

Table 102 defines the system-wide capabilities in a cloud storage system. These capabilities, which are found in the capabilities object, are referred to by the root URI (root capabilities).

Capability Name	Type	Definition
cdmi_domains	JSON String	If present and "true", indicates that the cloud storage system supports domains. If not present, the domainURI field shall not be present in response bodies and the "cdmi_domains" URI shall not be present.
cdmi_export_cifs	JSON String	If present and "true", this capability indicates that the cloud storage system supports CIFS exports.
cdmi_dataobjects	JSON String	If present and "true", this capability indicates that the cloud storage system supports data objects.
cdmi_export_iscsi	JSON String	If present and "true", this capability indicates that the cloud storage system supports iSCSI exports.
cdmi_export_nfs	JSON String	If present and "true", this capability indicates that the cloud storage system supports NFS protocol exports.
cdmi_export_occi_iscsi	JSON String	If present and "true", this capability indicates that the cloud storage system supports OCCI/iSCSI exports.
cdmi_export_webdav	JSON String	If present and "true", this capability indicates that the cloud storage system supports WebDAV exports.
cdmi_metadata_maxitems	JSON String	If present, this capability indicates the maximum number of user-defined metadata items supported per object. If absent, there is no limit placed on the number of user-defined metadata items.
cdmi_metadata_maxsize	JSON String	If present, this capability indicates the maximum size, in bytes, of each user-defined metadata item supported per object. If absent, there is no limit placed on the size of user- defined metadata items.
cdmi_metadata_maxtotalsize	JSON String	If present, this capability indicates the maximum size, in bytes, of user-defined metadata supported by the cloud storage system. If absent, there is no limit placed on the size of user-defined metadata.
cdmi_notification	JSON String	If present and "true", this capability indicates that the cloud storage system supports notification queues.
cdmi_logging	JSON String	If present and "true", this capability indicates that the cloud storage system supports logging queues.
cdmi_query	JSON String	If present and "true", this capability indicates that the cloud storage system supports query queues.
cdmi_query_regex	JSON String	If present and "true", this capability indicates that the cloud storage system supports query with regular expressions.
cdmi_query_contains	JSON String	If present and "true", this capability indicates that the cloud storage system supports query with “contains” expressions.
cdmi_query_tags	JSON String	If present and "true", this capability indicates that the cloud storage system supports query with tag-matching expressions.
cdmi_query_value	JSON String	If present and "true", this capability indicates that the cloud storage system supports query of value fields.
cdmi_queues	JSON String	If present and "true", this capability indicates that the cloud storage system supports queue objects.
cdmi_security_access_control	JSON String	If present and "true", this capability indicates that the cloud storage system supports ACLs. See 12.1.3 for additional information.
cdmi_security_audit	JSON String	If present and "true", this capability indicates that the cloud storage system supports audit logging. See 20.4 for additional information.
cdmi_security_data_integrity	JSON String	If present and "true", this capability indicates that the cloud storage system supports data integrity/authenticity. See 12.1.3 for additional information.
cdmi_security_encryption	JSON String	If present and "true", this capability indicates that the cloud storage system supports data at-rest encryption. See 12.1.3 for additional information.
cdmi_security_immutability	JSON String	If present and "true", this capability indicates that the cloud storage system supports data immutability/retentions. See 12.1.3 for additional information.
cdmi_security_sanitization	JSON String	If present and "true", this capability indicates that the cloud storage system supports data/media sanitization. See 12.1.3 for additional information.
cdmi_serialization_json	JSON String	If present and "true", this capability indicates that the cloud storage system supports JSON as a serialization format.
cdmi_snapshots	JSON String	If present and “true”, this capability indicates that the cloud storage system supports snapshots.
cdmi_references	JSON String	If present and “true”, this capability indicates that the cloud storage system supports references.
cdmi_object_move_from_local	JSON String	If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects from URIs within the same storage system.
cdmi_object_move_from_remote	JSON String	If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects from URIs within other CDMI storage systems.
cdmi_object_move_from_ID	JSON String	If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects without a path from a /cdmi_objectid/ URI within the same storage system. This effectively adds a path, allowing the object to be accessed by ID and by path.
cdmi_object_move_to_ID	JSON String	If present and "true", this capability indicates that the cloud storage system supports moving CDMI objects with a path to a /cdmi_objectid/ URI within the same storage system. This effectively removes the path, leaving the object only accessible by ID.
cdmi_object_copy_from_local	JSON String	If present and "true", this capability indicates that the cloud storage system supports copying CDMI objects from URIs within the same storage system.
cdmi_object_copy_from_remote	JSON String	If present and "true", this capability indicates that the cloud storage system supports copying CDMI objects from URIs within other CDMI storage systems.
cdmi_object_access_by_ID	JSON String	If present and "true", this capability indicates that objects can be accessed, updated, and deleted through "/cdmi_objectid/”.
cdmi_post_dataobject_by_ID	JSON String	If present and "true", this capability indicates that the system allows a new data object by ID to be added via POST to "/cdmi_objectid/".
cdmi_post_queue_by_ID	JSON String	If present and "true", this capability indicates that the system allows a new queue object by ID to be added via POST to "/cdmi_objectid/".
cdmi_deserialize_dataobject_by_ID	JSON String	If present and "true", this capability indicates that the system allows the deserialization of serialized data objects when creating a new data object by ID via POST to "/cdmi_objectid/".
cdmi_deserialize_queue_by_ID	JSON String	If present and "true", this capability indicates that the system allows the deserialization of serialized queue objects when creating a new queue object by ID via POST to "/cdmi_objectid/".
cdmi_serialize_dataobject_to_ID	JSON String	If present and "true", this capability indicates that the system allows the serialization of data objects when creating a new data object by ID via POST to "/cdmi_objectid/".
cdmi_serialize_domain_to_ID	JSON String	If present and "true", this capability indicates that the system allows the serialization of domain objects when creating a new data object by ID via POST to "/cdmi_objectid/".
cdmi_serialize_container_to_ID	JSON String	If present and "true", this capability indicates that the system allows the serialization of container objects when creating a new data object by ID via POST to "/cdmi_objectid/".
cdmi_serialize_queue_to_ID	JSON String	If present and "true", this capability indicates that the system allows the serialization of queue objects when creating a new data object by ID via POST to "/cdmi_objectid/".
cdmi_copy_dataobject_by_ID	JSON String	If present and "true", this capability indicates that the system allows the copying an existing data object when creating a new data object by ID via POST to "/cdmi_objectid/".
cdmi_copy_queue_by_ID	JSON String	If present and "true", this capability indicates that the system allows the copying an existing queue object when creating a new queue object by ID via POST to "/cdmi_objectid/".
cdmi_create_reference_by_ID	JSON String	If present and "true", this capability indicates that the system allows the creation of a new reference by IDa new child reference to be created via POST to "/cdmi_objectid/".

Table 103 defines the capabilities for storage system metadata in a cloud storage system. These capabilities are found in the capabilities objects for domains, data objects, containers, and queues. See 16.3 for a description of these storage system metadata items.

Table 104 defines the capabilities for data system metadata in a cloud storage system. These capabilities are found in the capabilities objects for domains, data objects, containers, and queues. See 16.3 for a description of these data system metadata items.

Capability Name	Type	Definition
cdmi_assignedsize	JSON String	If present and "true", this capability indicates that the cloud storage system shall support assigned size for containers.
cdmi_data_redundancy	JSON String	If present, this capability specifies the maximum number of redundancy copies that may be specified. If absent, redundancy copies specified shall be ignored.
cdmi_data_dispersion	JSON String	If present and "true", this capability indicates that the cloud storage system shall disperse data. If absent, the dispersion specified shall be ignored.
cdmi_data_retention	JSON String	If present and "true", this capability indicates that the cloud storage system shall support retention.
cdmi_data_autodelete	JSON String	If present and “true”, this capability indicates that the cloud storage system shall support the autodeletion of objects when retention ends.
cdmi_data_holds	JSON String	If present and "true", this capability indicates that the cloud storage system shall support placing holds on objects. When a CDMI implementation supports holds for the purpose of making data immutable, the system-wide capability of “cdmi_security_immutability” specified in Table 102 of 12.1.1 shall be set to “true”. Otherwise, it shall not be present, indicating that there is no support for data immutability.
cdmi_encryption	JSON Array	If present, this capability shall list the encryption algorithms and key lengths supported. If absent, objects shall not be encrypted. When a CDMI implementation supports at-rest encryption, the system-wide capability of “cdmi_security_encryption” specified in Table 102 of Section 12.1.1 shall be set to “true”. Otherwise, it shall not be present, indicating that there is no support for at-rest encryption. Supported encryption algorithms are in the form of ALGORITHM_MODE_KEYLENGTH, where: • "ALGORITHM" is the encryption algorithm (e.g., "AES" or "3DES"). • "MODE" is the mode of operation (e.g.,"XTS", "CBC", or "CTR"). • "KEYLENGTH" is the key size (e.g.,"128","192", "256"). To improve interoperability between CDMI implementations, the following designators should be used for the more common encryption combinations: • “3DES_ECB_168” for the three-key Triple DES algorithm, the Electronic Code Book (ECB) mode of operation, and a key size of 168 bits; • “3DES_CBC_168” for the three-key Triple DES algorithm, the Cipher Block Chaining (CBC) mode of operation, and a key size of 168 bits; • "AES_CBC_128" for the AES algorithm, the CBC mode of operation, and a key size of 128 bits; • "AES_CBC_256" for the AES algorithm, the CBC mode of operation, and a key size of 256 bits; • "AES_XTS_128" for the AES algorithm, the XTS mode of operation, and a key size of 128 bits; and • "AES_XTS_256" for the AES algorithm, the XTS mode of operation, and a key size of 256 bits.
cdmi_geographic_placement	JSON String	If present and "true", this capability indicates that the cloud storage system shall enforce the geographic restriction of object placement.
cdmi_immediate_redundancy	JSON String	If present, this capability specifies the maximum number of immediate redundancy copies that may be specified. If absent, immediate redundancy copies specified shall be ignored.
cdmi_infrastructure_redundancy	JSON String	If present, this capability specifies the maximum number of infrastructure redundancy copies that may be specified. If absent, infrastructure redundancy copies specified shall be ignored.
cdmi_latency	JSON String	If present and "true", this capability indicates that the cloud storage system shall tier data based on desired latency. If absent, the max latency specified shall be ignored.
cdmi_RPO	JSON String	If present and "true", this capability indicates that the cloud storage system shall manage data to achieve a specified RPO. If absent, the RPO specified shall be ignored.
cdmi_RTO	JSON String	If present and "true", this capability indicates that the cloud storage system shall manage data to achieve a specified RTO. If absent, the RTO specified shall be ignored.
cdmi_sanitization_method	JSON Array	If present, this capability lists the sanitization methods supported. When a CDMI implementation supports sanitization, the system-wide capability of “cdmi_security_sanitization” specified in Table 102 of 12.1.1 shall be set to “true”. Otherwise, it shall not be present, indicating that there is no sanitization support.
cdmi_throughput	JSON String	If present and "true", this capability indicates that the cloud storage system shall tier data based on desired throughput. If absent, the max throughput specified shall be ignored.
cdmi_value_hash	JSON Array	If present, this capability shall list the hash algorithms and lengths supported. If absent, object values shall not be hashed. Values shall be in the form of "Algorithm Length”, e.g., "SHA256". When a CDMI implementation supports hashing, the system-wide capability of “cdmi_security_data_integrity” specified in Table 102 of 12.1.1 shall be set to “true”. Otherwise, it shall not be present, indicating that there is no support for hashing.

Capability Name	Type	Definition
cdmi_list_children	JSON String	If present and "true", this capability indicates that the container’s children may be listed.
cdmi_list_children_range	JSON String	If present and "true", this capability indicates that the container’s children may be listed with ranges.
cdmi_read_metadata	JSON String	If present and "true", this capability indicates that the container’s metadata may be read.
cdmi_modify_metadata	JSON String	If present and "true", this capability indicates that the container’s metadata may be modified.
cdmi_modify_deserialize_container	JSON String	If present and "true", this capability indicates that the container object permits the deserialization of a serialized container object into the container object as an update.
cdmi_snapshot	JSON String	If present and "true", this capability indicates that the container allows a new snapshot to be created.
cdmi_serialize_dataobject	JSON String	If present and "true", this capability indicates that the object may be serialized.
cdmi_serialize_container	JSON String	If present and "true", this capability indicates that the container and all children’s contents may be serialized.
cdmi_serialize_queue	JSON String	If present and "true", this capability indicates that the queue may be serialized.
cdmi_serialize_domain	JSON String	If present and "true", this capability indicates that the domain and all child domains may be serialized.
cdmi_deserialize_container	JSON String	If present and "true", this capability indicates that the container permits the deserialization of serialized containers and associated serialized children into the container
cdmi_deserialize_queue	JSON String	If present and "true", this capability indicates that the container permits the deserialization of serialized queues into the container.
cdmi_deserialize_dataobject	JSON String	If present and "true", this capability indicates that the container permits the deserialization of serialized data objects into the container.
cdmi_create_dataobject	JSON String	If present and "true", this capability indicates that the container allows a new object to be added.
cdmi_post_dataobject	JSON String	If present and "true", this capability indicates that the container allows a new object to be added via POST.
cdmi_post_queue	JSON String	If present and "true", this capability indicates that the container allows a new queue to be added via POST.
cdmi_create_container	JSON String	If present and "true", this capability indicates that the container allows a new container to be created via PUT.
cdmi_create_queue	JSON String	If present and "true", this capability indicates that the container allows queues to be created.
cdmi_create_reference	JSON String	If present and "true", this capability indicates that the container allows a new child reference to be created via PUT.
cdmi_cifs_export	JSON String	If present and "true", the container can be exported as a filesystem via CIFS
cdmi_nfs_export	JSON String	If present and "true", the container can be exported as a filesystem via NFS
cdmi_iscsi_export	JSON String	If present and "true", the container can be exported as a filesystem via iSCSI
cdmi_occi_export	JSON String	If present and "true", the container can be exported as a filesystem via OCCI
cdmi_delete_container	JSON String	If present and "true", this capability indicates that the container may be deleted.
cdmi_move_container	JSON String	If present and "true", this capability indicates that a container object may be moved into the container.
cdmi_copy_container	JSON String	If present and "true", this capability indicates that a container object may be copied into the container.
cdmi_move_dataobject	JSON String	If present and "true", this capability indicates that a data object may be moved into the container.
cdmi_copy_dataobject	JSON String	If present and "true", this capability indicates that a data object may be copied into the container.

Table 107 defines the capabilities for domains in a cloud storage system. (All capabilities refer to what may be done via CDMI content-type operations.)

Capability Name	Type	Definition
cdmi_create_domain	JSON String	If present and "true", this capability indicates that the domain allows a new subdomain to be added.
cdmi_delete_domain	JSON String	If present and "true", this capability indicates that the domain may be deleted.
cdmi_domain_summary	JSON String	If present and "true", this capability indicates that the domain supports domain summaries.
cdmi_domain_members	JSON String	If present and "true", this capability indicates that the domain supports domain user management.
cdmi_list_children	JSON String	If present and "true", this capability indicates that the domain's children may be listed.
cdmi_read_metadata	JSON String	If present and "true", this capability indicates that the domain's metadata may be read.
cdmi_modify_metadata	JSON String	If present and "true", this capability indicates that the domain's metadata may be modified.
cdmi_modify_deserialize_domain	JSON String	If present and "true", this capability indicates that the domain object permits the deserialization of a serialized domain object into the domain object as an update.
cdmi_copy_domain	JSON String	If present and "true", this capability indicates that the domain may be copied (via PUT) to another URI.
cdmi_deserialize_domain	JSON String	If present and "true", this capability indicates that the domain permits the deserialization of serialized domains and associated serialized children into the domain.

The representations in this clause are shown using JSON notation. Both clients and servers shall support UTF-8 JSON representation. The request and response body JSON fields may be specified or returned in any order, with the exception that, if present, for capability objects, the childrenrange and children fields shall appear last and in that order.

The following HTTP GET reads from an existing capability object at the specified URI.

The following capabilities describe the supported operations that may be performed when reading an existing capabilities object:

All CDMI implementations shall permit clients to read all fields of all capabilities objects.

The HTTP request headers for reading a CDMI capabilities object using CDMI content type are shown in Table 109.

The HTTP response headers for reading a CDMI capabilities object using CDMI content type are shown in Table 110.

The response message body fields for reading a CDMI capabilities object using CDMI content type are shown in Table 111.

Field Name	Type	Description	Requirement
objectType	JSON String	”application/cdmi-capability”	Mandatory
objectID	JSON String	Object ID of the object	Mandatory
objectName	JSON String	Name of the object • For objects in a container, the objectName field shall be returned. • For objects not in a container (objects that are only accessible by ID), the objectName field shall not be returned.	Mandatory
parentURI	JSON String	URI for the parent object • For objects in a container, the parentURI field shall be returned. • For objects not in a container (objects that are only accessible by ID), the parentURI field shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object.	Mandatory
parentID	JSON String	Object ID of the parent container object • For objects in a container, the parentID field shall be returned. • For objects not in a container (objects that are only accessible by ID), the parentID field shall not be returned. Appending the objectName to the parentURI shall always produce a valid URI for the object.	Mandatory
capabilities	JSON Object	The capabilities supported by the corresponding object. Capabilities in the "/cdmi_capabilities/" object are system-wide capabilities. Capabilities found in children objects under "/cdmi_capabilities/" correspond to the capabilities of a specific subset of objects. Each capability is expressed as a JSON string.	Mandatory
childrenrange	JSON String	The range of the children returned in the children field.	Mandatory
children	JSON Array	Names of the children capabilities objects. For the root container capabilities, this includes "domain/", "container/", "dataobject/", and "queue/". Within each of these capabilities objects, further more specialized capabilities profiles may be specified by the cloud storage system.	Mandatory

If individual fields are specified in the GET request, only these fields are returned in the result body. Optional fields that are requested but do not exist are omitted from the result body.

Table 112 describes the HTTP status codes that occur when reading a capabilities object using CDMI content type.

EXAMPLE 1 GET to the root container capabilities URI to read all fields of the container

EXAMPLE 2 GET to the root container capabilities URI to read the capabilities and children of the container

EXAMPLE 3 GET to the root container capabilities URI to read the first two children of the container

Capability Name	Type	Definition
cdmi_acl	JSON String	If present and "true", this capability indicates that the cloud storage system supports ACLs. When a CDMI implementation supports ACLs for the purpose of access control, the system-wide capability of “cdmi_security_access_control” specified in Table 103 of 12.1.1 shall be set to “true”. Otherwise, it shall not be present, indicating that there is no support for access control.
cdmi_size	JSON String	If present and "true", this capability indicates that the cloud storage system shall generate a "cdmi_size" storage system metadata for each stored object.
cdmi_ctime	JSON String	If present and "true", this capability indicates that the cloud storage system shall generate a "cdmi_ctime" storage system metadata for each stored object.
cdmi_atime	JSON String	If present and "true", this capability indicates that the cloud storage system shall generate an "cdmi_atime" storage system metadata for each stored object.
cdmi_mtime	JSON String	If present and "true", this capability indicates that the cloud storage system shall generate an "cdmi_mtime" storage system metadata for each stored object.
cdmi_acount	JSON String	If present and "true", this capability indicates that the cloud storage system shall generate an "cdmi_acount" storage system metadata for each stored object.
cdmi_mcount	JSON String	If present and "true", this capability indicates that the cloud storage system shall generate an "cdmi_mcount" storage system metadata for each stored object.

Capability Name	Type	Definition
cdmi_read_value	JSON String	If present and "true", this capability indicates that the object’s value may be read.
cdmi_read_value_range	JSON String	If present and "true", this capability indicates that the object’s value may be read with byte ranges.
cdmi_read_metadata	JSON String	If present and "true", this capability indicates that the object’s metadata may be read.
cdmi_modify_value	JSON String	If present and "true", this capability indicates that the object’s value may be modified.
cdmi_modify_value_range	JSON String	If present and "true",this capability indicates that the object’s value may be modified with byte ranges.
cdmi_modify_metadata	JSON String	If present and "true", this capability indicates that the object’s metadata may be modified.
cdmi_modify_deserialize_dataobject	JSON String	If present and "true", this capability indicates that the data object permits the deserialization of a serialized data object into the data object as an update.
cdmi_delete_dataobject	JSON String	If present and "true", this capability indicates that the object may be deleted.

Header	Type	Description	Requirement
Accept	Header String	"application/cdmi-capability". This header shall contain a list of one or more of the five CDMI MIME types (see RFC 6208).	Mandatory
X-CDMI-Specification-Version	String Array	A comma separated list of versions supported by the client, e.g., "1.0.1, 1.5, 2.0"	Mandatory

HTTP Status	Description
200 OK	Capabilities object list is in the response.
400 Bad Request	Invalid parameter or field names are in the request.
401 Unauthorized	There are incorrect or missing authentication credentials.
403 Forbidden	Client lacks the proper authorization to perform this request.
404 Not Found	A resource was not found at the specified URI.
406 Not Acceptable	The server is unable to provide the object in the content-type specified in the Accept header.