Chapter 3. Distribution Metadata and Services

- Prev
- AppStream
- Next

# ⁠Chapter 3. Distribution Metadata and Services

AppStream provides an own Metadata format which gets shipped by the distributions and is read by the Xapian database generator or software centers directly.
This chapter contains information about it.

## ⁠3.1. AppStream distribution XML files

### ⁠3.1.1. 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.

### ⁠3.1.2. 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. Limba). 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.

### ⁠3.1.3. General XML structure

The XML starts with an `<components>` tag as root element. It has all the `<component>` tags of different `type` as children.
Data to fill the different component elements is usually taken from their Desktop files and package data. However, if an upstream project ships metainfo files (see Chapter 2, Upstream Metadata), values defined there should override data from any other source.
All child elements of the `<components>` element, no matter of which type they are, must at least have an `id`, `name`, `summary` and `pkgname` tag. For applications, a `icon` tag is also required.
The `<components>` root node has these properties, where the first two are required:

version
  This property declares the AppStream spec version this file is based on (currently 0.9). The property is required.
origin
  Defines the repository-id this AppStream XML file belongs to. This usually matches the filename without extension (see the explanation on how to pick a good filename above). It is also used to associate the right cached icons with AppStream metadata. This property is required.
architecture
  Defines the architecture this data belongs to. This information is useful to resolve AppStream-ID conflicts on multiarch systems, which appear if the user has metadata for two architectures installed. This property is optional.

### ⁠3.1.4. Valid tags for all component types

These tags can be applied to every component type (application, component, font, inputmethod) which is described in the AppStream metadata.
Additionally to the `type` property, every `<component/>` tag in AppStream distro data may have a `priority` property, defining the priority of this specific metadata over other metadata from different AppStream XML files (e.g. from a different repository) which have the same component-id. The value of this tag is an integer, if the property is missing, a value of `"0"` is assumed.

⁠<id/>
  The `<id/>` tag is a short unique and usually lower-cases identifier for the component. Depending on the component's type, different naming conventions apply.
⁠<pkgname/>
  The name of the package which needs to be installed in order to make this component available on the system.
  This tag can be defined multiple times, if a component is split across multiple packages.

  Important

  The preferred way is to create metapackages containing the component metadata, and referncing them from the distribution metadata, and not to use multiple `pkgname` tags. They should only be used multiple times as a workaround or if there is no sensible way of creating a matching metapackage.
⁠<source_pkgname/>
  This optional tag is used to specify the source package the binary package this component belongs to was built from.
  The tag can be used by software center applications to group components. It is otherwise useful for the distributor to assign components to a source package and to fetch additional information about a package from the web.
⁠<name/>
  A human-readable name for this component.
  In case of a component of type `desktop`, the application name as defined in the application's desktop file is used.
⁠<project_license/>
  The `<project_license/>` tag is indicating the license of the component. It should be a string in SPDX format. Licenses may be combined using and and or logic. Possible values include:
  - GPL-2.0
  - LGPL-3.0+ and GPL-3.0+
  - MIT
  - CC-BY-SA-2.0
  - ...
  A full list of recognized licenses and their identifiers can be found at the SPDX OpenSource License Registry.
⁠<summary/>
  The tag contains a short summary of the purpose and function of this component. In case the component is of type `desktop`, it is usually taken from a Desktop file, if the application does not ship an upstream metadata file.
  For more information about this tag, take a look at the tag's definition at <summary/>.
⁠<description/>
  A long description of the component. It is usually taken from the package descriptions or meta-info files, if they were provided. 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>

  As opposed to the by-paragraph translation used in meta-info files, this tag is translated "as a whole", meaning that the `<description/>` tag itself has a language property and contain the translated paragraphs for the given language. This allows faster parsing of the Appstream XML file, and does not increase it's size much, as long as it is compressed.
  For more information about this tag, take a look at the tag's definition at <description/>.
⁠<url/>
  Defines URLs for this component. This tag can be present multiple times.
  For a list of possible url types and what they are expected to do, take a look at the tag's description at <url/>.
