A library_model is a container for a set of items which represent a usable set of files. The Content Library Service allows for multiple libraries to be created with separate authorization and sharing policies.

Each library_model is a container for a set of content.library.item_model instances. Each item is a logical object in a library, which may have multiple files.

A library_model may be local or subscribed. A local library has its source of truth about items within this Content Library Service. Items may be added to or removed from the library. A local library may also be private or published. When published, the library is exposed by a network endpoint and can be used by another Content Library Service for synchronization. A private local library cannot be used for synchronization.

A subscribed library is a library which gets its source of truth from another library that may be across a network in another Content Library Service. A subscribed library may have a different name and metadata from the library to which it subscribes, but the set of library items is always the same as those in the source library. Library items cannot be manually added to a subscribed library -- they can only be added by adding new items to the source library.

An OVF library item is the basic building block for instantiating virtual machines from content library. It may contain one or multiple virtual machine templates. This structure provides a rich view of the virtual machines within the ovf container as well as information about to the ovf descriptor associated with the library item

It is valid for disk, virtual machine or virtual machine collection.

Using the authentication scheme information, a client invoking an API call from any service can figure out what kind of credentials are needed for that API call.

For an explanation of authentication information contained within component elements, see vapi.metadata.authentication.component.

For an explanation of authentication information contained within package elements, see vapi.metadata.authentication.package.

For an explanation of authentication information contained within service elements, see vapi.metadata.authentication.service.

One of the sources for metadata is the annotations present in the interface definition language. When an annotation is represented in the element_map, element_map describes the data specified in the arguments for the annotation.

For example, in @UnionCase(tag="tag", value="SELECT"), ElementMap describes the keyword arguments tag and value.

An operation accepts a list of parameters and returns a result or an error. The operation_result_info describes the result element of an operation.

In the interface definition language, API designers have the ability to include all the fields from one structure to another structure. This is done by using an annotation @Include on the structure in which we want to add the fields. If this annotation is present, the list of fields in the structure_info will also contain the fields that are being included. The annotation information is also retained in the vapi.metadata.metamodel.structure_info.metadata element as well.

• Field element in a structure element. See vapi.metadata.metamodel.structure_info.fields
• Parameter element in an operation element. See vapi.metadata.metamodel.operation_info.params
• Result element in an operation element. See vapi.metadata.metamodel.operation_info.output

• Built-in types: These are types present in the interface definition language type system. They are provided by the infrastructure.
• User defined named type: API designers can create custom types and use them for the typed elements. These types have a unique identifier.
• Generic type instantiation: The language infrastructure also provides generic types such as list, map, set and so on. An instantiation of one of these generic types could also be used for the typed elements.

For an explanation of privilege information contained within component elements, see vapi.metadata.privilege.component.

For an explanation of containment within operation elements, see vapi.metadata.privilege.service.operation.

For an explanation of privilege information contained within package elements, see vapi.metadata.privilege.package.

For an explanation of privilege information contained within service elements, see vapi.metadata.privilege.service.

A third party extension can define and implements it's own authentication mechanism and define a constant in a different IDL file.

Examples:

• Trying to create a new tag category when a tag category with the specified name already exists.
• Trying to create a new tag in tag category when a tag with the specified name already exists the tag category.
• Trying to create a LUN with a specific UUID on a node (for replication purposes) when a LUN with that UUID already exists on the node.
• Trying to create a file in a directory or move or copy a file to a directory when a file with that name already exists in the directory.

Examples:

• Trying to power on a virtual machine that is already powered on.

Some types of errors are caused by the value of one of the inputs to the operation, possibly due to an interaction with other inputs to the operation. This structure is intended to be used as the payload to identify those inputs when the operation reports errors like vapi.std.errors.invalid_argument or vapi.std.errors.not_found. See vapi.std.errors.error.data.

Examples:

• A user is monitoring the progress of the operation in a GUI and sees that it is likely to take longer than he is willing to wait and clicks the cancel button.
• A user invokes the operation using a command-line tool and decides that she didn't really want to invoke that operation, and presses CTRL-c.

Counterexamples:

• The client's connection to the server was closed. Reporting an error is pointless since the client will not receive the error response because the connection has been closed.
• The request is taking longer than some amount of time. The vapi.std.errors.timed_out error would be reported if the time was specified as part of the input or is documented in the API contract.

This error serves two purposes:

1. It is the error that clients in many programming languages can catch to handle all standard errors. Typically those clients will display one or more of the localizable messages from vapi.std.errors.error.messages to a human.
2. It is the error that operations can report when they need to report some error, but the error doesn't fit into any other standard error, and in fact the only reasonable way for a client to react to the error is to display the message(s) to a human.

