[Screenshot of GNOME Software]

Introduction:

Every software center that exists allows the user to look at screenshots and a long description of the application before it is installed. For most users it allows them to answer the question Do I want to install this application?

Traditionally in Linux distributions, we have none of this data for the vast majority of our desktop user-installable applications. To solve this, we have defined a new data file, which the upstream project can optionally translate using the same technique as GSetting schemas or Desktop files. Rather than create a new schema from scratch, we'll be using a subset of the AppStream metadata proposal.

Applications wishing to have long descriptions, screenshots and other useful things are required to ship one or more files in /usr/share/appdata/%{id}.appdata.xml.

File specification

Sample file

The file should contain something like this:

<?xml version="1.0" encoding="UTF-8"?>
<!-- Copyright 2013 First Lastname <your@email.com> -->
<component type="desktop">
 <id>gnome-power-statistics.desktop</id>
 <metadata_license>CC0-1.0</metadata_license>
 <project_license>GPL-2.0+ and GFDL-1.3</project_license>
 <name>Power Statistics</name>
 <summary>Observe power management</summary>
 <description>
  <p>
   Power Statistics is a program used to view historical and current battery
   information and will show programs running on your computer using power.
  </p>
  <p>Example list:</p>
  <ul>
   <li>First item</li>
   <li>Second item</li>
  </ul>
  <p>
  You probably only need to install this application if you are having problems
  with your laptop battery, or are trying to work out what programs are using
  significant amounts of power.
  </p>
 </description>
 <screenshots>
  <screenshot type="default">
   <image>http://www.hughsie.com/en_US/main.png</image>
   <caption>The main window showing the application in action</caption>
  </screenshot>
  <screenshot>
   <image>http://www.hughsie.com/en_US/preferences.png</image>
   <caption>The preferences window where you can change the defaults</caption>
  </screenshot>
 </screenshots>
 <url type="homepage">http://www.gnome.org/projects/en_US/gnome-power-manager</url>
 <updatecontact>gnome-power-manager-list@gnome.org</updatecontact>
 <project_group>GNOME</project_group>
</component>

<id/>

The %{id} is the same name as the installed .desktop file for the application.

<metadata_license/>

The <metadata_license> tag is indicating the content license that you are releasing the AppData text file and screenshots as. This is not typically the same as the project license. By ommitting the metadata_license value would probably mean your data would not be incorporated into the distribution metadata. Permissible license codes include:

The license codes correspond to the SPDX License IDs although the previously defined Fedora IDs will work as well.

The old name for this tag was <licence/> and was changed for two reasons. It used the British English spelling, and also that it wasn't clear that the license given wasn't the project license, but rather the license for the metadata only.

<project_license/>

The <project_license> tag is indicating the licenses that you used for the application and any data or media files used. This is not typically the same as the metadata license.

The license codes correspond to the SPDX License IDs as a string, e.g. GPL-2.0+ and GFDL-1.3 or GPL-2.0+ and (GFDL-1.3 or LGPL-2.1).

<name/>

This is the project name, usually the same as the Name value in the desktop file. It's important to choose a good name here; A generic name like Color is suitable for the desktop file but something like GNOME Color Manager that describes the project is more appropriate for a software center.

<summary/>

This is the project one line tagline, usually the same as the Comment value in the desktop file. Don't include a trailing fullstop.

<description/>

The long description is an important part of the file. Important things to consider when writing the application description:

Do not assume the format is HTML. Only paragraph, ordered list and unordered list are supported at this time.

<screenshots/>

A screenshot presents your application to the outside world, and could be seen by hundreds or thousands of people.

Screenshots are an important part of how people choose which applications to install, so it's important to get them right. Consistent, good looking screenshots will make your application look more attractive and will expand your userbase. Consistent screenshots also provide a more predictable experience for people using the software center.

Screenshot size, shape and format:

Basic guidelines for things to include (and not include) in your screenshots:

Additional advice on how to take effective screenshots:

<url/>

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

<updatecontact/>

AppData is a new standard, and we'll likely be adding extra metadata in the future. If you include the <updatecontact> tag then someone will send an email when the standard is updated, detailing the new fields that you may or may not want to add to your appdata.xml file. We're not expecting to do this more than 2 times a year, so don't expect a deluge of email.

TIP:Use _at_ rather than @ if you're worried about the email address being harvested by spammers.

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

Questions:

How do I translate this data?

If you ship an .xml.in file rather than an .xml file, you can use intltool to translate the data. You can also use itstool to translate the data, and we've provided a appdata.its file for convenience.

Translated descriptions are a really nice feature, as only a fraction of the userbase installing application will be able to understand English text.

Why not just use the package description?

Different distros cut and join different source packages in different ways, plus, it's not typically translated.

Why not just use the DOAP description?

This is one file per-project and is not suitable when one tarball will install several applications. It's also not translatable.

Why not just use a centralized web service?

Put simply, we don't have the resources to moderate, check and translate each string for every application. We don't have the legal framework so that non-free applications could also ship application data.

The upstream project is in a much better place to describe itself, and the upstream project is able to use its existing localization and translation teams. Also, things like the screenshot will change as the project is updated, and not all distros ship the same version of an application. We also want the long description to come up immediately, and be searchable, so we can't really use a web service in that case. Additionally, different distros have different policies on trademarks.

What happens if I don't ship this file?

We will penalize apps that do not ship the extra metadata by showing them lower in the search results. Applications without icons, names or short descriptions will not be shown at all.

Why XML and not JSON/other?

AppData is a subset of the AppStream schema, which is also XML.

Where will this data be used?

We will scrape this data when building and composing metadata for distributions.

What resolution screenshots should I aim to take?

Any 16:9 aspect resolution is fine, as long as the width is at least 624 pixels. A useful table of resolutions of the correct aspect can be found here:

640x360800x450960x5401120x6301280x7201440x810
656x369816x459976x5491136x6391296x7291456x819
672x378832x468992x5581152x6481312x7381472x828
688x387848x4771008x5671168x6571328x7471488x837
704x396864x4861024x5761184x6661344x7561504x846
720x405880x4951040x5851200x6751360x7651520x855
736x414896x5041056x5941216x6841376x7741536x864
752x423912x5131072x6031232x6931392x7831552x873
768x432928x5221088x6121248x7021408x7921568x882
784x441944x5311104x6211264x7111424x8011584x891

The native size for most software centers is 624x351 and so screenshots taken or cropped to this size will not be resized and will look pixel perfect. The largest resolution screenshot supported is 1600x900.

My AppData file has <application> rather than <component>?

This is the old AppStream schema, before it was standardized on freedesktop. You can continue to use the old format, all the software centers and metadata extractors in common use understand both types.

If you want to upgrade to the 0.6+ format, just use appstream-util upgrade on your AppData files.

How do I know if my appdata XML is correct?

The best way to validate the data is by using the appstream-util validate tool available in the appstream-glib project.

You can also validate the AppData file using this web helper:

Have you got a real world example?

See the commit that added the non-translated AppData metadata to gnome-power-manager or the translated metadata to gnome-color-manager.