⁠<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.

  Note

  Components 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 component icon. It is mostly used for GUI applications (component-type `desktop`). 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. It must not contain a full or relative path to the icon file.
  `local` icons are reserved for AppStream data installed by local applications or via 3rd-party application installers. They should specify a full file path. This icon type may have `width` and `height` properties.
  `remote` icons loaded from a remote URL. Currently, at least HTTP urls must be supported. This icon type may have `width` and `height` properties.
  Examples of the different methods to specify an icon:

      ​<icon type="stock">gimp</icon>
      ​<icon type="cached">firefox.png</icon>
      ​<icon type="remote" width="64" height="64">http://example.com/icons/foobar.png</icon>
      ​<icon type="local" width="64" height="64">/usr/share/pixmaps/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 component 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>

⁠<categories/>
  This tag can contain one or more `<category>` tags, describing the categories this application is located in. This tag is usually applied to components of type `desktop`, although it might be used by others later. This data is usually taken from Desktop files, a list of categories can be found in the Freedesktop menu spec. Example:

      ​<categories>
      ​    <category>GNOME</category>
      ​    <category>GTK</category>
      ​    <category>Network</category>
      ​    <category>Telephony</category>
      ​</categories>

  Deprecated Tags

  The tag `<appcategories>` with its `<appcategory>` child elements is deprecated API. AppStream parsers should handle these tags just like the `category` tags, there is no difference except for the name.
⁠<keywords/>
  This tag can contain one or more `<keyword>` tags, describing keywords for the component, to make it easier to find in a software center. In case of type `desktop` components, this data is taken from Desktop files. For `addon` components, the upstream metadata file usually provides this tag. 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 should be marked as `type="source"`, indicating that it is the unscaled version of the screenshot. Images of `type="thumbnail"` define thumbnails of the screenshot.
  The metadata generator should scale the source image down to several thumbnails useful for the client to load. The recommended sizes for thumbnail images are:
  - 752x423 (large)
  - 624x351 (normal)
  - 112x63 (small)
  - 1504x846 (large, HiDPI)
  - 1248x702 (normal, HiDPI)
  - 224x126 (small, HiDPI)
  In order to support HiDPI screens, the thumbnails should also be available in their bigger sizes. A metadata generator should, however, never attempt to scale up a smaller image to a larger size, and just ship the smaller sizes instead.
  Optionally, a screenshot can contain a `<caption>` tag, describing the screenshot's caption. This is usually what the user can see on the image shown. The tag is translatable.
  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">
      ​    <caption>Foobar showing kitchen-sink functionality</caption>
      ​    <caption xml:lang="si">Foobar shoeewing kischän-sünk funzionality</caption>
      ​    <image type="source" width="800" height="600">http://www.example.org/en_US/main.png</image>
      ​    <image type="thumbnail" width="752" height="423">http://www.example.org/en_US/main-large.png</image>
      ​    <image type="thumbnail" width="112" height="63">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 component which the metadata belongs to is essential for the functionality of the defined desktop environment. Examples for compulsory components 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 components 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.
⁠<provides/>
  This tag is described in detail at Section 2.1, “Generic Component”.
  For generic component types, this tag has to be present. Distributors must ensure that all things described in this tag are present in the package referenced in the associated `pkgname` tag.
⁠<developer_name/>
  The `<developer_name/>` tag as described in the specification for a generic component. See <developer_name/> for more information.
