# AppStream XML files

## Introduction

AppStream XML files are small textfiles describing all available applications in the distribution's package repositories. The XML files might be compressed with GZip.

## File naming and location

The XML files must have an unique name, which is usually the distribution's name and version, combined with the name of the repository/origin. For example in Debian 8 (Jessie), the filename for the main repository component would be `debian-jessie-main.xml.gz`. For Fedora 20 (Heisenbug) updates it would be `fedora-20-updates.xml.gz`. 3rd-party repositories use a vendor name and repository-name combination, for example Ubuntu PPAs might get `ppa-ubuntu12.04-username-foobar.xml`.

There are two valid locations to store AppStream XML data. `/usr/share/app-info/xmls` stores all AppStream data which has been installed via software packages, while `/var/cache/app-info/xmls` stores application data which was downloaded by the package manager or placed there by other tools (e.g. Listaller). The XML files can either be plain files or be compressed with gzip. It is always a good idea to compress the files, because they tend to become quite large.

## XML structure

The XML starts with an `<applications>` tag as root element. It has all the `<application>` elements as children. Data to fill the application elements is usually taken from their Desktop files and package data. However, if an application ships AppData files (see ), values defined there should override data from any other source. The `<application>` element must at least have an `id`, `name`, `summary`, `pkgname` and `icon` tag. All possible tags are:

<id/>

  The `<id type="desktop">` tag is the same name as the installed .desktop file for the application. Additional identifiers are possible later, but right now `desktop` is the only supported type.

<pkgname/>

  The name of the package which needs to be installed in order to provide this application.

<name/>

  The application name defined in the application's Desktop file.

<project_license/>

  The `<project_license>` tag is indicating the license of your project/application. It should be a string in SPDX format. Licenses may be combined using and and or logic. Possible values include:

  - GPL-2

  - LGPL-3+ and GPL-3+

  - MIT

  - CC-BY-SA-2

  - ...

  A full list of recognized licenses and their identifiers can be found at the SPDX OpenSource License Registry. For SPDX compatibility, versions with trailing dot-zeroes are considered to be equivalent to versions without (e.g., "2.0.0" is considered equal to "2.0" and "2").

  Although the license tag is not mandatory, it is recommended to include it.

<summary/>

  A short summary of the purpose and function of this application. Usually taken from the Desktop file, if the application does not ship an AppData file.

<description/>

  A long description of the application. It is usually taken from the package descriptions or application's AppData files. The description might use markup. Right now, only paragraph, ordered list and unordered list are supported. An example description element might look like this:

      <description>
        <p>
         Power Statistics is a program used to view historical and current battery
         information and will show programs running on your computer using power.
        </p>
        <p>Example list:</p>
        <ul>
         <li>First item</li>
         <li>Second item</li>
        </ul>
        <p>
        You probably only need to install this application if you are having problems
        with your laptop battery, or are trying to work out what programs are using
        significant amounts of power.
        </p>
       </description>

<url/>

  Links of type `homepage` should be a link to the upstream homepage for the application. It is planned to allow links to application's FAQ and forums later.

<project_group/>

  The `<project_group>` tag identifies a project with a specific upstream umbrella project. Known values include `GNOME, KDE, XFCE, LXDE, Mozilla` and `MATE`, although other umbrella projects like `Yorba` would make sense too.

  Applications should only identify with an umbrella project if you use all their infrastructure and policies, for instance string freezes dates, bugtracker and source control instance.

<icon/>

  The `<icon>` tag describes the application's icon. It can be of the type `stock`, `cached`, `local`, or `url`.

  `stock` icons are loaded from stock. The icon name should never include any file-extension or path.

  `cached` icons are loaded from the AppStream icon cache. The icon tag should contain the icon file name, including it's extension.

  `local` icons are reserved for AppStream data installed by local applications or via 3rd-party application installers, such as Listaller. They should specify a full file path.

  `remote` icons loaded from a remote URL. This is currently not implemented anywhere, but might be used in future.

  Examples of the different methods to specify an icon:

      <icon type="stock">gimp</icon>
      <icon type="cached">firefox.png</icon>
      <icon type="local">/usr/share/pixmaps/foobar.png</icon>
      <icon type="remote">http://example.com/icons/foobar.png</icon>

  Multiple `<icon/>` tags might be combined for one application, e.g. to define a `stock` icon and a `cached` icon. Software-Centers should always prefer the stock icon, if it is available, and fall back to the other icon types if they can not find it. The libappstream library makes it easy to do that, if you are not accessing the Xapian database manually.

  The AppStream Xapian database generator will prefer `cached` over `local` over `remote` icons when setting the non-stock icon for the application.

