2 Upstream Metadata #

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 with underscores, and prefix every leading digit of a section 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.7zip could become org._7_zip._7zip.

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:

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.

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

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

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

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:

In metainfo files, this tag should be translated by-paragraph, meaning that in a translated file, each translated <p/> child has a language property.

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/apa.html). Example:

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

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>

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

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

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

Example:

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

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.

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.

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:

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.

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>

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.

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.

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/apb.html). Software center applications will only recognize these values.

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:

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>

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

Values might be for example "The GNOME Foundation" or "The KDE Community". You must not include hyperlinks or emails in this field; if you want to link to the developer's homepage, use the <url/>-tag instead.

This tag is translatable.

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 screenshot of the software. Every <screenshot/> tag must have at least one <image/> or <video/> child, but never an image and video at the same time.

Screenshots containing a video 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 or WebP is also permitted for images in metainfo files.

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

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:

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

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:

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

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>

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:

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>

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:

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 type="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 type="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>

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>

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

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>

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>

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>