Chapter 2. Upstream Meta Information

2.1. Generic Component
2.2. Desktop Applications (AppData)
2.3. Fonts
2.4. Input Methods

AppStream allows upstream projects to define metadata about the components they provide using small XML files, metainfo files, which get installed into locations on the client system and are used by distribuors to enhance their metadata.

A "component" is something like an application, a library, a font or a codec. For several components, especially those which are shown in software-centers, we provide specialized metainfo files to define specific properties and data of these components. For example, applications and fonts support screenshots, while codecs don't.

All metainfo files need to contain a minimal amount of information, defined in the "Generic Component" section, which also describes some optional elements which can be used. Specialized components might require more information to be complete and valid.

2.1. Generic Component

2.1.1. Introduction

For a distribution, it is good to know more about the content of a package. Which public interfaces (libraries? Python modules?) does it provide? Does it contain codecs? Does it contain firmware? Fonts? An application? All of this information can be used to automatically install missing software or to offer users a choice on what they want to install from a software center.

To provide this information, we created the metainfo files, which allow upstream projects to describe the content of their software package. If a metainfo file provides a <provides/> tag, distributors must also ensure that the package providing the file contain all items referenced by that statement, or is installed by a metapackage depending on packages which provide these items. This gives upstream projects a (very light) way to influence distributor packaging. More information about that can be found below.

Several specialized component-metainfo files exist, for example for applications or fonts. These are all based on this generic component XML specification, and are described in the following chapters.

2.1.2. Filesystem locations

Upstream projects can ship one or more metainfo files in /usr/share/appdata/%{id}.metainfo.xml, where id is a unique identifier of this specific component.

Note

Applications are a special case here, because they are special in some ways (and also for historical reasons). If your metainfo file covers only an application, as described in the AppData section, install it as /usr/share/appdata/%{id}.appdata.xml.

Please note that the /usr/share/appdata/symbols directory is reserved for a possible future use for storing upstream-generated symbols files for libraries.

Multiarch Support

On multiarch-aware systems such as Debian: If a component ships a library, the meta-info file should be in the same package as the library itself. To make the library packages co-installable, append the <triplet> to the meta-info filename. So appstream.metainfo.xml becomes appstream_x86_64-linux-gnu.metainfo.xml. Upstream projects which ship components with libraries should adjust their buildsystem to install a multi-arch compatible metainfo file by default. Make use of the <architectures/> tag to indicate that the meta-info file is arch specific.

2.1.3. XML Specification

The XML for a generic component definition starts with an

<component>

tag as root element. The

<component>

element must at least have an id, name and releases tag, a provides tag with appropriate children is highly recommended. All possible tags in the generic set are:

<id/>

The

<id>

tag is a short and unique identifier for this component. It must contain only ASCII caracters, dots, hyphens and numbers, spaces are not allowed. Specialized metainfo types, such as application or fonts, may apply additional restrictions on the id tag value.

Note that the value of this tag must be unique across all distributions. In case it is not, distributors are expected to reject the conflicting components from inclusion into their metadata.

<name/>

A human-readable name for this software component. For example, if the component id was "libc", it's name might be "GNU Standard C Library".

<summary/>

A short summary of what this component does. If the component is "PackageKit", the summary could be "Provides a package-management abstraction layer".

<url/>

Defines URLs for this component.

Links of type homepage should be a link to the upstream homepage for the component.

Links of type bugtracker should point to the software's bug tracking system, for users to report new bugs.

Links of type faq should link a FAQ page for this software, to answer some of the most-asked questions in detail, something which you can not do in the component's description.

Links of type donation should point to a webpage showing information on how to donate to the described software project.

<releases/>

The

<releases>

tag contains <release/> child tags which describe some metainformation about the current release of the described software. The <release/> tag may be present multiple times (for older releases), but a tag for the current version must always be present. A release tag can have the properties version and timestamp which contain the version number and a release timestamp in form of YYYYMMDD.

Examples for a valid releases tag:

<releases>
  <release version="1.2" timestamp="20140412" />
  <release version="1.0" timestamp="20120826" />
</releases>

<provides/>

The provides tag and it's children describe the public interfaces this application provides. A public interface can be anything which other applications, which are not part of the upstream project, can access or reference. This includes binaries and libraries. Private interfaces should never be added to a provides tag.

A provides tag contain a number of childrens describing the type and name of the provided public interface items. It is suggested that the build-system auto-generates this tag and it's children. Currently allowed item types are listed below. If you miss something, file a bug against AppStream so we can add the new type.

<library/>

Contains the name of a shared library placed in a publicly accessible library path, such as /usr/lib, /usr/lib/<triplet> or /lib. For example, for the libappstream library, the value for library would be libappstream.so.1.

<binary/>

Name of a binary installed into a location in PATH.

<font/>

Name of a font provided by this component. For example Linux Libertine O. The tag must have a file property stating the filename of the referenced font.

Example:

<provides>
  <font file="LinLibertine_R.otf">Linux Libertine O</font>
</provides>

<modalias/>

A modalias glob representing the hardware types (for example USB, PCI, ACPI, DMI) this component handles. Useful for installing printer drivers or other USB protocol drivers for smartphones, firmware, kernel drivers which are not merged upstream yet or whatever else.

<firmware/>

Name of the firmware this component provides, to make it possible to find the right firmware package to install for a given kernel driver. The value is the path below /lib/firmware to the firmware file in question, like the firmware value exported from Linux kernel modules.

Example:

<provides>
  <firmware>ipw2200-bss.fw</firmware>
</provides>

<python2/>

Name of a Python2 module this component provides.

<python3/>

Name of a Python3 module this component provides.

<project_group/>

If you include the <project_group/> tag then this identifies your project with a specific upstream umbrella project. Known values include GNOME, KDE, XFCE, MATE and LXDE, although other umbrella projects like Yorba or Mozilla make sense too.

Note

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

<metadata_license/>

The <metadata_license/> tag is indicating the content licence that you are releasing the one Metainfo XML file as. This is not typically the same as the project licence. By ommitting the licence value would probably mean your data would not be incorporated into the distribution metadata (so this is a required tag). Permissible licence codes include:

CC0
CC-BY
CC-BY-SA
GFDL
MIT

The licence codes correspond to the identifiers 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"). For instance, CC-BY-SA corresponds to http://creativecommons.org/licenses/by-sa/3.0/

An example for a very basic component file could look like this:

<?xml version="1.0" encoding="UTF-8"?>
<component>
  <id>foobar</id>
  <name>Foo Bar</name>
  <summary>A foo-ish bar</summary>
  <url type="homepage">http://www.example.org</url>
  <metadata_license>CC0</metadata_license>

  <provides>
    <library>libfoobar.so.2</library>
    <font>foo.ttf</font>
    <binary>foobar</binary>
  </provides>
  <release version="1.2" timestamp="1365768000" />
</component>