Previous topic

Files Naming

Next topic

Package contents listing (APP-LIST.xml)

DOCUMENTATION
Last updated 15-Jul-2016

Metadata Descriptor (APP-META.xml)

Each package MUST contain a well-formed XML file named APP-META.xml in the package root directory. This file contains all the package metadata and MUST comply with the RELAX NG schema and be in the UTF-8 encoding.

Note

The XML namespace of the metadata will be changed when incompatible changes are introduced.

An example of an application metadata file is the following:

<application xmlns="http://aps-standard.org/ns/2" version="2.0">

    <name>Open-Xchange</name>
    <version>6.14</version>
    <release>1.15</release>

    <presentation>
        <summary>Open-Xchange is a highly advanced email and collaboration solution.</summary>
        <icon path="images/ox_logo.jpg"/>
        <categories>
            <category>Collaboration/Email</category>
        </categories>
    </presentation>

    <service id="organization">
        <schema path="schema/organization.schema"/>
        <code engine="php" path="scripts/organization.php"/>
    </service>

</application>

A package SHOULD declare the version of the APS format specification with which it complies. 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 (e.g., APS 1.01 ) MUST be ignored by APS controllers and MUST NOT be specified.

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.

<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 treated as a key. Internationalization and Localization is covered in the corresponding section.

Application Properties

The following properties are common for all applications:

Application ID

<application>
    ...
    <id>http://www.phpbb.com/</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>phpbb</name>
    ...
</application>

It is a free-formed short string which specifies the 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 - release of the package containing the same version of the application (packages may be released many times, e.g., for fixing bugs in packaging or adding localizations).

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.

Homepage

<application>
    ...
    <homepage>http://phpbb.com/</homepage>
    ...
</application>

The URL of the application’s official site.

Software Vendor Information

<application>
    ...
    <vendor>
        <name>Broombla Corporation</name>
        <homepage>http://broombla.com</homepage>
        <icon path="icons/broombla-corp-logo.png"/>
    </vendor>
    ...
</application>

The characteristics of the software vendor whose application is packaged:

  • name - The name of the software vendor.
  • homepage - The URL of the software vendor homepage.
  • icon/@path - This 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.

Software Packager Information

<application>
    ...
    <packager>
        <name>Parallels</name>
        <homepage>http://sp.parallels.com</homepage>
        <icon path="icons/parallels-package-logo.png"/>
        <uri>uuid:15d041e8-34c6-409a-b165-3290d2c9d599</uri>
    </packager>
    ...
</application>

The characteristics of the package manufacturer:

  • name - The name of the package manufacturer.
  • homepage - The URL of the package manufacturer homepage.
  • icon/@path - This 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.
  • uri - is an arbitrary URI unique for each packager. This URI is needed to distinguish packages with the same name but created by different packagers. Note that consequent versions of the same package MUST have the same URI, as otherwise package Controllers MAY refuse to update the package from one version to another.

Controllers SHOULD allow upgrading and patching a package from a version which does not specify uri to one which specifies it to support a smooth upgrade path for the packages which did not use uri from the beginning.

Presentation

<application>
    ...
    <presentation>
        <summary>
            High powered, fully scalable, bulletin board package.
        </summary>

        <description>
            phpBB is a high powered, fully scalable, and highly customizable
            Open Source bulletin board package. phpBB is the ideal free
            community solution for all web sites.
        </description>

        <icon path="images/phpbb.png" />

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

        <categories>
            <category>Collaboration/Portals</category>
            <category>Web/Content management</category>
        </categories>

        <languages>
            <language>en</language>
            <language>de</language>
            <language>ru</language>
        </languages>
    </presentation>
    ...
</application>
  • summary - A single-sentence summary of the package for end users.
  • description - A one-paragraph description of the package for end users.
  • icon - An icon may be provided to be displayed in the GUI for the application. 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.
  • screenshot - 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.
  • changelog - contains the human-readable list of changes between consecutive package versions. The order of entries in the changelog is not specified, a controller should sort them.
  • 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 a Controller is OPTIONAL.
  • 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 from the ISO 639: Names of Languages.

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.

<application>
    ...
    <license-agreement must-accept="true">
        <free/>
        <text>
            <name>End-User License Agreement</name>
            <file>licenses/eula.txt</file>
        </text>
    <license-agreement>
    ...
<application>

or

<application>
    ...
    <license-agreement>
        <commercial/>
        <text>
            <name>Commercial EULA</name>
            <url>http://opensource.org/licenses/bsd-license</url>
        </text>
    </license-agreement>
    ...
<application>

The license-agreement section MAY contain the following elements:

  • free and commercial - the application license MUST be characterized as free or commercial by using the appropriate free or commercial element.
  • 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.