<mimetypes/>

  This tag can contain one or more `<mimetype>` tags, describing the mime types this application supports. The data can usually be fetched from the Desktop files. Example:

      <mimetypes>
          <mimetype>text/html</mimetype>
          <mimetype>image/jpeg</mimetype>
          <mimetype>application/rss+xml</mimetype>
       </mimetypes>

<appcategories/>

  This tag can contain one or more `<appcategory>` tags, describing the categories this application is in. This data is usually taken from Desktop files, a list of categories can be found in the Freedesktop menu spec. Example:

      <appcategories>
          <appcategory>GNOME</appcategory>
          <appcategory>GTK</appcategory>
          <appcategory>Network</appcategory>
          <appcategory>Telephony</appcategory>
      </appcategories>

<keywords/>

  This tag can contain one or more `<keyword>` tags, describing keywords for the application, to make it easier to find in a software center. The data is taken from Desktop files. Example:

      <keywords>
        <keyword>IDE</keyword>
        <keyword>development</keyword>
        <keyword>programming</keyword>
      </keywords>

<screenshots/>

  This tag can contain one or more `<screenshot>` tags, describing screenshots which are available for the application. A screenshot tag my have the attribute `type="default"`, marking it as the application's default screenshot, which primarily represents it in a software center.

  Every `<screenshot>` is defined by several images of different sizes. All images should have their width and hight set as arguments. Also, one of the images shoukd be marked as `type="source"`, indicating that it is the unscaled version of the screenshot. Images of `type="thumbnail"` define thumbnails of the screenshot.

  Every image should have a full remote url set, usually pointing to a cache of images maintained by the distributor. Example:

      <screenshots>
        <screenshot type="default">
          <image type="source" width="800" height="600">http://www.example.org/en_US/main.png</image>
          <image type="thumbnail" width="200" height="150">http://www.example.org/en_US/main-small.png</image>
        </screenshot>
        <screenshot>
           ....
        </screenshot>
      </screenshots>

<compulsory_for_desktop/>

  The `<compulsory_for_desktop>` tag indicates that the application which the data belongs to is essential for the functionality of the defined desktop environment. Examples for compulsory applications are the `GNOME-Shell` by the GNOME-Project, or the `Plasma-Desktop` by KDE, as well as things like `iBus` or the desktop login manager.

  Software centers are expected to detect the running desktop environment and disable uninstallation for compulsory components of that desktop, so users will not be able to damage their currently running, primary desktop environment.

  Multiple occurrences of the `<compulsory_for_desktop>` tag are allowed, so a project can be essential for many desktops. The distributor decides which applications should be made compulsory, however it is generally a good idea to follow upstream's recommendations on that matter.

  A list of all allowed values for this tag is defined in the XDG Menu Specification. Software center applications will only recognize these values.

## Example file

This is an example AppStream metadata file:

    <?xml version="1.0"?>
    <applications version="0.1">
        <application>
            <id type="desktop">firefox.desktop</id>
            <pkgname>firefox-bin</pkgname>
            <name>Firefox</name>
            <name lang="en_GB">Firefoux</name>
            <summary>Web browser</summary>
            <summary lang="fr_FR">Navigateur web</summary>
    	<project_license>MPL-2</project_license>
            <keywords>
                <keyword>internet</keyword>
                <keyword>web</keyword>
                <keyword>browser</keyword>
                <keyword lang="fr_FR">navigateur</keyword>
            </keywords>
            <icon type="stock">web-browser</icon>
            <icon type="cached">firefox.png</icon>
            <appcategories>
                <appcategory>network</appcategory>
                <appcategory>web</appcategory>
            </appcategories>
            <mimetypes>
                <mimetype>text/html</mimetype>
                <mimetype>text/xml</mimetype>
                <mimetype>application/xhtml+xml</mimetype>
                <mimetype>application/vnd.mozilla.xul+xml</mimetype>
                <mimetype>text/mml</mimetype>
                <mimetype>application/x-xpinstall</mimetype>
                <mimetype>x-scheme-handler/http</mimetype>
                <mimetype>x-scheme-handler/https</mimetype>
            </mimetypes>
            <url type="homepage">http://www.mozilla.com</url>
            <screenshots>
                <screenshot type="default">
    		<image type="source" width="800" height="600">http://www.awesomedistro.example.org/en_US/firefox.desktop/main.png</image>
    		<image type="thumbnail" width="200" height="150">http://www.awesomedistro.example.org/en_US/firefox.desktop/main-small.png</image>
                </screenshot>
            </screenshots>
        </application>
        <!-- more applications here! -->
    </applications>