The vCloud API provides a general-purpose facility for associating user-defined metadata with an object. A system administrator or the owner of an object can use the metadata link in the object's representation to access object metadata.

The representations of most first-class objects in the vCloud API include a link to a Metadata element, which contains up to 1024 name=value pairs that the owner of an object can create, retrieve, update, and delete. It also contains an additional group of name=value pairs that are under the control of the system administrator.

Object metadata gives cloud operators and cloud tenants a flexible way to apply user-defined properties to objects and use property values to help integrate the use and management of those objects with a variety of applications. Object metadata is preserved when objects are copied, and can be included in query filter expressions (see Add a Metadata Filter to a Query).

The representation of any object that supports metadata includes a link that you can use to retrieve the object's Metadata element. This example shows the metadata link from an Org element.

<Link
   rel="down"
   type="application/vnd.vmware.vcloud.metadata+xml" 
   href="https://vcloud.example.com/api/org/26/metadata"/>

A Metadata element can contain up to 1024 MetadataEntry elements. Each MetadataEntry includes a single name=value pair, represented in its Key and TypedValue elements. Key names are specified by Key element contents. A key name is a UTF-8 (Unicode) string encoded as described in RFC3986 (pct-encoded).

The key name must be unique within the scope of the containing Metadata element. Because key names are implicitly qualified by the Domain value of the containing MetadataEntry, the two key names in this example are considered to be unique.

<Metadata
 ...
   <MetadataEntry>
      <Domain
         visibility="READONLY">SYSTEM</Domain>
      <Key>Foo</Key>
      ...   
   </MetadataEntry>
  <MetadataEntry>
      <Domain>GENERAL</Domain>
      <Key>Foo</Key>
      ...   
   </MetadataEntry>
</Metadata>

See Access Control for vCloud API Object Metadata for more information about the Domain element.

The type of a Value is expressed in the xsi:type attribute of the containing TypedValue element. Values have various restrictions, based on their type.

Metadata TypedValue Types

Type Name

Restrictions on Value

Size of Value

MetadataStringValue

UTF-8 character set. Strings longer than 1000 characters cannot be searched for in a query.

Depends on length of string.

MetadataNumberValue

Must be a signed 8-byte integer.

8 bytes

MetadataDateTimeValue

UTC date and time in the format defined by http://www.w3.org/TR/xmlschema-2/#http://www.w3.org/TR/xmlschema-2//dateTime. For example, 2012-06-18T12:00:00-05:00

8 bytes

MetadataBooleanValue

Must be one of: 1, 0, true, false

1 byte

The following rules apply when you update a Metadata element.

When the content of a Key element in the update does not match the content of an existing Key element in the same Domain, the MetadataEntry containing that Key is added to the Metadata element.

When the content of Key element in the update matches the content of an existing Key element in the same Domain, the MetadataEntry containing that Key is replaced.

The Domain element of a MetadataEntry controls access to that entry by users and system administrators. There are two access domains.

GENERAL

User access to metadata in the GENERAL domain is controlled by the user's rights to the object to which the Metadata is attached. The owner of the object can create, read, update, or delete any MetadataEntry in the GENERAL domain. A MetadataEntry that does not include a Domain element is considered to be in the GENERAL domain.

SYSTEM

Metadata in the SYSTEM domain can be created, updated, and deleted only by a system administrator. User access to metadata in the SYSTEM domain is controlled by the value of the visibility attribute of the Domain element.

Domain Visibility Attribute Values

Value

Meaning

PRIVATE

The metadata is visible to system administrators only.

READONLY

the metadata is visible to system administrators and the object owner.

The following limits apply to vCloud API object metadata:

Metadata key size

The contents of a Key element in a MetadataEntry cannot exceed 256 UTF-8 characters.

Metadata size

The size of all Metadata for an object, computed as the sum of all Key and TypedValue UTF-8 strings in all MetadataEntry elements in the GENERAL domain, cannot exceed 128 KB. An additional 16KB of MetadataEntry content can be created in the SYSTEM domain.

MetadataEntry limit

The total metadata associated with an object cannot exceed 1024 MetadataEntry elements in the GENERAL domain and 128 MetadataEntry elements in the SYSTEM domain.