Examples:

• Trying to disable snapshots on a virtual machine which has a snapshot.
• Trying to downgrade a license that has licensed features that are in use.

Some types of errors are caused by a problem with one or more files. This structure is intended to be used as the payload to identify those files when the operation reports errors like vapi.std.errors.not_found. See vapi.std.errors.error.data.

This error is reported by the API infrastructure, so it could occur in response to the invocation of any operation.

Examples:

• The operation returns a value whose type doesn't match the type type the operation says it should return.
• The operation reports an error that is not included in the list of errors the operation says that it can report.

This error is reported by the API infrastructure, so it could occur in response to the invocation of any operation. It may also be reported as the result of operation-specific validation.

Examples:

• A parameter has a value that is not of the expected type.
• A parameter has a value that is not in the required range.
• A parameter has a value that is not one of the specifically allowed strings.
• One field of a structure is the tag for a tagged union, and has a specific value but another field of the structure that is required to be specified when the tag has that value is not specified, or another field of the structure that is required to be unspecified when the tag has that value is specified.

Counterexamples:

• Trying to create a new tag in tag category when a tag with the specified name already exists the tag category. The vapi.std.errors.already_exists error would be used instead.
• Invoke the operation to retrieve information about a virtual machine, passing an id that does not identify an existing virtual machine. The vapi.std.errors.not_found error would be used instead.
• Attempt to put a virtual machine into a folder that can only contain hosts. The vapi.std.errors.invalid_element_type error would be used instead.
• Attempt to attach a SCSI virtual disk to an IDE port. The vapi.std.errors.invalid_element_type error would be used instead.

Examples:

• Attempt to move a host with a fault tolerant virtual machine out of a cluster (i.e. make the host a standalone host).
• Attempt to remove a host from a DRS cluster without putting the host into maintenance mode.

This error could be reported, for example, if an attempt is made to put an element into the wrong type of container.

Examples:

• Attempt to put a virtual machine into a folder that can only contain hosts.
• Attempt to attach a SCSI virtual disk to an IDE port.

• A parameter has a value that is not of the expected type. The vapi.std.errors.invalid_argument error would be used instead.

Examples:

• The XML in a SOAP request is not well-formed so the server cannot parse the request.
• The XML in a SOAP request is well-formed but does not match the structure required by the SOAP specification.
• A JSON-RPC request is not valid JSON.
• The JSON sent in a JSON-RPC request is not a valid JSON-RPC Request object.
• The Request object from a JSON-RPC request does not match the structure required by the API infrastructure.

Counterexamples:

• The parameter has a value that is not with the required range. The vapi.std.errors.invalid_argument error would be used instead.
• The name of the operation specified in the request doesn't not match any known operation. The vapi.std.errors.not_found error would be used instead.

Some transport protocols (for example JSON-RPC) include their own mechanism for reporting these kinds of errors, and the API infrastructure for a programming language may expose the errors using a language specific mechanism, so this error might not be used.

Examples:

• Trying to add a virtual device that cannot be hot plugged to a running virtual machine.
• Trying to upgrade the virtual hardware version for a suspended virtual machine.
• Trying to power off, reset, or suspend a virtual machine that is not powered on.

Counterexamples:

• Trying to power off a virtual machine that is in the process of being powered on. The vapi.std.errors.resource_busy error would be used instead.

Examples:

• Invoke the operation to retrieve information about a virtual machine, passing an id that does not identify an existing virtual machine.
• Invoke the operation to modify the configuration of a virtual nic, passing an id that does not identify an existing virtual nic in the specified virtual machine.
• Invoke the operation to remove a vswitch, passing an id that does not identify an existing vswitch.

Every API request specifies a service identifier and an operation identifier along with the parameters. If the API infrastructure is unable to find the requested service or operation it reports this error.

This error can be reported by the API infrastructure for any operation, but it is specific to the API infrastructure, and should never be reported by the implementation of any operation.

Examples:

• A client provides an invalid service or operation identifier when invoking the operation using a dynamic interface (for example REST).
• A client invokes the operation from a service, but that service has not been installed.

Counterexamples:

• A client invokes a task scheduling operation, but provides an invalid service identifier or operation identifier. The vapi.std.errors.not_found error would be used instead.

Examples:

• Trying to power off a virtual machine that is in the process of being powered on.

Counterexamples:

• Trying to remove a VMFS datastore when there is a virtual machine registered on any host attached to the datastore. The vapi.std.errors.resource_in_use error would be used instead.

Examples:

• Trying to remove a VMFS datastore when the is a virtual machine registered on any host attached to the datastore.
• Trying to add a virtual switch if the physical network adapter being bridged is already in use.

Counterexamples:

