Each package must contain a well-formed XML file named
APP-META.xml in the
package root directory.
APP-META.xml is a UTF-8 encoded XML file that contains all package metadata in accordance with the rules described in
The XML namespace of the metadata will be changed when incompatible changes are introduced in APS.
An example of an application metadata file is as follows:
<application xmlns="http://aps-standard.org/ns/2" version="2.0"> <id>http://aps-standard.org/samples/async1pn</id> <name>Sample Notification Management</name> <version>1.0</version> <release>1.15</release> <vendor> <name>APS team</name> <homepage>http://dev.apsstandard.org/</homepage> </vendor> <packager> <name>APS team</name> <homepage>http://dev.apsstandard.org/</homepage> </packager> <presentation> <summary>Basic multi-tenant application with async provisioning and notification. </summary> <icon path="images/ox_logo.jpg"/> </presentation> <license-agreement must-accept="true"> <free/> <text> <name>End-User License Agreement</name> <file>http://opensource.org/licenses/bsd-license</file> </text> </license-agreement> <upgrade match="version =ge=1.0, release =ge=0" /> <service id="clouds"> <code engine="php" path="scripts/clouds.php"/> <presentation> <name>VPS cloud globals</name> <summary>VPS cloud application global service</summary> <infolinks> <link href="http://doc.apsstandard.org/pa/demo-projects/dbasic1p/" class="deployment-guide">Demo project description </link> <link href="http://dev.apsstandard.org/develop/rt/tickets/new/" class="support">APS support </link> </infolinks> </presentation> </service> <privileges> <privilege area="clients" name="vps-manage" title="VPSes"/> </privileges> </application>
The following sections contain explanation of the elements.
A package must declare the version of the APS specification it complies with. This is done with the help of the version attribute.
<application xmlns="http://aps-standard.org/ns/2" version="2.0"> ... </application>
The version of the APS format specified here is
2.0. The numbering scheme for the APS format
major.minor. The major and minor numbers must be treated as separate integers
and each number MAY be incremented to more than one digit. Thus, APS 2.10 would be a
higher version than APS 2.0. Leading zeros (for example, APS 2.01 ) must be ignored by
APS controllers and must not be specified.
Optimally, a package uses APS version 2.0 or higher.
A package should declare the packaging date with the help of the
There is no need to add it manually. The package compiler adds this attribute automatically.
<application xmlns="http://aps-standard.org/ns/2" version="2.0" packaged="2012-01-01T09:00:00+06:00"> </application>
All user-visible strings in the metadata descriptor are localizable. An English string defined in
is handled as a key. Get more details about it in the Internationalization and Localization document.
<application> ... <id>http://aps-standard.org/samples/async1pn</id> ... </application>
It is a URI-formed unique application identifier. This string should be used as the application identifier - it must not be changed in consequent versions of packages, otherwise package upgrade and patching from older versions will not be feasible. This URI may or may not lead to any valid page.
<application> ... <name>Sample Notification Management</name> ... </application>
It is a free-formed short string that specifies a user-visible name of an application. The package name may be changed during upgrade and should reflect the packaged software name.
<application> ... <version>2.0.22</version> <release>6</release> ... </application>
A package version consists of two parts:
version: corresponds to the version of the application packaged.
release: is a release of the package based on a certain version of the application.
Packages of the same application version may be released many times,
for example, for fixing bugs in packages or adding localization.
The version format and the algorithm for determining the chronological relationship between different package versions are specified by the Version Format in Debian Policy.
Unlike the Debian version-release approach, the application version and the package release are separated to ease parsing.
<vendor> <name>APS team</name> <homepage>http://dev.apsstandard.org</homepage> </vendor>
Characteristics of the software vendor whose application is packaged:
name: the name of the software vendor.
homepage: the URL of the software vendor homepage.
<packager> <name>APS Team</name> <homepage>http://aps.test</homepage> </packager>
Characteristics of the package manufacturer:
name: the name of the package manufacturer.
homepage: the URL of the package manufacturer homepage.
The <presentation> tree contains visual elements that present the application on the provider and customer control panels.
<presentation> <summary>Basic multi-tenant application with async provisioning.</summary> <description>This is a demo application illustrating how to use the async provisioning. The application tracks operations over its resources and notifies subscribers about it. </description> <icon path="images/phpbb.png" /> <categories> <category>Samples</category> <category>Infrastructure/Management</category> </categories> <navigation id="ccp" label="VPS Management" icon="images/nav-icon.png"> <item id="servers" label="Servers" icon="images/servers-icon.png"> <view id="servers" label="Servers List" src="ui/servers.js"> </view> </item> </navigation> <screenshot path="images/admin.png"><description>Admin interface</description></screenshot> <screenshot path="images/main.png"><description>Main page</description></screenshot> <changelog> <version version="2.1.22" release="1"><entry>New upstream version</entry></version> <version version="2.1.21" release="5">...</version> </changelog> <languages> <language>en</language> <language>de</language> <language>ru</language> </languages> </presentation>
The <icon> element inside the <presentation> section defines the default icon to be displayed at all levels
of the application navigation tree. This can be redefined by the
icon attribute in any navigation elements,
that is in <navigation> and <item>.
By default, the icons are displayed as monochrome images.
Get more details about it in the Application Icon Design concepts.
This element contains short introduction to the application purposes printed out in the APS catalog and control panels.
This elements contains some details about the application functionality and its features. It is printed out in the APS catalog and control panels. The description must be not shorter than 256 UTF-8 characters and not longer than 1024 UTF-8 characters.
The icon presents the package in the APS catalog and in control panels.
path attribute must contain a full path in the archive to the icon file.
The icon should be a 64x64 pixel image in the PNG format using alpha transparency. The JPEG and GIF formats MAY be used as well, but their use is discouraged.
A package may include a set of categories. A category is a Unicode string without attached semantics. The first category should be the “primary category” in the sense that the first category should be adequate for sorting packages in the user interface. A list of predefined categories is available at APS Application Categories. The specified category names should be used. Other category names MAY be used, but handling them in the APS controller is not guaranteed.
One or more screenshots with descriptions may be provided.
path attribute must contain a full path in the archive to the screenshot file.
It must be a JPEG, PNG or GIF image.
Change log contains the human-readable list of changes between consecutive package versions. The order of entries in the change log is not specified. The APS controller should sort them when displaying on the screen.
A package may declare a set of languages for the presentation purposes. The first language is the “default language” of the application. The languages are identifiers as defined in the ISO 639: Names of Languages standard.
A declaration of the license agreement MAY include the name of the license, whether the license must be accepted by a user, and either a full path to the license file in the package or a URL of the full text of the license.
<license-agreement must-accept="true"> <free/> <text> <name>End-User License Agreement</name> <file>licenses/eula.txt</file> </text> <license-agreement>
<license-agreement> <commercial/> <text> <name>Commercial EULA</name> <url>http://opensource.org/licenses/bsd-license</url> </text> </license-agreement>
license-agreement section MAY contain the following elements:
commercial: the application license must be characterized as
free or commercial by using the appropriate.
text/name: element must be a name of the license agreement.
text/file: element must be a full path in the archive to the existing license agreement file.
text/url: element must be a URL to the license agreement file.
This element shows package versions that this package can upgrade. Get more details about it in the Application Updates document.
The <service> element declares an application service and is explained in the Application Services document.
The <privileges> section consists of a list of <privilege> elements. Each element is used to register a custom privilege in the platform. For example:
<privileges> <privilege area="clients" name="vps-manage" title="VPSes"/> </privileges>
This is the declarative way of registering custom privileges as opposed to the imperative way, which an application can use in its provisioning scripts. The element attributes must comply with the Privilege structure of the PrivilegeManagement APS type.