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.

How the Schema Reference Documentation is Organized

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. Reference pages for types and elements are collected in alphabetized folders for browsing. You can also 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.
Important

The schema reference includes reference topics for the entire vCloud API, including objects and operations that are inaccessible to vCloud Air tenants.

Searching In The Frame Set

In addition to searching using the Documentation Center Search window and navigating using the Documentation Center table of contents, you can also use the Schema Reference frame set, which provides its own search and navigation facilities. 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.

Operation Summary Syntax

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, when an object has media type application/vnd.vmware.vcloud.catalogItem+xml, the object_type is shown as catalogItem. Where the object_type is a virtual machine, it can be represented as either vApp/{id} or vApp/vm-{id}.

{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/ .

Element and Type Reference Pages

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.

Filter

For attributes in query responses, Yes means that this attribute can be used in a query filter expression.

Sort

For attributes in query responses, Yes means that this attribute can be used with a query sortAsc or sortDesc parameter to sort query results.

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.
Query Reference Pages

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 indicates how each attribute can be used when sorting or filtering query results.
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.
Schema Definition Files

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.
Schema Differences in This Release

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