• Trying to power off a virtual machine that is in the process of being powered on. The vapi.std.errors.resource_busy error would be used instead.

Examples:

• Attempt to invoke some operation on a virtual machine when the virtual machine's configuration file is not accessible (for example due to a storage APD condition).

Counterexamples:

• Attempt to invoke some operation when the server is too busy. The vapi.std.errors.service_unavailable error would be used instead.
• Attempt to invoke some operation when the server is undergoing maintenance. The vapi.std.errors.service_unavailable error would be used instead.
• Some operation fails to contact VMware Tools running inside the virtual machine. The vapi.std.errors.service_unavailable error would be used instead.

Examples:

• Attempt to invoke a operation when the server is too busy.
• Attempt to invoke a operation when the server is undergoing maintenance.
• An operation fails to contact VMware Tools running inside the virtual machine.

Counterexamples:

• A client provides an invalid service or operation identifier when invoking the operation using a dynamic interface (for example REST). The vapi.std.errors.operation_not_found error would be used instead.
• A client invokes the operation from the service, but that service has not been installed. The vapi.std.errors.operation_not_found error would be used instead.

• provided by the client as an input parameter.
• a fixed limit of the service implementation that is a documented part of the contract of the service.
• a configurable limit used by the implementation of the service.
• a dynamic limit computed by the implementation of the service.

Examples:

• The operation was unable to complete within the timeout duration specified by a parameter of the operation.

Counterexamples:

• A server implementation that puts requests into a queue before dispatching them might delete a request from the queue if it doesn't get dispatched within n minutes. The vapi.std.errors.service_unavailable error would be used instead.

Some types of errors are transient in certain situtations and not transient in other situtations. This error payload can be used to indicate to clients whether a particular error is transient. See vapi.std.errors.error.data.

Examples:

• Trying to power on a virtual machine when there are not enough licenses to do so.
• Trying to power on a virtual machine that would violate a resource usage policy.

Counterexamples:

• Trying to power off a virtual machine that is in the process of being powered on. A vapi.std.errors.resource_busy error would be used instead.
• Trying to remove a VMFS datastore when the is a virtual machine registered on any host attached to the datastore. The vapi.std.errors.resource_in_use error would be used instead.
• Trying to add a virtual switch if the physical network adapter being bridged is already in use. The vapi.std.errors.resource_in_use error would be used instead.
• Attempt to invoke some operation on a virtual machine when the virtual machine's configuration file is not accessible (for example due to a storage APD condition). The vapi.std.errors.resource_inaccessible error would be used instead.

API requests may include a security context containing user credentials. For example, the user credentials could be a SAML token, a user name and password, or the session identifier for a previously established session.

Examples:

• The SAML token in the request's security context has expired.
• The user name and password in the request's security context are invalid.
• The session identifier in the request's security context identifies a session that has expired.

• The user is authenticated but isn't authorized to perform the requested operation. The vapi.std.errors.unauthorized error would be used instead.

For security reasons, the vapi.std.errors.error.data field in this error is unset, and the vapi.std.errors.error.messages field in this error does not disclose which part of the security context is correct or incorrect. For example the messages would not disclose whether a username or a password is valid or invalid, but only that a combination of username and password is invalid.

API requests may include a security context containing user credentials. For example, the user credentials could be a SAML token, a user name and password, or the session identifier for a previously established session. Invoking the operation may require that the user identified by those credentials has particular privileges on the operation or on one or more resource identifiers passed to the operation.

Examples:

• The operation requires that the user have one or more privileges on the operation, but the user identified by the credentials in the security context does not have the required privileges.
• The operation requires that the user have one or more privileges on a resource identifier passed to the operation, but the user identified by the credentials in the security context does not have the required privileges.

Counterexamples:

• The SAML token in the request's security context has expired. A vapi.std.errors.unauthenticated error would be used instead.
• The user name and password in the request's security context are invalid. The vapi.std.errors.unauthenticated error would be used instead.
• The session identifier in the request's security context identifies a session that has expired. The vapi.std.errors.unauthenticated error would be used instead.

For security reasons, the vapi.std.errors.error.data field in this error is unset, and the vapi.std.errors.error.messages field in this error does not disclose why the user is not authorized to perform the operation. For example the messages would not disclose which privilege the user did not have or which resource identifier the user did not have the required privilege to access. The API documentation should indicate what privileges are required.

Every operation expects parameters with known names. Some of those parameters may be (or contain) structures, and the operation expects those structures to contain fields with known names. If the operation receives parameters or fields with names that is does not expect, this error may be reported.

This error can be reported by the API infrastructure for any operation, but it is specific to the API infrastructure, and should never be reported by the implementation of any operation.

Examples:

