Overview

This page defines the Title Case Convention for CloudStack Object Types, provides context on where and when to use Title Case, and lists all official Object Types recognized in the platform.

The goal is to make references to key CloudStack objects consistent, readable, and clear, especially in user-facing text, logs, and documentation.

Why this change

We are standardizing how Object Types are referenced in Apache CloudStack code, logs, API documentation, and developer communication.

Historically, Object Type names (e.g. "instance", "network", "account") have been written inconsistently across code, logs, and API responses. For example, developers may refer to a "virtual machine", "VM", or "instance" interchangeably.

To improve clarity and consistency:

• The term Instance is now the official name for a CloudStack-managed virtual machine.
• The legacy term Virtual Machine may still appear in some API names and parameters for backward compatibility, but must not be used in new code, logs, or documentation.

The Title Case Convention ensures that when a word refers to a CloudStack Object Type, it is written as a proper noun (e.g. Instance, Network, User). When used in a generic or non-object sense, it remains lowercase.

Canonical Object Types (Work in Progress)

The following are the canonical CloudStack Object Types that should always appear in Title Case when referring to CloudStack model entities.

Note: API calls (e.g. listVirtualMachines, deployVirtualMachine) retain the older naming for compatibility.

Implementation Guidelines

1. Code and Logs

When writing or updating log messages, always use the correct Object Type name and capitalization.

// Incorrect
LOGGER.info("Failed to start virtual machine for account: " + accountId);

// Correct
LOGGER.info("Failed to start Instance for Account: " + accountId);

2. API Description

Ensure all API parameter and response field descriptions use the proper Object Type name and Title Case.

/////////////////////////////////////////////////////
//////////////// API parameters /////////////////////
/////////////////////////////////////////////////////

// Incorrect
@Parameter(name = ApiConstants.ACCOUNT, type = CommandType.LONG, description = "the account that owns this network.")
private Long account;

// Correct
@Parameter(name = ApiConstants.ACCOUNT, type = CommandType.LONG, description = "The Account that owns this Network.")
private Long account;

3. Code Comments

Use Title Case when describing Object relationships or model entities.

/**
 * Associates the Network with an Account and allocates IP addresses for Instances.
 */

4. Acronym Capitalization

Acronyms used in object names, UI labels, API field descriptions, and user-facing documentation must be written in UPPERCASE. This applies to commonly used technical acronyms such as:

• ID
• UUID
• IP
• VLAN
• VPC
• and other standardized acronyms

Examples:

• Account ID (not Account Id)
• Instance UUID (not Instance Uuid)
• IP Address (not Ip Address)
• VLAN Range (not Vlan Range)
• VPC Offering (not Vpc Offering)

Note:
This rule applies to object naming, UI text, and documentation.
It does not override the CloudStack coding-style guideline that discourages uppercase acronyms in Java variable and method names.

5. Documentation and UI

All references to CloudStack-managed objects in user-facing content; including CWIKI documentation, Admin UI strings, and API reference docs, should use the canonical Title Case name.

Notes for Contributors

• Always verify whether the term refers to a CloudStack Object Type before applying Title Case.

• Do not change API names or parameters that are public-facing or backward-compatible (e.g., deployVirtualMachine); only update descriptions, logs, and documentation.

• Use Instance instead of Virtual Machine or VM in all new code, messages, and documentation.

• Community feedback is welcome via mailing list or JIRA.