Metadata Descriptor (APP-META.xml)

Each package must contain a well-formed XML file named APP-META.xml in the package root directory.

Metadata Structure

APP-META.xml is a UTF-8 encoded XML file that contains all package metadata in accordance with the rules described in this document.

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>

    <privileges>
        <privilege area="clients" name="vps-manage" title="VPSes"/>
    </privileges>

</application>

The following sections contain explanation of the elements.

General Properties

APS Version

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 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

Optimally, a package uses APS version 2.0 or higher.

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

<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

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

Package Version

<application>
   ...
   <version>2.0.22</version>
   <release>6</release>
   ...
</application>

A package version consists of two parts:

• Application version: corresponds to the version of the application packaged.

• Package 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.

Software Vendor Information

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

Software Packager Information

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

Presentation

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

Note

By default, the icons are displayed as monochrome images.

Get more details about it in the Application Icon Design concepts.

Summary

This element contains short introduction to the application purposes printed out in the APS catalog and control panels.

Description

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.

Icon

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.

Categories

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.

Navigation

The <navigation> tree is explained in the Navigation Elements document.

Screenshots

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

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.

Languages

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.

License Agreement

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:

• free or 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.

Upgrade

This element shows package versions that this package can upgrade. Get more details about it in the Application Updates document.

Services

The <service> element declares an application service and is explained in the Application Services document.

Privileges

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.

← File Naming

Package contents listing (APP-LIST.xml) →