• A client using stubs generated from the interface specification for version2 of a service invokes the operation passing one or more parameters that were added in version2, but they are communicating with a server that only supports version1 of the service.
• A client provides an unexpected parameter or field name when invoking the operation using a dynamic interface (for example REST).

Examples:

• Trying to hot-plug a CPU when the current configuration of the VM does not support hot-plugging of CPUs.
• Trying to change the memory size to a value that is not within the acceptable guest memory bounds supported by the virtual machine's host.

Typically the {vapi.std.errors.error.data field of this error will contain information that can be presented to a human to allow them to decide whether to trust the endpoint. If they decide to trust the endpoint, the request can be resubmitted with an indication that the endpoint should be trusted.

Examples:

• The client provides an IP address or URL of an endpoint the system should communicate with using an SSL connection, but the endpoint's SSL certificate is self-signed, expired, or otherwise not trustworthy.
• The client provides an IP address of a host the system should communicate with using ssh, but ssh doesn't recognize the public key of the host

The linux_configuration structure contains settings that identify a Linux machine in the same way that the vcenter.guest.windows_configuration structure identifies a Windows machine.

• Name
• Version
• Deployments
• Automatically Discovered or Manually Added

See deploy and filter.

This corresponds to the ovf:Configuration element of the ovf:DeploymentOptionSection in the specification. The ovf:DeploymentOptionSection specifies a discrete set of intended resource allocation configurations. This structure represents one item from that set.

See deploy and filter.

This information based on the ovf:DeploymentOptionSection.

See deploy and filter.

vmw:ExtraConfig elements may occur as direct child elements of a VirtualHardwareSection, or as child elements of individual virtual hardware items.

See deploy and filter.

vmw:ExtraConfig elements can be used to specify configuration settings that are transferred directly to the .vmx file.

The behavior of the vmw:ExtraConfig element is similar to the extraConfig property of the VirtualMachineConfigSpec object in the VMware vSphere API. Thus, the same restrictions apply, such as you cannot set values that could otherwise be set with other properties in the VirtualMachineConfigSpec object. See the VMware vSphere API reference for details on this.

See deploy and filter.

Ovf Property elements are exposed to the guest software through the OVF environment. Each Property element exposed in the OVF environment shall be constructed from the value of the ovf:key attribute. A Property element contains a key/value pair, it may optionally specify type qualifiers using the ovf:qualifiers attribute with multiple qualifiers separated by commas.

The settings in ip_allocation_params structure are global to a deployment. Thus, if a virtual machine is part of a virtual appliance, then its settings are ignored and the settings for the virtual appliance is used.

This information is based on the vmw:IpAssignmentSection in OVF package.

See deploy and filter.

These messages fall into different categories defined in vcenter.ovf.ovf_message.category:

• Describe information about a given OVF package.
• Describe default deployment configuration.
• Describe possible deployment values based on the deployment environment.
• Provide deployment-specific configuration.

Most OVF parameter structures provide both informational and deployment parameters. However, some are purely informational (for example, download size) and some are purely deployment parameters (for example, the flag to indicate whether registration as a vCenter extension is accepted).

See deploy and filter.

• Parsing and validation error on OVF descriptor (which is an XML document), manifest and certificate files.
• OVF descriptor generating and device error.
• Unexpected server error.

A property is uniquely identified by its [classid.]id[.instanceid] fully-qualified name (see vcenter.ovf.property.class_id, vcenter.ovf.property.id, and vcenter.ovf.property.instance_id). If multiple properties in an OVF package have the same fully-qualified name, then the property is excluded and cannot be set. We do warn about this during import.

See deploy and filter.

This is based on the ovf:ProductSection.

See deploy and filter.

It allows a virtual system collection to contain a set of children that are homogeneous with respect to a prototypical virtual system or virtual system collection. It shall cause the deployment function to replicate the prototype a number of times, thus allowing the number of instantiated virtual systems to be configured dynamically at deployment time.

This is based on the ovf2:ScaleOutSection.

See deploy and filter.

When deploying an OVF package, a deployment specific instance count can be specified (see vcenter.ovf.scale_out_group.instance_count.

This is based on the ovf2:ScaleOutSection.

See deploy and filter.

This information is based on the file references and the ovf:DiskSection in the OVF descriptor.

See deploy and filter.

See deploy and filter.

See deploy and filter.

This error serves two purposes:

1. It is the error that clients in many programming languages can catch to handle all standard errors. Typically those clients will display one or more of the localizable messages from vcenter.tokenservice.error.messages to a human.
2. It is the error that operations can report when they need to report some error, but the error doesn't fit into any other standard error, and in fact the only reasonable way for a client to react to the error is to display the message(s) to a human.