⁠<releases/>
  The `releases` tag and its `release` children are structured as described in <releases/>.
  Each `release` tag may have a `description` tag as child, containing a brief description of what is new in the release. The `description` tag is structured as described in <description/>. This also applies to its translation rules.
  The AppStream distro XML generator may shorten overlong lists of releases to a smaller list, e.g. of 4 `release` tags. It may also convert ISO 8601 `date` properties of the metainfo file into an UNIX timestamp `timestamp` property. It should avoid generating metadata containing both properties on a `release` tag.
  Example for a valid releases tag:

      ​<releases>
      ​  <release version="1.8" timestamp="1424116753">
      ​    <description>
      ​      <p>This stable release fixes the following bug:</p>
      ​      <ul>
      ​        <li>CPU no longer overheats when you hold down spacebar</li>
      ​      </ul>
      ​    </description>
      ​    <size type="download">12345678</size>
      ​    <size type="installed">42424242</size>
      ​  </release>
      ​  <release version="1.2" timestamp="1397253600" />
      ​  <release version="1.0" timestamp="1345932000" />
      ​</releases>

  In case a `<release/>` tag has a `<description/>` tag as parameter, describing the new release briefly, distributors are encouraged to provide 2-4 `<release/>` release tags for every component. If no description is provided, one tag is enough.
  Components of type `firmware` (Section 2.7, “Firmware”) may also have a <location/> tag as child of one of the `<release/>` tags. In case a `<location/>` tag is present, it must be accompanied by a `<checksum/>` tag, containing a checksum of the downloaded file. This is done to ensure the integrity of the downloaded firmware, and that the user gets the firmware which was tested by the distributor. The `<location/>` tag is often used in case the distributor is not allowed to legally redistribute the firmware in a native package.
  The `<checksum/>` tag has a `type` attribute, describing the checksumming-algorithm that was used to create it. Currently, only `SHA1` is supported.
  Example for a `<release/>` tag of a firmware component which makes use of `<location/>`:

      ​<release version="2.0.3" timestamp="1429362707">
      ​  <location>http://www.hughski.com/downloads/colorhug2/firmware/colorhug2-2.0.3.cab</location>
      ​  <checksum type="sha1">40b59e37cb918f3241f65bc5ac2b90ab47b34e8c</checksum>
      ​  <description>
      ​    <p>This stable release fixes problems.</p>
      ​  </description>
      ​</release>

⁠<languages/>
  This tag gives information about the translations a component provides, and to which extent the software is translated.
  The tag is allowed to only occur once per component, and contains multiple `<lang/>` child nodes, which have a language code as value. Each `<lang/>` node may have a `percentage` property, which describes the percentage value to which a component has been translated.
  The language data is expected to be extracted by the AppStream XML generator, and is not provided upstream. Generators may obtain the information from processing GNU Gettext files, which should cover most translation methods.
  Tag example:

      ​<languages>
      ​  <lang percentage="96">gu</lang>
      ​  <lang percentage="94">ca@valencia</lang>
      ​  <lang percentage="91">de</lang>
      ​  <lang percentage="93">eo</lang>
      ​</languages>

⁠<bundle/>
  The optional `bundle` tag indicates that the described software is available as a software bundle via a 3rd-party application installer. The value of this tag is an identification string for the bundle.
  Software centers may use the information of this tag to offer the user to install the software from 3rd-party sources, or just update an already installed software automatically via the normal update procedure. The `bundle` tag can coexist with the `pkgname` tag, in case a component is available from multiple sources.
  The `type` property of this tag indicates which 3rd-party software installation solution the bundle belongs to. Currently supported solutions are:
  - The Limba Project, using the value `limba`.
  - xdg-app bundles, using the value `xdg-app`.
  Example:

      ​<bundle type="limba">foobar-1.0.2</bundle>

### ⁠3.1.5. Example file

This is an example AppStream metadata file:

    ​
    ​<?xml version="1.0"?>
    ​<components version="0.6">
    ​  <component type="application">
    ​    <id>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>
    ​    <categories>
    ​      <category>network</category>
    ​      <category>web</category>
    ​    </categories>
    ​    <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>
    ​    <provides>
    ​      <binary>firefox</binary>
    ​    </provides>
    ​  </component>
    ​  <component>
    ​    <id>pulseaudio</id>
    ​    <name>PulseAudio</name>
    ​    <summary>The PulseAudio sound server</summary>
    ​    <url type="homepage">http://www.freedesktop.org/wiki/Software/PulseAudio/</url>
    ​    <project_license>GPLv2</project_license>
    ​    <provides>
    ​      <library>libpulse-simple.so.0</library>
    ​      <library>libpulse.so.0</library>
    ​      <binary>start-pulseaudio-kde</binary>
    ​      <binary>start-pulseaudio-x11</binary>
    ​    </provides>
    ​    <release version="2.0"/>
    ​  </component>
    ​  <component type="font">
    ​    <id>LinLibertine_M.otf</id>
    ​    <name>Libertine</name>
    ​    <summary>Linux Libertine Open fonts</summary>
    ​    <font_classifier>Mono</font_classifier>
    ​    <font_parent>Libertine</font_parent>
    ​  </component>
    ​  <!-- more components here! -->
    ​</components>

- Prev2.7. Firmware
- Up
- Home
- Next3.2. Debian DEP-11 specification