Upstream Metadata | AppStream | AppStream 1.2
Description: 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 distributors to enhance their metadata. A component is a piece of software, like an application, a li…

Jump to content Jump to page navigation: previous page [access key p]/next page [access key n]
AppStream
AppStream › Upstream Metadata
AppStream › Upstream Metadata
Top
←→
Applies to AppStream 1.2

# 2 Upstream Metadata #

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 distributors to enhance their metadata.

A "component" is a piece of software, 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.

The XML in metainfo files does not need any XML namespace, and adding one should generally be avoided. If you want to use a namespace though (maybe in case you want to embed the data in other contexts), the xmlns should be `https://specifications.freedesktop.org/metainfo/1.0`.

## 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 contains a `<provides/>` tag, distributors must also ensure that the package providing the file contains 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/metainfo/%{id}.metainfo.xml`, where `id` is a unique identifier of this specific component.

###### Note

Component metadata of type `desktop-application` as described in Section 2.3, “Desktop Applications” can be installed with an `.appdata.xml` extension as well for historical reasons. AppStream implementations will read the XML files as long as they end up in the right location on the filesystem.

###### Important: Legacy Path

AppStream tools scan the `/usr/share/appdata/` path for legacy compatibility as well. It should not be used anymore by new software though, even on older Linux distributions (like RHEL 7 and Ubuntu 16.04 LTS) the metainfo path is well supported. Support for the legacy path will likely be dropped completely with a future AppStream 1.0 release.

### 2.1.3 XML Specification #

The XML for a generic component definition starts with a `<component>` tag as the root element. The `<component>` element must at least have an `id`, `name` and `summary` tag; a `provides` tag with appropriate children is highly recommended.

