About the Schema Reference

The vCloud API Schema Reference includes reference material for all elements, types, operations, and queries in the vCloud API. It also includes the schema definition files and a summary of changes to the schemas in this release.

The schema reference documentation is organized to reflect the division of the vCloud API into user, administrator, and extension categories. Within each category, you can open a list of elements, types that the elements extend, and operations that create, retrieve, update, or delete the objects that the elements represent. You can also open a list of queries in that category.

The schema reference provides its own search facility. You cannot search for schema reference content in the main Documentation Center search window.

User Operations, Elements, Types, and Queries

These operations and queries are accessible to all users who have permission to log into an organization. User elements and user types represent the objects that these operations manipulate.

Administrator Operations, Elements, Types, and Queries

These operations and queries are accessible to organization administrators or system administrators. Administrator elements and types represent the objects that these operations manipulate.

Extension Operations, Elements, Types, and Queries

These operations and queries are accessible to system administrators who need access to vSphere platform objects from the vCloud API. Extension elements and types represent the objects that these operations manipulate.

You can enter a search string in the Quick Index text box to search the lists of operations, elements, and types in any category.

In an Operations list, you can search for the following items:

All or part of the name of the object on which you want to operate. The search returns a list of all of the operations that are possible on that object. For example, selecting User Operations and typing vApp in the Quick Index text box returns a list of all of the requests that operate on a vApp object.

The name of an action to perform. For example, selecting User Operations and typing power in the Quick Index text box returns a list of all the requests that change the power state of a vApp.

An HTTP verb (GET, PUT, POST, DELETE) to view a list of all the requests that use that verb. For example, selecting User Operations and typing PUT in the Quick Index text box returns a list of all of the requests that update an object.

In an Elements or Types list, type all or part of the element or type name.

Search terms are not case-sensitive.

Operations consist of an HTTP verb and a request URL. The reference documentation represents the verb and the URL using the following syntax:

HTTP_VERB / object_type /{id}[/action/ action_name ]

In this syntax, the initial / character is assumed to follow a site-specific API URL, such as https://vcloud.example.com/api. The following strings represent variables in the remainder of the URL:

HTTP_VERB

The HTTP verb used to request the operation.

object_type

An abbreviation of the MIME type of the object referenced by the operation. This abbreviation is constructed from the final component of the object's media type, between the . and the +xml designation. For example, for an object whose media type is application/vnd.vmware.vcloud.catalogItem+xml , the object_type is shown as catalogItem .

{id}

The unique identifier of the object of the operation.

action_name

The name of an action. Required only when the operation request URL includes the string /action/ .

For each element or complex type, the reference documentation provides a page that lists the following items:

Element

The name of the element.

Type

The type of the element.

Namespace

The XML namespace in which this element or type name is defined.

Description

A description of the purpose and contents of the element or type.

Since

The vCloud API version in which this element or type first appeared.

Schema

The name of the XML schema definition file in which this element or type is defined. Click to open the file in your browser, or right-click to download it.

Media Type

The MIME type associated with this element or type.

Extends

The abstract base type from which this element's type is derived.

XML Representation

The XML representation of the element or type. Names of contained elements are links to the reference pages for those elements.

Attributes

A table listing the following properties of each attribute of the element or type:

Attribute

The name of the attribute.

Type

The primitive XML type of the attribute.

Required

Yes for attributes that are required. No for attributes that are optional.

Modifiable

The modification constraint for the attribute value, expressed in one of the following terms:

create

A client can modify the value on create.

update

A client can modify the value on update.

always

A client can modify the value on create or update.

none

A client cannot modify the value.

Since

The vCloud API version in which this attribute first appeared.

Deprecated

If use of this attribute is deprecated, the vCloud API version in which deprecation was announced.

Description

A description of the purpose and contents of the attribute.

Elements

A table listing the following properties of each element defined in the type:

Element

The name of the element.

Type

A link to the definition of the complex type that the element is based on.

Occurrence

The occurrence constraint for the element. The constraint can be one of the following expressions:

0..*

Optional. Can occur zero or more times.

0..1

Optional. Can occur at most once.

1

Required. Must occur exactly once.

Modifiable

The modification constraint for element contents, expressed in one of the following terms:

create

A client can modify the contents on create.

update

A client can modify the contents on update.

always

A client can modify the contents on create or update.

none

A client cannot modify the contents.

Since

The vCloud API version in which this element first appeared.

Deprecated

If use of this element is deprecated, the vCloud API version in which deprecation was announced.

Description

A description of the purpose and contents of the element.

Operations

A summary of the operations permitted on the element. Operations are categorized by request type; one of create, retrieve, update, and delete. This sequence of verbs is often abbreviated with the acronym CRUD.

Typed queries are are listed by name in alphabetical order. For each query category, the reference documentation provides a page that lists the following items:

Type Name The name of a query type in this category.
Description A description of the purpose of the query.
User YES means that this query is accessible to users.
Admin YES means that this query is accessible to organization administrators.
System YES means that this query is accessible to system administrators
Format Formats supported by the query.
Records Result The name of the container for the query result, and a link to the reference page for the type that represents each result in the container when the query format is records or idrecords. The type reference page lists all the attributes returned by the query, and can be a useful guide when creating filter expressions for queries.
Since The first vCloud API release that supported this query type.
Deprecated The first vCloud API release in which this query type was marked as deprecated.

You can download an archive of XML schema definition files (*.xsd) for the vCloud API. The archive includes two folders:

1.5

Schema definition files for vCloud API version 1.5 and later.

schemas

Additional schema definition files that are version-independent or from external sources such as DMTF.

The vCloud API Schema Differences Summary provides information on elements and attributes that are new, changed, or removed in this release.