Each package MUST contain a well-formed XML file named APP-META.xml in the package root directory.
In this document:
The file contains all package metadata. It MUST be
valid in accordance with the XML schema and UTF-8 encoded.
Note
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>
</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 herein is 2.0. The numbering scheme for the APS format versions is 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.
Note
A package SHOULD use the APS version 2.0 or higher if possible.
A package SHOULD declare the packaging date with the help of the packaged attribute.
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 APP-META.xml 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:
<packager>
<name>APS Team</name>
<homepage>http://aps.test</homepage>
</packager>
Characteristics of the package manufacturer:
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">
<item id="servers" label="Servers">
<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>
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.
The 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. The 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>
or
<license-agreement>
<commercial/>
<text>
<name>Commercial EULA</name>
<url>http://opensource.org/licenses/bsd-license</url>
</text>
</license-agreement>
The license-agreement section MAY contain the following elements:
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.