In addition to the `type` attribute denoting the component type in case the component is not a `generic` component, the `component` tag may also have a `date_eol` attribute that sets a date when the component stops to be supported entirely (this may be the case for superseded legacy software like `org.python.python2`). The attribute value can be any complete date or time in ISO 8601 (https://en.wikipedia.org/wiki/ISO_8601).

All possible tags which can be used with components of all types are:

<id/> #

  The `id` tag is a unique identifier for this component. It must contain only alphanumeric ASCII characters, dots, hyphens and underscores. Spaces are not allowed. While hyphens are allowed for legacy compatibility, their usage is strongly discouraged to ensure interoperability of the AppStream ID with other tools such as D-Bus (and thereby making the ID more generic and useful). For the same reason it is also strongly discouraged to start any segment of the ID with a digit. Additionally, even though uppercase letters are permitted in a component-ID, it is strongly encouraged to only use lowercase letters for the ID.

  The ID must follow a reverse-DNS scheme, consisting of `{tld}.{vendor}.{product}`, for example `org.kde.gwenview` or `com.hugski.colorhug2`. Ownership of `{vendor}.{tld}` in the domain name system guarantees uniqueness of IDs.

  To increase the uniqueness and to distinguish between different pieces of a software suite, it is suggested to append the type name to the component-id in these cases. For example, one can use `com.hugski.colorhug2` for the client tools to control hardware, and `com.hugski.colorhug2.firmware` for the runtime firmware files.

  Note that the value of this tag must be unique across all distributions and software deployment platforms. In case it is not unique, distributors are expected to reject the conflicting components from inclusion into their metadata and notify the upstream projects about this issue.

  ###### Important: Escaping characters in the component ID

  To ensures the greatest possible compatibility of an AppStream ID, it is recommended to replace any hyphens in the ID in all but the last segment of it with underscores, and prefix every leading digit of a segment with an underscore as well. Since the underscore is not a valid character in domain names, the uniqueness of the ID is kept. For example, the ID `org.7-zip.7-zip` could become `org._7_zip._7-zip`.

<metadata_license/> #

  The `<metadata_license/>` tag indicates the content license that you are releasing the one metainfo XML file under. This is typically not the same as the project license. Omitting the license value will result in the metainfo data not being incorporated into metadata collections as used by Linux distributions. This tag is required for all metainfo files.

  The value of this tag has to be one of the recognized SPDX license IDs for `<metadata_license/>` tags, or a simple SPDX expression (only `AND` and `OR` operators allowed) allowing the use of the metadata file under one of the recognized licenses.

  We do recognize a set of permissive (https://en.wikipedia.org/wiki/Permissive_software_licence) licenses that have been vetted for mutual compatibility. This is important in order to allow the metainfo metadata to be combined with arbitrary other data in one file. While copyleft licenses like the GPL are great for code, it is not feasible to test every copyleft license for mutual compatibility and compliance when combining metainfo metadata with other data into one larger assembly fully automatically.

  Currently, the following licenses have been reviewed and can be used as metadata licenses:

  - `FSFAP`

  - `MIT`

  - `0BSD`

  - `CC0-1.0`

  - `CC-BY-3.0`

  - `CC-BY-4.0`

  - `CC-BY-SA-3.0`

  - `CC-BY-SA-4.0`

  - `GFDL-1.1`

  - `GFDL-1.2`

  - `GFDL-1.3`

  - `BSL-1.0`

  - `FTL`

  - `FSFUL`

  The license codes correspond to the identifiers found at the SPDX OpenSource License Registry (https://spdx.org/licenses/). For instance, `CC-BY-SA-3.0` corresponds to the license at creativecommons.org/licenses/by-sa/3.0 (https://creativecommons.org/licenses/by-sa/3.0/). If you are looking for the simplest license to use for your metadata, using the `FSFAP` license is suggested.

<name/> #

  A human-readable name for this software component. For example, if the component ID was "libc", its 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". This element is translatable.

<icon/> #

  The `<icon/>` tag describes the component icon. It is mostly used for GUI applications (component-type `desktop-application`). It can be of type `stock`, `local` or `remote`.

  `stock` icons are loaded from the icon stock (the current or hicolor/locolor fallback themes). The icon name must not include any file-extension or path.

  `local` icons are loaded from a file in the filesystem. They should specify a full file path. This icon type may have `width` and `height` properties. If targeting a hi-DPI screen, this icon type may have a `scale` property.

  `remote` icons loaded from a remote URL. Currently, only HTTP/HTTPS urls are supported. This icon type should have `width` and `height` properties. If targeting a hi-DPI screen, this icon type may have a `scale` property.

  The semantics of each property in the `<icon/>` tag are the same as for the `<icon/>` tag for catalog metadata. See <icon/>.

<description/> #

  A long description of this component. Some markup can be used.

  Do not assume the format is HTML. This list contains all currently supported formatting options:

  - Paragraph (`p`)

  - Ordered list (`ol`), with list items (`li`)

  - Unordered list (`ul`), with list items (`li`)

  - Section heading (`heading`), to divide a longer description into sections. It is comparable to a `h3` element in HTML, and is rendered as a heading for the content that follows it. A heading is a short label and should not be longer than 80 characters - use a paragraph for longer text. Headings are plain text and must not contain any markup, not even `em` or `code`.

    This element requires AppStream 1.2 or later. Older implementations will ignore it and not display its text at all, so a description must still make sense without its headings.

  - Within paragraphs and list items, emphasis (`em`) and inline code (`code`) text styles are supported. The emphasis is commonly rendered in italic, while inline code is shown in a monospaced font.

  - Nested lists are not supported

  In MetaInfo files, this tag should be translated by-paragraph. For enumerations, items are translated individually as well, and not the whole enumeration block. This means that in a translated file, only `<p/>`, `<heading/>` and `<li/>` elements may carry an `xml:lang` property.

  All text must be in paragraphs, section headings or list item elements - text that contained directly in a `description` element is not permitted.

<categories/> #

  This tag can contain one or more `<category>` entries, describing the categories this software component is associated with. This tag is usually applied to components of type `desktop-application`, but can be used with any component. A list of valid category names can be found in the Freedesktop menu specification (https://specifications.freedesktop.org/menu-spec/latest/category-registry.html). Example:

      <categories>
          <category>Game</category>
          <category>ArcadeGame</category>
      </categories>

<keywords/> #

  This tag can contain one or more `<keyword>` children, describing keywords for the component, to make it easier to find in a software center. For translated keywords in metainfo files, the individual `keyword` tags should be translated.

  Example:

      <keywords>
        <keyword translate="no">IDE</keyword>
        <keyword>development</keyword>
        <keyword>programming</keyword>
        <keyword xml:lang="de">entwicklung</keyword>
        <keyword xml:lang="de">programmierung</keyword>
      </keywords>

<url/> #

  Defines web URLs for this component. There are several different URL types allowed:

  homepage

    Should be a link to the upstream homepage for the component.

  bugtracker

    Should point to the software's bug tracking system, for users to report new bugs.

  faq

    Should link a FAQ page for this software, to answer some of the most-asked questions in detail, something which you cannot do in the component's description.

  help

    Should provide a web link to an online user's reference, a software manual or help page.

  donation

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

  translate

    URLs of this type should point to a webpage where users can submit or modify translations of the upstream project.

    Typically this should be a link to the project page in Weblate, Transifex or Zanata, but could also be a link to an upstream-hosted wiki page describing how to send translations upstream.

  contact

    URLs of this type should allow the user to contact the developer.

    This could for example be an HTTPS URL to an online form or a page describing how to contact the developer.

  vcs-browser

    URLs of this type should point to a webpage on which the user can browse the sourcecode.

  contribute

    URLs of this type should point to a webpage showing information on how to contribute to the described software project.

<launchable/> #

  This tag indicates possible methods to launch the software described in this component. It is allowed to appear multiple times in MetaInfo data.

  The `<launchable/>` tag has a required `type` property indicating the system that is used to launch the component. The following types are allowed:

  desktop-id

    The application can be launched via a desktop file. The value of the tag is a desktop-file id (https://specifications.freedesktop.org/desktop-entry-spec/latest/file-naming.html#desktop-file-id).

    In case a software component has multiple launchable entries, the software center might display a dialog to choose which entry to launch. If possible though, it should be avoided to add multiple `launchable` tags of type `desktop-id`.

  service

    The software can be started, stopped, and monitored by the OS "init" facility, such as systemd. The value of the tag is a name that can be used with that facility, such as a systemd unit name.

    Multiple `launchable` tags of type `service` are not alternatives to start the same service, but the component does contain multiple services that might all need to be started.

    Only those services should be listed as launchables that the user is actually expected to start and stop manually. Services that are started/stopped indirectly via dependencies of other services should not be listed.

    For systemd units, the services listed as launchables are expected to support enabling and disabling.

  cockpit-manifest

    The software can be launched from the menus of the Cockpit (https://cockpit-project.org) admin interface. The value of the tag is the name of a Cockpit package (https://cockpit-project.org/guide/latest/packages.html).

  url

    The application is a web site that is viewed through a browser. The value of the tag is a direct HTTP/HTTPS URL that the browser must navigate to.

  Example:

      <launchable type="desktop-id">org.gnome.sysprof2.desktop</launchable>

<releases/> #

  The `<releases>` tag contains multiple `release` children that themselves contain metadata about releases made for this software component. The release information XML is described in-depth in Section 2.2, “Release Information”, examples for a valid `releases` tag with artifacts are also provided there.

  Release information can be embedded in the component's metainfo file, following the XML description outlined in Section 2.2, “Release Information”. Alternatively, it can also be split into its own metadata file as described in that section. In case of external metadata, a `releases` tag must still be present in the component's metainfo file, and must have a `type` property set to value `external` (if the `type` property is missing, a value of `embedded` is implicitly assumed for it).

  In case of external metadata, the `releases` tag may also have an `url` property linking to a web location where the release XML can be found and updated separately from the main component metadata. An `url` property must not be present without `type` set to `external`.

  Only HTTPS links are allowed for the web URL, and any `artifact` defined in a release description from an external website should not be trusted without further verification, as external release information can currently not be signed.

  AppStream catalog metadata generators may choose to update the locally provided release information with the data from the web location provided by the URL in `url`. This allow projects to complete release localization after a release was made, or include further information that was not yet available directly at release time. The generated catalog XML data must be complete and must not contain references to external release information.

  Example for a `releases` block that points to an external metadata file:

      <releases type="external" url="https://example.org/releases/org.example.myapp.releases.xml" />

  ###### Important: Local Release Data

  Please note that even if release data is external and also provided on a remote location, it also must be available locally, installed as a file into `/usr/share/metainfo/releases/%{cid}.releases.xml`. The local file may not contain all information (for example it may not have a complete release description or all translations), but basic data such as the released versions and their release dates should be present.

  It is an error to reference an external release data file, but not provide a local copy of it.

<provides/> #

  The `provides` tag and its 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 contains a number of children describing the type and name of the provided public interface items. It is suggested that the build system auto-generates this tag and its children. Currently allowed item types are listed below. If you miss something, file a bug against AppStream (https://github.com/ximion/appstream/issues/new) so we can add the new type.

  <mediatype/>

    Describes the media types (also known as MIME types) this software supports, meaning it can open, edit or otherwise handle them. This tag is especially useful for generic components and addon-type components. For applications, the metadata may automatically be fetched from their `.desktop` files by the distribution's metadata generator if a desktop-entry file is set as <launchable/>. Example:

        <provides>
            <mediatype>text/html</mediatype>
            <mediatype>image/jpeg</mediatype>
            <mediatype>application/rss+xml</mediatype>
         </provides>

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

    Full name of a font provided by this component. See Section 2.8, “Fonts” for more information.

  <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, and out of tree kernel drivers.

  <firmware/>

    This provided element is described in detail for the `firmware` component type, where it is mandatory. Please see <provides/> ↪ <firmware/> for more information.

  <python3/>

    Name of a Python 3 module this component provides.

  <dbus/>

    Contains the well-known name of a D-Bus service as its value. The type of the service must be specified using the `type` property of this tag. Allowed values are `user` and `system`.

    Example:

        <provides>
          <dbus type="system">org.freedesktop.packagekit</dbus>
        </provides>

  <id/>

    Contains the component-ID of another software component. The presence of this tag indicates that the software component containing it is able to provide all functionality of the one referenced in the `<provides/> ↪ <id/>` tag.

    This is useful in case a component-id had to be renamed in the past, e.g. because its domain-name changed.

<requires/>, <recommends/> & <supports/> #

  The `requires` tag denotes an absolute requirement on a different entity. For example, a component can require certain hardware to be present, require a specific minimum kernel version, or another component to be installed first. If a requirement specified in a `requires` tag is not met, AppStream clients should prevent the installation of the particular software component.

  If it is not essential that a certain requirement is met by the system, but just recommended to be available, a `recommends` tag should be used. In this case, AppStream clients should allow the installation of the software component, but may display a warning before allowing the installation. It is permissible, but not required, to prevent installation of software which does not have all items specified as `recommends` met on the system that it is installed to.

  Components may also set a `supports` tag. This is an even weaker relation than `recommends`, and means the particular component can make use of certain hardware capabilities or other software if it is available, but will also be usable if it is not.

  A `requires`, `recommends` or `supports` tag contains children describing the type, value and version relation of the required item. Each child can have a `version` and a `compare` property, to allow depending on a certain minimal version of the respective item. The `version` property contains the version to be compared against, while the `compare` property contains a two-letter code denoting how to compare the version of a present item with the version listed in the property. If no `compare` property is given, but a `version` property is found, AppStream implementations should implicitly assume a value of `ge` for comparison of the versions. The installed version is on the left side of the required version when comparing them. See Section 4.1, “Version Comparison Algorithm” for a description of the version comparison algorithm.

  Possible two-letter codes for version comparisons are:

  - `eq` - Equal to

  - `ne` - Not equal to

  - `lt` - Less than

  - `gt` - Greater than

  - `le` - Less than or equal to

  - `ge` - Greater than or equal to

  Please note that not all item types are valid for all relation types. Generally valid item types are listed below, with information as for which relation kins they are valid.

  <id/> #

    A relation to another software component. The value should be another component-ID. Example:

        <requires>
          <id version="1.0" compare="ge">org.example.my_software</id>
        </requires>

    Valid for: `requires`, `recommends`, `supports`

  <modalias/> #

    Check for specific hardware to be present via its modalias. The modalias may contain a wildcard expression. Example:

        <recommends>
          <modalias>usb:v1130p0202d*</modalias>
        </recommends>

    Valid for: `requires`, `recommends`, `supports`

  <kernel/> #

    Check for a specific kernel to be running on the system. The kernel name is the output of `uname -s`. Example:

        <requires>
          <kernel version="4.14" compare="ge">Linux</kernel>
        </requires>

    Valid for: `requires`, `recommends`

  <memory/> #

    Set a relation to the amount of physical memory (RAM) the system should have to run the software component. The memory size is set in MiB. You usually only want to use this with the `recommends` tag, because users might want to install the software on systems even if they have a lesser amount of memory compared to what would be ideal. Example:

        <recommends>
          <memory>2048</memory> <!-- recommend at least 2GiB of memory -->
        </recommends>

    Valid for: `requires`, `recommends`

  <firmware/> #

    Depend on a specific device firmware. The value of this tag should either be a name like `bootloader`, be empty to reference the firmware itself described by the `firmware`-type component this tag is contained in, or contain a GUID. This tag is commonly used and interpreted by the LVFS (https://fwupd.org/). Example:

        <requires>
          <firmware compare="ge" version="0.1.2">6de5d951-d755-576b-bd09-c5cf66b27234</firmware>
          <firmware compare="ge" version="0.1.2"/>
          <firmware compare="ge" version="0.3.4">bootloader</firmware>
        </requires>

    Valid for: `requires`, `recommends`

  <hardware/> #

    Require, recommend or support a specific system hardware configuration. The value of this item is a Computer Hardware ID (CHID) (https://docs.microsoft.com/en-us/windows-hardware/drivers/dashboard/using-chids) without any surrounding braces.

    On Linux systems, the CHIDs of the system can be queried using the `sudo fwupdtool hwids` command.

    This tag is commonly used and interpreted by the LVFS (https://fwupd.org/) and fwupd tool. Example:

        <requires>
          <hardware>be6ab11f-af5f-572e-be18-84301d880764</hardware>
        </requires>

    Valid for: `requires`, `recommends`, `supports`

  <control/> #

    This item type can be used to indicate support for or require certain ways a user can control the software. This usually maps to certain methods of input. If multiples `control` tags with different values are found within a requires/supports block, only one of them needs to be satisfied on the system to mark an application as compatible. This means if `touch` and `pointing` are both supported as controls for an application-type component, a system that only has a mouse and no touchscreen will still be considered able to run the application. Valid values for this tag are:

    - `pointing` - Input via mouse/cursors/other pointing devices is possible

    - `keyboard` - Keyboard input is possible

    - `console` - Control via a console / command-line interface

    - `tablet` - Graphics tablet input

    - `touch` - Input by touching a surface with fingers is possible

    - `gamepad` - The component supports gamepads (any game controller with wheels/buttons/joysticks)

    - `tv-remote` - Input via a TV remote (with arrow keys, number pad, other basic inputs) is supported.

    - `voice` - The software can be controlled via voice recognition/activation

    - `vision` - The software can be controlled by computer vision / visual object and sign detection

    If a control type is supported (= in a `supports` block), it means the software supports the given method of user input. As long as one of the input methods is available on the system, the software can be used. Installation on systems without the given control may still be permitted, but the software may not be easily usable.

    If a control type is recommended (= in a `recommends` block), it means the software prefers the given method of user input. The software may still be installed if the input control method is not available, but functionality may be severely degraded.

    If a control type is required (= in a `requires` block), the same applies, but the software installer should refuse to install the software on devices which do not have at least one of the input methods. It is therefore advised to only use the `control` tag in `supports` and possibly `recommends` blocks, and avoid to use it in `requires`.

    For certain component types, some permitted controls are implicitly assumed: For desktop-application and web-application components, `pointing` and `keyboard` controls are assumed supported, unless explicit support is defined by the metadata author. For console-application, control via `console` is assumed.

    For any other, non-application-like component types, the `control` relation item is currently considered unsupported.

    Example control support block:

        <supports>
          <control>pointing</control>
          <control>keyboard</control>
          <control>touch</control>
        </supports>

    Valid for: `requires`, `recommends`, `supports`

  <display_length/> #

    Set a relation to the display length defined as an integer value in logical pixels (device pixels divided by scaling factor, roughly equivalent to 0.26mm (1/96in), also known as device-independent pixels). Setting the `side` property to either `shortest` or `longest` will apply the selected size constraint to either the shortest or longest side of the display rectangle, with `shortest` being implicitly assumed if no value is set.

    ###### Note: About Pixel Dimensions

    One logical pixel (= device independent pixel) roughly corresponds to the visual angle of one pixel on a device with a pixel density of 96dpi and a distance from the observer of about 52cm, making the physical pixel about 0.26mm in size. When using logical pixels as unit, they might not always map to exact physical lengths as their exact size is defined by the device providing the display. They do however accurately depict the maximum amount of pixels that can be drawn in the depicted direction on the device's display space.

    Relations for the display length can be defined using a `compare` property as described in <requires/>, <recommends/> & <supports/>. If this property is not present, a value of `ge` (greater-or-equal) is implicitly assumed.

    Keep in mind that constraints are checked against the shortest side of the display by default: When setting an upper bound (via `lt` or `le`) to exclude large screens, you will almost always want to set the `side` property to `longest`, as even very large displays can have a comparatively short shortest edge. A 4K television, for example, has a shortest edge of only 2160 logical pixels and would therefore satisfy a `<display_length compare="lt">3840</display_length>` constraint applied to the (default) shortest side.

    ###### Note: Determining Device Types

    Please note that a display with a lot of vertical space may not be a television screen, but could also be a large gaming monitor. Similar logic applies to the smaller screen sizes. Therefore, to indicate that an application runs well on a certain device and not just on a certain display, additional metadata is needed, like the application's supported input controls as defined via <control/>.

    ###### Note: Sizes for Reference

    The sizes below are for reference if you do not know the exact dimensions your application will fit into, and just need a rough guideline as to what device type you can expect at a given size:

    - Very small screens, as used in watches, wearables and other small-display devices: about <= 360px

    - Small screens often used in handheld devices, such as phone screens, small phablets: about < 768px

    - Screens in laptops, tablets: about >= 768px

    - Bigger computer monitors: about >= 1024px

    - Television screens, large projected images: about >= 3840px

    This tag may appear up to four times to set a minimum and maximum dimension required. If multiple displays are connected to a device, it is acceptable to test against either the largest screen attached to the device, or the combined amount of display space (depending on what makes the most sense for the respective device / setup). A software center application may test for the maximum possible resolution of an attached display, and not the currently set display resolution in case it wants to check against hardware capability and not be influenced by user configuration.

    If used in a `requires` block, this relation can be used to restrict an application to only be installable on systems which have a minimum usable display length available for it. If used in a `recommends` block, the application will still be installable, but the user may be shown a warning.

    If no `display_length` relation is present, a minimum required display (`ge`) relation of `768px` is implicitly assumed to preserve backwards compatibility (so applications capable of running on smaller screens need to make their support for that configuration explicit).

    Examples:

        <!-- recommend at least 600 logical pixels of space -->
        <recommends>
          <display_length compare="ge">600</display_length>
        </recommends>

        <!-- ensure this application is not run on a very large screen, or
             very small screen (no tiny handhelds or television screens) -->
        <requires>
          <display_length side="longest" compare="lt">3840</display_length>
          <display_length compare="gt">360</display_length>
        </requires>

    Valid for: `requires`, `recommends`

  <internet/> #

    Require, recommend or support connectivity to the internet. The value of this item one of the following:

    - `always` - Needs internet connectivity to work. If used in a `recommends` element, then this indicates that the app can work without internet, but the experience will be degraded.

    - `offline-only` - Never uses the internet, even if it’s available.

    - `first-run` - Uses the internet the first time the application is run, but not normally afterwards.

    If the value of `<internet/>` is not `offline-only`, the `bandwidth_mbitps` attribute can be set to a bandwidth (in Mbit/s) which is the minimum internet bandwidth needed for the application to be usable. If this attribute is not set, it’s assumed that the application is usable with all internet connections.

    Examples:

        <!-- always needs the internet -->
        <requires>
          <internet>always</internet>
        </requires>

        <!-- always needs the internet and has a degraded experience if it’s not at least 2Mbit/s -->
        <requires>
          <internet bandwidth_mbitps="2">always</internet>
        </requires>

        <!-- never uses the internet, even if available -->
        <requires>
          <internet>offline-only</internet>
        </requires>

        <!-- the software explicitly supports running offline (but may also be able to use online features) -->
        <supports>
          <internet>offline-only</internet>
        </supports>

        <!-- requires the internet on first run -->
        <requires>
          <internet>first-run</internet>
        </requires>

        <!-- can work without the internet, but with a degraded experience -->
        <recommends>
          <internet>always</internet>
        </recommends>

        <!-- recommends the internet for when it’s first run, but can work without -->
        <recommends>
          <internet>first-run</internet>
        </recommends>

        <!-- requires the internet on first run, can run without it afterwards but with a degraded experience -->
        <requires>
          <internet>first-run</internet>
        </requires>
        <recommends>
          <internet>always</internet>
        </recommends>

    Valid for: `requires`, `recommends`, `supports`

<replaces/> #

  The `replaces` tag denotes indicates that the given component completely replaces another one on the system. In most cases, the replaced component and the one that replaces it can not be coinstalled. Compared to a <provides/> ↪ `id` relationship, for a replaced component there is no common interface that two components can provide at once.

  A `replaces` tag has `id` children which have the component-IDs of the components that the current component replaces as value.

  This feature is usually used for components that have to change their ID. While metainfo data may contain `replaces` tags, software repository providers should filter these tags carefully to ensure that the new component has the right to replace an old one.

  Example:

      <!-- the 7-zip application changes its ID and therefore replaces the component with its old ID -->
      <id>org._7_zip._7zip</id>
      [...]
      <replaces>
        <id>org.7-zip.7zip</id>
      </replaces>

<mimetypes/> #

  This tag can contain one or more `<mimetype/>` children, describing the MIME types this application supports.

  ###### Important: Deprecation

  This tag is deprecated and should not be used for new metadata. Please use <provides/> ↪ `mediatype` tags instead.

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

<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 (https://specifications.freedesktop.org/menu-spec/latest/onlyshowin-registry.html). Software center applications will only recognize these values.

<project_license/> #

  The `<project_license/>` tag is indicating the license of the component (application/library/addon/font/etc.) described in the metadata document. It should be an SPDX license expression (https://spdx.org/specifications). Please note the SPDX license IDs are case-sensitive in AppStream. Possible values include:

  - `GPL-2.0`

  - `LGPL-3.0+ AND GPL-3.0+`

  - `MIT`

  - `CC-BY-SA-2.0`

  - `LicenseRef-proprietary=https://example.com/mylicense.html`

  A full list of recognized licenses and their identifiers can be found at the SPDX OpenSource License Registry (https://spdx.org/licenses/).

  Custom licenses which are not in the SPDX registry, like proprietary licenses, can be denoted using the `LicenseRef` notation. `LicenseRef-proprietary` can be used to denote a proprietary license, with an optional URL to the license text following after a `=` sign.

  The license given in the `project_license` tag should be the ‘main’ license of the project. For a software project, this is typically the license for the code. It is not recommended to include the license for accompanying documentation (for example) in `project_license`, as that could confuse users. In particular, the `CC-BY-SA-3.0` license which is commonly used for documentation is not an (FSF or OSI) approved license for free software, so including it in `project_license` results in the project as a whole being considered non-free.

  Although the `project_license` tag is not mandatory, it is highly recommended to include it.

  Examples:

      <project_license>LGPL-3.0+ OR MPL-2.0</project_license>
      <project_license>LGPL-3.0+ OR MPL-2.0</project_license>
      <project_license>GPL-3.0-or-later</project_license>
      <project_license>LicenseRef-proprietary=https://code.visualstudio.com/license</project_license>

<developer/> #

  The `<developer/>` element is designed to represent the developers or project responsible for development of the project described in the metadata. It must appear only once per component.

  The element should have a `id` property, containing a unique ID to identify the component developer / development team. It is recommended to use a reverse-DNS name, like `org.gnome` or `io.github.ximion`, or a Fediverse handle (like `@user@example.org`) as ID to achieve a higher chance of uniqueness.

  A `developer` element must have one `name` tag as child, which contains a translatable name for the component developer or development team. Values might be for example "The GNOME Foundation" or "The KDE Community". Hyperlinks or emails must not be used in the name; if you want to link to the developer's homepage, use the <url/>-tag instead. The `name` tag is translatable, it must only exist once in its untranslated form.

<developer_name/> #

  The `<developer_name/>` tag is designed to represent the developers or project responsible for development of the project described in the metadata.

  ###### Important: Deprecation

  This tag is deprecated and should not be used for new metadata. Please use <developer/> instead.

<screenshots/> #

  Visual components (like fonts or graphical applications) may choose to add one or multiple screenshots to their metadata. Screenshots can be either a video or a static image.

  The `<screenshots/>` tag contains multiple `<screenshot/>` children, where at least one of them must have the property `type="default"` to indicate the primary and most representative screenshot of the software.

  Optionally, a `screenshot` may also have an `environment` property. This string property denotes the GUI environment the screenshot was recorded in, in the form of `{env}:{style}`, where `{env}` is a desktop-environment name in lowercase and `{style}` is a specific style that the desktop environment recognizes, e.g. `light` and `dark` for light and dark themes. The `:{style}` part of the environment property may be omitted if the environment's default style is used. See desktop-style-ids.txt (https://github.com/ximion/appstream/blob/main/data/desktop-style-ids.txt) for a list of currently recognized environment and style combinations.

  Software centers displaying the component will usually prefer screenshots of the current environment and style, and display them first, even before the screenshot marked as `default`.

  In general, screenshots should be displayed in the order the are defined in in their `screenshots` block for the respective component on a per-environment basis (all screenshots of the same environment/style will be displayed in the order they are listed in the XML, but may be moved to the front of the list as a whole depending on the current environment).

  Every `<screenshot/>` element must have at least one `<image/>` or `<video/>` child, but never an `image` and `video` at the same time.

  Screenshots containing videos must not be the default screenshot.

  The value of the `<image/>` tag is a direct HTTP/HTTPS URL to a screenshot uploaded to a public location on the web. Images should ideally be provided in the PNG format; using JPEG, WebP or JXL is also permitted for screenshot images in metainfo files.

  The `<image/>` tag may have the following properties:

  - `type`

    The type of the image: `source` for the source image, and `thumbnail` for a thumbnail image. In case the type is `thumbnail`, the `width` and `height` properties must be present.

  - `width`

    The width of the image in pixels.

  - `height`

    The height of the image in pixels.

  - `scale`

    A scaling factor for the image, if it is intended for a HiDPI display. If a scaling factor > 1 is set, the `width`/`height` values are not adjusted to scale. They always represent the exact image dimensions in pixels.

  - `xml:lang`

    The language this screenshot image is translated in. This property should only be present if there are multiple images with different locales present.

  The value of the `<video/>` tag is a direct HTTP/HTTPS URL to a video uploaded to a public location on the web. The video must be in a Matroska (.mkv) (https://www.matroska.org/) or WebM (https://www.webmproject.org/) container and use either the VP9 (https://www.webmproject.org/vp9/) or AV1 (https://aomedia.org/av1-features/) codec. The video should ideally work without any audio, but if audio is needed, the Opus (https://opus-codec.org/) codec should be used. Software centers may still play the video without any sound though. Additionally, AppStream metadata repositories (like in distributions such as Fedora and Debian) may impose size limitations to video files delivered by their CDN, so it is recommended to keep the video file size below 10MiB. There is also a chance that software centers do not display any video at all, so a video must never be in a default screenshot.

  The `<video/>` tag may have the following properties:

  - `container`

    The video container that is used, can be `webm` or `matroska`.

  - `codec`

    The video codec used, can be `av1` or `vp9`.

  - `width`

    The width of the video in pixels.

  - `height`

    The height of the video in pixels.

  - `xml:lang`

    The language this video is translated in. This property should only be present if there are multiple videos with different locales present.

  Optionally, a `<screenshot/>` tag may have a translatable `<caption/>` child, defining a short (ideally not more than 100 characters) description of what the user can see on the referenced screenshot.

  A `source` video should be concise, easy to understand and not have an overly large file size. Try to use a reasonably large image for `source` images, as they may be scaled down to `thumbnail` images in metadata processing. It is suggested to have videos and images in 16:9 aspect ratio, as long as that is sensible for the displayed application.

  Example:

      <screenshots>
        <screenshot type="default">
          <caption>The FooBar main window.</caption>
          <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1.png</image>
        </screenshot>
        <screenshot>
          <caption>Foobar showing the frobnicate functionality.</caption>
          <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-2.png</image>
        </screenshot>
        <screenshot>
          <video codec="av1" width="1600" height="900">https://example.com/foobar/screencast.mkv</video>
        </screenshot>

        <screenshot environment="plasma-mobile">
          <caption>The FooBar main window, but on Plasma Mobile</caption>
          <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1_plasma-mobile.png</image>
        </screenshot>

        <screenshot environment="gnome:dark">
          <caption>The FooBar main window, on GNOME in dark mode</caption>
          <image type="source" width="1600" height="900">https://example.com/foobar/screenshot-1_gnome_dark.png</image>
        </screenshot>
       </screenshots>

<translation/> #

  The `<translation/>` tag is an optional tag which can be added to specify the translation domain used for this software component. It may be used by the AppStream distro metadata generator to determine the translation status of the respective software (e.g. which languages the software is translated into and how complete the translations are).

  The tag must have a `type` property, assuming the value of the translation system which is used. Right now, allowed translation systems and values for `type` are:

  - `gettext`

  - `qt`

  In case a software components gets its translation from multiple translation domains, the `<translation/>` tag may be defined more than once.

  The source strings in the component are assumed to be in the `en_US` locale. If that is not the case, specify the source locale in POSIX format using the `source_locale` attribute on the `<translation/>` tag. The metadata generator will use the source locale to synthesize a `<lang/>` tag for the source locale, with 100% translation.

  For Gettext translations, localization data will be looked for in `${prefix}/share/locale/${locale}/LC_MESSAGES/${id}.mo`, where `${id}` is replaced with the translation domain specified in the `<translation/>` tag. For Qt translations, if the ID string contains slashes, we will look for translations following either the `${prefix}/share/${id}_${locale}.qm` or the `${prefix}/share/${id}/${locale}.qm` pattern. If no slashes are contained, we will look for translation data in `${prefix}/share/locale/${locale}/LC_MESSAGES/${id}.qm`.

  Example:

      <translation type="gettext">foobar</translation>
      <translation type="gettext" source_locale="de_DE">foobar</translation>
      <translation type="qt">FooBar/translations/foobar</translation>

<suggests/> #

  The `<suggests/>` tag is an optional tag which can be added to specify the component-ids of other software this components suggests. Software centers might present the suggested software on the installation page of the described component.

  The tag may have a `type` property, with the value `upstream`, indicating that this suggestion originates from the upstream project. If no `type` property is given, `upstream` is implicitly assumed as value. Metainfo files must not define other `suggests` types, those are reserved for AppStream catalog XML (see <suggests/> in catalog XML).

  The `suggests` tag must have one or more `<id/>` tags as children, specifying the IDs of the suggested other software components.

  Example:

      <suggests>
        <id>org.kde.gwenview.desktop</id>
        <id>org.inkscape.inkscape</id>
      </suggests>

<content_rating/> #

  The `<content_rating/>` tag is an optional tag which can be added to specify age ratings for the respective software components. These maybe be used for parental control or to display their information in software centers.

  The tag must have a `type` property, indicating the type of the rating system that is used. At the moment, the Open Age Ratings Service (https://hughsie.github.io/oars/) (value `oars-1.0`) is supported natively, but more services might be added in future.

  The `<content_rating/>` tag may have `<content_attribute/>` children which each must have an `id` property indicating the specific section that is rated. Their value indicates the intensity of the rated section and can be one of:

  - `none` - no rating given

  - `mild`

  - `moderate`

  - `intense`

  In case the `<content_rating/>` tag is empty (no `<content_attribute/>` is present), it is assumed that the component was checked for age ratings and no age restrictions apply.

  The website of the Open Age Ratings Service provides an online form (https://hughsie.github.io/oars/generate.html) which will automatically generate AppStream compatible metadata based on a set of questions answered about the content.

  Example:

      <content_rating type="oars-1.0">
        <content_attribute id="drugs-alcohol">moderate</content_attribute>
        <content_attribute id="language-humor">mild</content_attribute>
      </content_rating>

<agreement/> #

  The `<agreement/>` tag is an optional tag which can be added to specify agreements the user has to accept or acknowledge before using the software. This tag can appear multiple times, if multiple agreements are required for a software component.

  The tag should have a `type` property, indicating the type of the agreement. If the `type` property is missing, an agreement of type `generic` is assumed. Currently recognized agreement types are:

  - `eula` - an end-user license agreement the user has to accept before installing the software.

  - `privacy` - a privacy statement for the software, usually a GDPR (https://www.eugdpr.org/) compliant statement

  The `<agreement/>` tag must have a `version_id` property, containing a version identifier for the license. It may be used by client applications to determine whether an agreement needs to be shown again after it has been accepted already by the user.

  Every `<agreement/>` must have `<agreement_section/>` children which each have an `id` property indicating the specific section that they describe (e.g. `introduction`). These values may be used to automatically jump to a specific section. Each `<agreement_section/>` has a translatable `name` child denoting the name or title of the respective section, and a `description` child that is translated according to the same translation rules that apply to the <description/> tag. The `description` contains the content of the respective agreement section.

  Example:

      <agreement type="privacy" version_id="1.0">
          <agreement_section id="introduction">
            <name>Introduction</name>
            <description>
              <p>
                We hold personal data about vendors, administrators, clients and other
                individuals for a variety of purposes.
                [...]
              </p>
            </description>
          </agreement_section>

          <agreement_section id="scope">
            <name>Scope</name>
            <description>
              <p>
                This policy applies to all users who have access to any of the personally
                identifiable data.
              </p>
            </description>
          </agreement_section>

          [...]
      </agreement>

<update_contact/> #

  The `<update_contact/>` tag is an optional tag which can be added to provide an email address distributors can use to contact the project about invalid or incomplete metadata or – in case the specification has changed – about old metadata. It can also be used to ask general questions in case of an update of the component described in the metadata file.

  The `<update_contact/>` tag must only be used by distributors. It is not included in the distribution-provided AppStream XML file, and therefore not exposed to the end user via any kind of UI.

  Upstream authors might decide to add an email address in cleartext, but spam protection using `_AT_` is also valid. The value of this tag is generally treated a case-insensitive way.

  Example:

      <update_contact>developer_AT_example.com</update_contact>

<name_variant_suffix/> #

  Variant suffix that software centers may append to the component name on lists in case multiple components have the same name. This is currently primarily used for firmware, where components only need to be distinguished if multiple variants are displayed. A name variant suffix could e.g. be 'Prerelease' or 'China'.

<branding/> #

  The `<branding/>` tag is an optional tag which defines properties affecting the branding and presentation of the component. It usually affects how the component is displayed in software centers and on websites.

  The tag may currently only contain `color` tags as children, defining accent colors for the component. Each `color` element contains an HTML hexadecimal color string as its value. This string must start with a `#` character. An accent color may for example be used as the background behind the logo/icon of an application.

  A `color` tag must have a `type` attribute which denotes the color type. The color type may currently only be `primary`. A `color` tag may have an optional `scheme_preference` attribute which denotes a preference for a particular color scheme where this color should be used over other colors. Values for this attribute may either be `light` or `dark` for a light or dark theme preference. Each color type/scheme combination may only appear once.

  Example:

      <branding>
        <color type="primary" scheme_preference="light">#ff00ff</color>
        <color type="primary" scheme_preference="dark">#993d3d</color>
      </branding>

<tags/> #

  The `<tags/>` tag is an optional tag which can be used to give the component one or multiple arbitrary labels. For example, it can be used for apps to tag themselves as "featured" in specific software centers, or to group software together by some well-defined criteria.

  The interpretation of tags is completely defined by the client application that is reading AppStream metadata. Tags defined in metainfo files may be filtered by catalog metadata generators, and may even be completely ignored by clients. Components must not rely on the presence of specific tags to behave correctly.

  The `tags` tag must have `tag` children which must have a value comprised only of lower-case ASCII characters, dots, hyphens and numbers. Spaces are not allowed. The tag must also have a `namespace` attribute to designate a namespace where the particular tag is valid. The namespace is an arbitrary string which has the same character limitations as the tag value. It may for example be the name of the client too that consumes the data, or the name of the organization the tag belongs to.

  Example:

      <tags>
        <tag namespace="lvfs">vendor-2021q1</tag>
        <tag namespace="plasma">featured</tag>
      </tags>

<references/> #

  The `<references/>` element is an optional tag to indicate references to this component in other registries. This is primarily used for scientific registries, citation information and DOI (Digital Object Identifier (https://en.wikipedia.org/wiki/Digital_object_identifier)) associations.

  This information is primarily consumed by specialized tools, but may also be shown by software centers or read by the applications themselves to compose references.

  The `references` element may have `doi` children containing DOI identifier strings as value, `citation_cff` children containing a link to a citation file in CFF (Citation File Format (https://citation-file-format.github.io/)) format or `registry` children. A `registry` child must have a `name` property containing the name of a registry referencing this component, while the value of it must be the identification string in the respective registry.

  Example:

      <references>
        <doi>10.1000/182</doi>
        <registry name="SciCrunch">SCR_000000</registry>
        <citation_cff>https://example.org/CITATION.cff</citation_cff>
      </references>

<custom/> #

  The `<custom/>` tag is an optional tag which can be used as a key-value store for custom values that are not covered by the AppStream specification. The tag is usually stripped out or filtered by catalog metadata generators, such as `appstream-generator`. When present, the data contained in a `custom` can be read by all tools making use of AppStream metadata, making it an ideal extension point when using an existing AppStream library is desired and some custom additions to the metadata are still required. The `custom` tag is also often used for prototyping new features in AppStream.

  The tag must have `value` children which must have a `key` property. The value of the `value` tag denotes a user-defined value, while the key string set for the `key` property denotes a user-specified key string. The key must be unique; multiple keys with the same name are not allowed.

  To avoid name conflicts, it is recommended to prefix keys with a vendor prefix, like `GNOME::` or `KDE::`.

  ###### Note

  Before using a `custom` tag, please consider if there is a better way to achieve your goal than adding the data to the AppStream metainfo file, or whether AppStream maybe already contains a way to achieve what you want. Additionally, if you think that the purpose you use the `custom` tag for is generally useful, please file a feature request against AppStream, so we can discuss adding the new feature to the specification and make it more usable for a bigger audience.

  Example:

      <custom>
        <value key="MyCorp::app_color">#FF0000</value>
        <value key="MyCorp::special_id">284fd262-6870-42a6-89a4-b189d3109e3e</value>
      </custom>

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

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

      <provides>
        <library>libfoobar.so.2</library>
        <font>foo.ttf</font>
        <binary>foobar</binary>
      </provides>
      <releases>
        <release version="1.2" date="2015-02-16" />
      </releases>
      <developer id="org.example">
        <name>FooBar Team</name>
      </developer>
    </component>

For a component of type `generic`, the minimal amount of required tags is: <id/>, <name/>, <summary/>, <metadata_license/>.