How GNOME Software uses metadata
GNOME Software displays a hardware support tile on the details page for an application. This combines information about the hardware requirements of the application, and the hardware capabilities of the computer, with the aim of highlighting incompatibilities or missing requirements — or to indicate that the application should work correctly with no incompatibilities.
Currently, the code looks at the following hardware. More may be supported in future.
- Whether a touchpad, mouse or keyboard is present/needed
- Whether a gamepad is needed
- The minimum and recommended display size that the app can scale to
It’s not possible to reliably detect whether a gamepad is present, as they are often left disconnected due to not being needed for normal computer use.
The dialog which appears when the tile is clicked lists the different hardware requirements of the app, and whether any of them are not met.
You can improve the hardware information:
GNOME Software displays an age rating tile on the details page for an application. This shows what age range the application should be suitable for, based on different kinds of content which the application has declared it contains. This information is summarised in a format similar to the game or film rating certificates for your country.
For example, this will highlight whether a game contains violence, or whether an application contains in-app advertising.
The dialog which appears when the tile is clicked lists the different types of content in the application and how severe that content is.
You can improve the age rating information:
GNOME Software displays a safety tile on the details page for an application. This summarises information about whether the app can be considered safe to install and run, or whether caution may be required before trusting it.
This tile combines information about the permissions which the app requests when it runs (such as permission to read your files), with information about how the app was developed. Free software applications, where the source code is publicly readable, can be more secure than proprietary ones, as they can be audited.
The dialog which appears when the tile is clicked lists the different permissions the app requests, plus some information about its license and runtime.
You can improve the safety information:
GNOME Software displays a storage tile on the details page for an application. If the application is not installed, this displays the estimated download size needed to install it. If the application is installed, it displays the storage space used by the application.
The sizes are calculated from data provided by the GNOME Software backend (such as flatpak or an RPM), and are not specified in the metadata provided by the application. There is nothing you can do to affect this tile by editing an application’s metainfo file. It’s listed here for completeness.
GNOME Software displays a tile indicating whether an application is free software or whether it’s proprietary. This tile includes more detailed information about the project’s license. This tile also lists some of the benefits of free software.
Sometimes the license information isn’t correct for an application, and hence an application which is actually free software will be shown as ‘proprietary’.
You can improve the license information:
GNOME Software displays a list of links for an application, giving the user access to related resources. This includes the application’s home page, its bug reporting page, a way to donate to the application’s developers, and information on contributing translations to the application.
Some or all of these links may be present depending on whether they are listed in the application’s metainfo.
You can improve the links:
Applications which are featured by GNOME Software are displayed in a carousel at the top of the main window. Each carousel tile has a background colour which is automatically extracted from the application’s icon. Sometimes this background colour is not quite right for the application and needs to be specified explicitly by the application developer.
The set of applications which are featured is decided by the Linux distribution maintainers.
You can improve the carousel tile:
Where metadata comes from
The metadata used to specify what hardware a piece of software requires, what ages of user it is suitable for, and factors which contribute to how safe it might be to install, all come from the metainfo file for that software.
The metainfo file format is specified in the AppStream specification.
What happens if metadata is missing
If some metadata is missing for an application, GNOME Software can only guess what it might be, and hence can’t present much information in its interfaces. The guesses GNOME Software makes are based on the fact that most software is designed for desktop computers.
You can help improve the metadata for an application! See below for a guide on how to do that.
How to add missing links
The links for an application are stored as
<url> elements within the application’s
<component> in its metainfo file.
Add as many of the link types documented in the appstream specification as are available for the application. If no suitable page exists for a given link type, it doesn’t have to be included.
<url type="bugtracker">https://gitlab.gnome.org/GNOME/gnome-software/-/issues/new</url> <url type="donation">https://www.gnome.org/donate/</url> <url type="homepage">https://wiki.gnome.org/Design/Apps/Software</url> <url type="translate">https://wiki.gnome.org/TranslationProject</url>
How to add missing hardware information
The hardware information for an application is stored in the
<recommends> elements within the application’s
<component> in its metainfo file.
Unfortunately this data, if present, is currently inadvertently stripped by Flathub, which means that if it’s added in applications’ metainfo files, it currently won’t appear in the appstream file published by flathub. This issue is being worked on.
How to add missing content rating information
The content rating information for an application is stored in the
<content_rating> element within the application’s
<component> in its metainfo file.
Applications should use the OARS 1.1 standard to fill in this element. If the
<content_rating> element is not specified, the application’s content rating is unknown. If it’s specified but empty, the application has no content which might be unsuitable for any audience.
Use the OARS generator to produce suitable content rating information for an application.
How to fix incorrect licensing information
The licensing information for an application is stored in the
<project_license> element within the application’s
<component> in its metainfo file.
The content in this element should be an SPDX expression which describes the ‘main’ license for the project. This should typically be the license of the code, and not include the license of the documentation or ancillary content.
If the SPDX expression is a single license, or an ‘or’ combination of multiple licenses, which are all FSF or OSI approved, the application is considered ‘free software’ and the license tile says so. Otherwise, it’s considered ‘proprietary’.
If an application is being displayed as ‘proprietary’ when you think it shouldn’t be, it’s likely that the
<project_license> element includes the documentation license for the project. Remove it.
For example, change the license metadata from:
<project_license>GPL-2.0+ and CC-BY-SA-3.0</project_license>
- Don’t (generally) put documentation license in appdata
How to fix incorrect safety and permissions information
The safety and permissions information for an application comes from different sources depending on how the application is packaged. For traditionally packaged applications, for example in RPM or DEB format, there is no safety or permissions information available and nothing can currently be done to add it to an application.
For flatpak applications, the information comes from the application’s flatpak manifest, specifying what holes in the sandbox the application requires. Each of these holes typically contributes to lowering the displayed safety level of the application in gnome-software — moving it from ‘safe’ to ‘potentially unsafe’ to ‘unsafe’.
In order to improve the safety level of an application, its sandboxing must be made as tight as possible, by removing sandbox permissions where they’re not needed, and using portals instead of sandbox permissions where possible. Use of portals does not lower the displayed safety level of an application in gnome-software.
For example, if the application requests read/write access to the full file system (
--filesystem=host), does it actually need that, or does it only need to access files in a few specific locations? If so, the file portal could be used, or more specific file system permissions could be specified.
If the application works on Wayland, and only needs to work on X11 as a fallback, without using special X11 features, could it use
--socket=fallback-x11 rather than
Guidance about specific permissions, or other packaging formats, may be added here in future.
How to set the carousel tile background colour
The carousel tile background colour is normally extracted automatically from the application’s icon. If that colour is unsatisfactory, however, it can be overridden by adding the following XML to the application’s metainfo
<custom> <value key="GnomeSoftware::key-colors">[(124, 53, 77), (99, 16, 0)]</value> </custom>
The value of
GnomeSoftware::key-colors is a text-format GVariant with type
a(yyy), and represents an unordered set of key colours for the application. Each element of the set is a colour in RGB form ranging from
(0, 0, 0) to
(255, 255, 255).
Colours should be chosen so that they:
- Are identifiable to the application, matching the application’s branding in some way, if possible.
- Contrast with the edge of the application’s icon, so that when they are used as a background behind it, the icon can be distinguished.
- Contrast with the foreground text colour in the Adwaita theme (
#2e3436) and in its dark variant (
#eeeeec). This generally means choosing a colour with a medium level of brightness.
- Contrast can be checked using the Contrast app.
At least one colour should be specified. More can be specified if one colour can’t satisfy all the requirements above, and GNOME Software will choose the most appropriate to use in the carousel tile.