https://specifications.freedesktop.org/metainfo/1.0
.
<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.
/usr/share/metainfo/%{id}.metainfo.xml
, where id
is a unique identifier of this specific component.
Note
/usr/share/metainfo/%{id}.appdata.xml
.
Legacy Path
/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 might be dropped completely in future.
<component>
tag as the root element. The <component>
element must at least have an id
, name
and summary
tag; and a provides
tag with appropriate children is highly recommended. All possible tags in the generic set are:
<id>
tag is a unique identifier for this component. It must contain only ASCII characters, dots, hyphens and numbers. 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). It is also strongly discouraged to start any segment of the ID with a digit.
{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.
com.hugski.ColorHug2
for the client tools to control hardware, and com.hugski.ColorHug2.firmware
for the runtime firmware files.
Escaping characters in the component ID
org.7-zip.7Zip
could become org._7_zip._7Zip
.
<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 can result in your data not being incorporated into the distribution metadata (so this is a required tag).
CC0-1.0
CC-BY-3.0
CC-BY-SA-3.0
GFDL-1.3
MIT
FSFAP
CC-BY-SA-3.0
corresponds to the license at creativecommons.org/licenses/by-sa/3.0.
<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.
remote
icons loaded from a remote URL. Currently, only HTTP/HTTPS urls are supported. This icon type should have width
and height
properties.
p
), ordered list (ol
) and unordered list (ul
) are supported at this time.
<p/>
child has a language property.
<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 spec. Example:
<categories> <category>Game</category> <category>ArcadeGame</category> </categories>
<launchable/>
tag has a essential type
property indicating the system that is used to launch the component. The following types are allowed:
launchable
tags of type desktop-id
.
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.
<launchable type="desktop-id">org.gnome.Sysprof2.desktop</launchable>
<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.
release
tag can have the properties version
, date
and timestamp
. The date
property can have any time in ISO 8601 format as its value and should be present for every release. The timestamp
tag contains the release time in the form of a UNIX epoch. This tag should not be used in metainfo files in newly written metadata, but will still be parsed in case it is present. The timestamp
property is mainly used in generated distro-metadata. In case both release-time tags are present, the timestamp
tag will take precedence over date
.
<release/>
tag may also have an urgency
property, having one of the following values:
low
medium
high
critical
urgency
defines how important it is to install the new release as an update. This is especially important for type=firmware
components. If no urgency is defined, a medium
urgency is implicitly assumed. The urgency defines how the update will be presented to the user, and sometimes if it will be installed automatically and immediately, or delayed.
release
tag may have a type
property to classify releases with one of the following values:
stable
development
stable
is assumed. A software displaying a listing of releases should only show stable releases and discard any development release if the current version is itself stable. It can show all versions when development versions of the software are also distributed.
release
tag may have a description
tag as child, containing a brief description of what is new in the release. The description
tag is structured as described in <description/>.
release
tag may also have one or multiple size
tags as children, which define the installed and download size of this component release. This is useful in case the component does not have a corresponding native package in a distribution, for example if it is a Limba bundle or LVFS firmware. The size type is defined via a type
property on the size
tag, and may assume the value download
or installed
. The size itself is set as the value and must be given in bytes.
<releases> <release version="1.2" date="2014-04-12" urgency="high"> <size type="download">12345678</size> <size type="installed">42424242</size> </release> <release version="1.1" type="development" date="2013-10-20" /> <release version="1.0" date="2012-08-26" /> </releases>
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.
provides
tag contain 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 so we can add the new type.
/usr/lib
, /usr/lib/<triplet>
or /lib
. For example, for the libappstream library, the value for library
would be libappstream.so.1
.
PATH
.
firmware
component type, where it is mandatory. Please see <provides/> ↪ <firmware/> for more information.
type
property of this tag. Allowed values are user
and system
.
<provides> <dbus type="system">org.freedesktop.PackageKit</dbus> </provides>
<provides/> ↪ <id/>
tag.
requires
tag denotes an absolute requirement on a different system component. A component can require a certain hardware to be present, or kernel, or other component to be installed first. If a requirement is not met, AppStream clients should prevent the installation of the particular software component.
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 it.
requires
or recommends
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. Possible two-letter codes for version comparisons are:
eq
- Equal to
ne
- Not equal to
lt
- Lesser than
gt
- Greater than
le
- Lesser than or equal to
ge
- Greater than or equal to
<requires> <id version="1.0" compare="ge">org.example.MySoftware</id> </requires>
<recommends> <modalias>usb:v1130p0202d*</modalias> </recommends>
uname -s
. Example:
<requires> <kernel version="4.14" compare="ge">Linux</kernel> </requires>
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>
<mimetype/>
children, describing the MIME types this application supports. This tag is especially useful for generic components and addon-type components. For applications, the metadata will automatically be fetched from their .desktop
files by the distribution's metadata generator. Example:
<mimetypes> <mimetype>text/html</mimetype> <mimetype>image/jpeg</mimetype> <mimetype>application/rss+xml</mimetype> </mimetypes>
<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
<project_license/>
tag is indicating the license of the component (application/library/addon/font/etc.) described in the metadata document. It should be a SPDX license expression. Possible values include:
GPL-2.0
LGPL-3.0+ AND GPL-3.0+
MIT
CC-BY-SA-2.0
project_license
tag is not mandatory, it is recommended to include it.
<developer_name/>
tag is designed to represent the developers or project responsible for development of the project described in the metadata.
<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/>
child.
<image/>
tag is a direct HTTP/HTTPS/FTP URL to a screenshot uploaded to a public location on the web. The <image/>
tag may have the following properties:
type
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
height
xml:lang
<screenshot/>
tag may have a translatable <caption/>
child, defining a short (ideally not more than 256 characters) description of what the user can see on the referenced screenshot.
<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> </screenshots>
<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.
<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.
_AT_
is also valid. The value of this tag is generally treated a case-insensitive way.
<update_contact>developer_AT_example.com</update_contact>
<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.
type
property, assuming the value of the translation system which is used. Right now, allowed translation systems and values for type
are:
gettext
qt
<translation/>
tag may be defined more than once.
<translation type="gettext">foobar</translation>
<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.
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).
suggests
tag must have one or more <id/>
tags as children, specifying the IDs of the suggested other software components.
<suggests> <id>org.kde.gwenview.desktop</id> <id>org.inkscape.Inkscape</id> </suggests>
<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.
type
property, indicating the type of the rating system that is used. At the moment, the Open Age Ratings Service (value oars-1.0
) is supported natively, but more services might be added in future.
<content_rating/>
must have <content_attribute/>
children which each 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
<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/>
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.
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 compliant statement
<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.
<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.
<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>
<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 collection 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.
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.
GNOME::
or KDE::
.
Note
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.
<custom> <value key="MyCorp::app_color">#FF0000</value> <value key="MyCorp::special_id">284fd262-6870-42a6-89a4-b189d3109e3e</value> </custom>
<?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">http://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_name>FooBar Team</developer_name> </component>
generic
, the minimal amount of required tags is: <id/>, <name/>, <summary/>, <metadata_license/>.