<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "AppStream.ent">
%BOOK_ENTITIES;
]>

<section id="sect-AppStream-XML">
	<title>AppStream Catalog XML</title>

	<section id="spec-asxml-introduction">
		<title>Introduction</title>

		<para>
			AppStream catalog XML files are text files describing all available software components a software repository (usually
			from a Linux distributor) offers for installation.
			The XML files might be compressed with GZip.
		</para>
	</section>

	<section id="spec-asxml-filenaming">
		<title>File naming and location</title>
		<para>
			The XML files must have a unique name, which is usually the distribution's name and version, combined with the name of the repository/origin.
			For example in Debian 8 (Jessie), the filename for the main repository component would be <filename>debian-jessie-main.xml.gz</filename>.
			For Fedora 20 (Heisenbug) updates it would be <filename>fedora-20-updates.xml.gz</filename>.
			3rd-party repositories use a vendor name and repository-name combination, for example Ubuntu PPAs might get <filename>ppa-ubuntu12.04-username-foobar.xml</filename>.
		</para>
		<para>
			There are two valid locations to store AppStream XML data. <filename>/usr/share/swcatalog/xml</filename> stores all AppStream data which
			has been installed via software packages, while <filename>/var/lib/swcatalog/xml</filename> stores application data which was downloaded
			by the package manager or placed there by other tools (for example, Limba).
			The <filename>/var/cache/swcatalog/xml</filename> location however can be used for any data that was locally generated from other sources.
			The XML files can either be plain files or be compressed with gzip. It is always a good idea to compress the files, because they tend to become
			quite large.
		</para>

		<important>
			<title>Legacy Path</title>
			<para>
				Prior to version 1.0, AppStream tools scanned the paths <filename>/usr/share/app-info/(xml|xmls)</filename> and <filename>/var/lib/app-info/(xml|xmls)</filename> path for legacy
				compatibility as well.  Legacy path support was dropped in version 1.0. The old locations should not be used anymore. The modern locations are supported by both the AppStream 1.x as well as AppStream 0.16.x series.
			</para>
		</important>
	</section>

	<section id="spec-asxml-general">
		<title>General XML structure</title>
		<para>
			The XML starts with a <code>&lt;components&gt;</code> tag as the root element. It has all the
			<code>&lt;component&gt;</code> tags of different <literal>type</literal>s as children.
		</para>
		<para>
			Data to fill the different component elements is usually taken from their <ulink url="https://specifications.freedesktop.org/desktop-entry-spec/latest/">Desktop files</ulink>
			and package data. However, if an upstream project ships metainfo files (see <xref linkend="chap-Metadata"/>),
			values defined there should override data from any other source.
		</para>
		<para>
			All child elements of the <code>&lt;components&gt;</code> element, no matter of which type they are, must at least have
			an <literal>id</literal>, <literal>name</literal>, <literal>summary</literal> and <literal>pkgname</literal> tag.
			For applications, a <literal>icon</literal> tag is also required.
		</para>
		<para>
			The <code>&lt;components&gt;</code> root node has these properties, where the first two are required:
		</para>
		<variablelist>
			<varlistentry>
			<term>version</term>
			<listitem>
				<para>
					This property declares the AppStream spec version this file is based on (currently 0.14). The property is required.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>origin</term>
			<listitem>
				<para>
					Defines the repository ID this AppStream XML file belongs to. This usually matches the filename without extension (see the explanation on how to pick a good filename above).
					It is also used to associate the right cached icons with AppStream metadata. This property is required.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>media_baseurl</term>
			<listitem>
				<para>
					The base URL for media (screenshots, icons, ...) referenced in the metadata file.
					If this is set, all urls in the document referencing media will be treated relative to the base url.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>architecture</term>
			<listitem>
				<para>
					Defines the architecture this data belongs to. This information is useful to resolve AppStream-ID conflicts on multiarch systems,
					which appear if the user has metadata for two architectures installed. This property is optional.
				</para>
			</listitem>
			</varlistentry>
		</variablelist>
	</section>

	<section id="spec-asxml-tags">
		<title>Valid tags for all component types</title>
		<para>
			These tags can be applied to every component type (application, component, font, inputmethod) which
			is described in the AppStream metadata.
		</para>
		<para>
			Additionally to the <literal>type</literal> property, every <literal>&lt;component/&gt;</literal> tag in AppStream catalog data
			may have a <literal>priority</literal> property, defining the priority of this specific metadata over other metadata from different
			AppStream XML files (for example, from a different repository) which have the same component-id. The value of this tag is an integer, if the
			property is missing, a value of <code>"0"</code> is assumed.
		</para>
		<para>
			In order to <emphasis>merge</emphasis> metadata, each component in catalog data may also have a <literal>merge</literal> property, assuming the
			values <code>append</code>, <code>replace</code> or <code>remove-component</code>. If the value is <code>append</code>, all data this component describes will be appended
			to data of the component with the same ID. If the value is <code>replace</code> the fields of the target component will be replaced with the
			ones present in the merge component. If the merge type is <code>remove-component</code>, the entore component matching the ID of the merge-component should
			be removed from the metadata pool.
			Merge-components with a higher priority take precedence. If a component has a <literal>merge</literal> property, the only tag that must
			be present for it is the <code>&lt;id/&gt;</code> tag, any other metadata is optional.
		</para>

		<variablelist>
			<varlistentry id="tag-ct-component-id">
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					The <code>&lt;id/&gt;</code> tag is a short unique and usually lower-cases identifier for the component.
					Depending on the component's type, different naming conventions apply.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-pkgname">
				<term>&lt;pkgname/&gt;</term>
				<listitem>
					<para>
						The name of the package which needs to be installed in order to make this component available on the system.
					</para>
					<para>
						This tag can be defined multiple times, if a component is split across multiple packages.
					</para>
					<important>
						<para>
							The preferred way is to create metapackages containing the component metadata, and referencing them
							from the catalog metadata, and not to use multiple <literal>pkgname</literal> tags.
							They should only be used multiple times as a workaround or if there is no sensible way of creating a
							matching metapackage.
						</para>
					</important>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-source_pkgname">
				<term>&lt;source_pkgname/&gt;</term>
				<listitem>
					<para>
						This optional tag is used to specify the source package the binary package this component belongs to was built from.
					</para>
					<para>
						The tag can be used by software center applications to group components. It is otherwise useful for the distributor
						to assign components to a source package and to fetch additional information about a package from the web.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-name">
				<term>&lt;name/&gt;</term>
				<listitem>
					<para>
						A human-readable name for this software.
					</para>
					<para>
						In case of a component of type <literal>desktop-application</literal>, the application name as defined in the application's
						<ulink url="https://specifications.freedesktop.org/desktop-entry-spec/latest/">desktop file</ulink> is used.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-project_license">
				<term>&lt;project_license/&gt;</term>
				<listitem>
					<para>
						The <code>&lt;project_license/&gt;</code> tag is indicating the license of the component.
						It should be a <ulink url="https://spdx.org/specifications">SPDX license expression</ulink>.
						A full list of recognized licenses and their identifiers can be found at the
						<ulink url="https://spdx.org/licenses/">SPDX OpenSource License Registry</ulink>.
					</para>
					<para>
						You can find more information about this tag at the metainfo description for <xref linkend="tag-project_license"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-summary">
				<term>&lt;summary/&gt;</term>
				<listitem>
					<para>
						The tag contains a short summary of the purpose and function of this component. In case the component is of
						type <literal>desktop</literal>, it is usually taken from a Desktop file,
						if the application does not ship an upstream metadata file.
					</para>
					<para>
						For more information about this tag, take a look at the tag's definition at <xref linkend="tag-summary"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-description">
				<term>&lt;description/&gt;</term>
				<listitem>
					<para>
						A long description of the component. It is usually taken from the package descriptions or metainfo files, if they were provided.
						The description might use markup. Right now, only paragraph, ordered list and unordered list are supported.
						An example description element might look like this:
						<programlisting language="XML"><![CDATA[<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>]]></programlisting>
					</para>
					<para>
						As opposed to the by-paragraph translation used in metainfo files, this tag is translated "as a whole", meaning that the
						<literal>&lt;description/&gt;</literal> tag itself has a language property and contains the translated paragraphs for the given language.
						This allows faster parsing of the Appstream XML file, and does not increase it's size much, as long as it is compressed.
					</para>
					<para>
						For more information about this tag, take a look at the tag's definition at <xref linkend="tag-description"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-url">
				<term>&lt;url/&gt;</term>
				<listitem>
					<para>
						Defines URLs for this component. This tag can be present multiple times.
					</para>
					<para>
						For a list of possible url types and what they are expected to do,
						take a look at the tag's description at <xref linkend="tag-url"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-project_group">
				<term>&lt;project_group/&gt;</term>
				<listitem>
					<para>
						The <code><![CDATA[<project_group>]]></code> tag identifies a project with a specific upstream umbrella project.
						Known values include <literal>GNOME, KDE, XFCE, LXDE, Mozilla</literal> and <literal>MATE</literal>, although other umbrella projects
						like <literal>Yorba</literal> would make sense too.
					</para>
					<note>
						<para>
							Components 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.
						</para>
					</note>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-icon">
				<term>&lt;icon/&gt;</term>
				<listitem>
					<para>
						The <code>&lt;icon/&gt;</code> tag describes the component icon. It is mostly used for GUI applications (component-type <literal>desktop-application</literal>).
						It can be of the type <literal>stock</literal>, <literal>cached</literal>, <literal>local</literal>,
						or <literal>url</literal>.
					</para>
					<para>
						<literal>stock</literal> icons are loaded from stock. The icon name should never include any file-extension or path.
					</para>
					<para>
						<literal>cached</literal> icons are loaded from the AppStream icon cache. The icon tag should contain the icon file name, including its
						extension. It must not contain a full or relative path to the icon file.
						This icon type may have <literal>width</literal> and <literal>height</literal> properties.
						If targeting a hi-DPI screen, this icon type may have a <literal>scale</literal> property.
					</para>
					<para>
						<literal>local</literal> icons are reserved for AppStream data installed by local applications or via 3rd-party application installers.
						They should specify a full file path.
						This icon type may have <literal>width</literal> and <literal>height</literal> properties.
						If targeting a hi-DPI screen, this icon type may have a <literal>scale</literal> property.
					</para>
					<para>
						<literal>remote</literal> icons loaded from a remote URL. Currently, only HTTP urls are supported.
						This icon type should have <literal>width</literal> and <literal>height</literal> properties.
						If targeting a hi-DPI screen, this icon type may have a <literal>scale</literal> property.
					</para>
					<para>
						If specified, the <literal>scale</literal> property is defined as in the
						<ulink url="https://specifications.freedesktop.org/icon-theme-spec/latest/#definitions">Freedesktop Icon Theme Specification</ulink>.
						It’s an integer value ≥1 indicating how many pixels in the image represent a logical pixel on the display, in each dimension.
						This allows icons for hi-DPI screens to be displayed at the same logical size as on lower resolution screens, but without upscaling artifacts.
					</para>
					<para>
						Examples of the different methods to specify an icon:
					</para>
					<programlisting language="XML"><![CDATA[<icon type="stock">gimp</icon>
<icon type="cached">firefox.png</icon>
<icon type="cached" width="128" height="128" scale="2">firefox.png</icon>
<icon type="remote" width="64" height="64">https://example.com/icons/foobar.png</icon>
<icon type="local" width="64" height="64">/usr/share/pixmaps/foobar.png</icon>]]></programlisting>
					<para>
						Multiple <code><![CDATA[<icon/>]]></code> tags might be combined for one application, for example to define a <literal>stock</literal> icon
						and a <literal>cached</literal> icon.
						Software-Centers should always prefer the stock icon, if it is available, and fall back to the other icon types if they can not find it.
						The <emphasis>libappstream</emphasis> library makes it easy to do that.
					</para>
					<para>
						The AppStream library will prefer <literal>cached</literal> over <literal>local</literal> over <literal>remote</literal>
						icons when setting the non-stock icon for the application.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-categories">
				<term>&lt;categories/&gt;</term>
				<listitem>
					<para>
						This tag can contain one or more <code><![CDATA[<category>]]></code> tags, describing the categories this component
						is located in. This tag is usually applied to components of type <literal>desktop-application</literal>, although it might be used by others later.
						This data is usually taken from Desktop files, a list of categories can be found in the
						<ulink url="https://specifications.freedesktop.org/menu-spec/latest/category-registry.html">Freedesktop menu spec</ulink>.
						Example:
					</para>
					<programlisting language="XML"><![CDATA[<categories>
    <category>Science</category>
    <category>Network</category>
    <category>Telephony</category>
</categories>]]></programlisting>
					<note>
						<title>Deprecated Tags</title>
						<para>
							The tag <code><![CDATA[<appcategories>]]></code> with its <code><![CDATA[<appcategory>]]></code> child elements is deprecated API.
							AppStream parsers should handle these tags just like the <literal>category</literal> tags, there is no difference except for the name.
						</para>
					</note>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-keywords">
				<term>&lt;keywords/&gt;</term>
				<listitem>
					<para>
						This tag can contain one or more <code><![CDATA[<keyword>]]></code> tags, describing keywords for the component,
						to make it easier to find in a software center.
					</para>
					<para>
						This tag behaves like the <xref linkend="tag-keywords"/> tag used in metainfo files, but is translated "as a whole",
						unlike its metainfo counterpart that has individual keywords translated. This means that the <literal>&lt;keywords/&gt;</literal> tag
						itself has a language property and contains only the translated keywords for the given language.
					</para>
					<para>
						In case of type <literal>desktop-application</literal> components, this data is taken from .desktop files. For <literal>addon</literal>
						components, the upstream metadata file usually provides this tag.
					</para>
					<para>
						Example:
					</para>
					<programlisting language="XML"><![CDATA[<keywords>
  <keyword>IDE</keyword>
  <keyword>development</keyword>
  <keyword>programming</keyword>
</keywords>
<keywords xml:lang="de">
  <keyword>IDE</keyword>
  <keyword>entwicklung</keyword>
  <keyword>programmierung</keyword>
</keywords>]]></programlisting>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-screenshots">
				<term>&lt;screenshots/&gt;</term>
				<listitem>
					<para>
						This tag can contain one or more <code><![CDATA[<screenshot>]]></code> tags, describing screenshots which are available for
						the software. A screenshot tag my have the attribute <code>type="default"</code>, marking it as the software's default screenshot,
						which primarily represents it in a software center.
					</para>
					<para>
						The <literal>screenshots</literal> tag is described for metainfo files in <xref linkend="tag-screenshots"/>. In catalog metadata, the tag
						has the exact same format as in metainfo files.
						The metadata generator may add an arbitrary number of resized thumbnails for <literal>image</literal> type screenshots though.
					</para>
					<para>
						Every static-image <code><![CDATA[<screenshot>]]></code> is defined by several images of different sizes.
						All images should have their width and hight set as arguments. Also, one of the images should be marked as <code>type="source"</code>,
						indicating that it is the unscaled version of the screenshot.
						Images of <code>type="thumbnail"</code> define thumbnails of the screenshot.
					</para>
					<para>
						The metadata generator should scale the source image down to several thumbnails useful for the client to load.
						The recommended widths for thumbnail images are:
					</para>
					<itemizedlist>
						<listitem><para><emphasis>752</emphasis> (large)</para></listitem>
						<listitem><para><emphasis>624</emphasis> (normal)</para></listitem>
						<listitem><para><emphasis>112</emphasis> (small)</para></listitem>

						<listitem><para><emphasis>1504</emphasis> (large, HiDPI)</para></listitem>
						<listitem><para><emphasis>1248</emphasis> (normal, HiDPI)</para></listitem>
						<listitem><para><emphasis>224</emphasis> (small, HiDPI)</para></listitem>
					</itemizedlist>
					<para>
						In order to support HiDPI screens, the thumbnails should also be available in their bigger sizes. A metadata generator should, however, never attempt
						to scale up a smaller image to a larger size, and just ship the smaller sizes instead.
						When scaling images to the respective thumbnail width, the image aspect ratio must be preserved, padding, cropping or stretching should not happen.
					</para>
					<para>
						Optionally, a screenshot can contain a <code><![CDATA[<caption>]]></code> tag, describing the screenshot's caption. This is usually what the user can see
						on the image shown. The tag is translatable.
					</para>
					<para>
						For <code><![CDATA[<screenshot>]]></code> tags that contain <literal>video</literal> elements, a catalog metadata generator may impose any restrictions to them,
						including completely removing them from the output, imposing filesize limits, etc.
						Upstream metainfo files should not rely on the videos being present and must always have a static screenhot for the software component as well.
					</para>
					<para>
						Every image or video should have a full remote url set, usually pointing to a cache of images maintained by the repository vendor.
						Example:
					</para>
					<programlisting language="XML"><![CDATA[<screenshots>
  <screenshot type="default">
    <caption>FooBar showing kitchen-sink functionality.</caption>
    <caption xml:lang="de">FooBar beim Ausführen der Spühlbecken-Funktion.</caption>
    <image type="source" width="800" height="600">https://www.example.org/en_US/main.png</image>
    <image type="thumbnail" width="752" height="423">https://www.example.org/en_US/main-large.png</image>
    <image type="thumbnail" width="112" height="63">https://www.example.org/en_US/main-small.png</image>
  </screenshot>
  <screenshot>
    <video container="matroska" codec="av1" width="800" height="600">https://www.example.org/en_US/screencast.mkv</video>
  </screenshot>
  <screenshot>
     ....
  </screenshot>
</screenshots>]]></programlisting>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-compulsory_for_desktop">
				<term>&lt;compulsory_for_desktop/&gt;</term>
				<listitem>
					<para>
						The <code><![CDATA[<compulsory_for_desktop>]]></code> tag indicates that the component which the metadata belongs to is essential for the
						functionality of the defined desktop environment.
					</para>
					<para>
						This tag is described in detail at <xref linkend="tag-compulsory_for_desktop"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-provides">
				<term>&lt;provides/&gt;</term>
				<listitem>
					<para>
						This tag is described in detail at <xref linkend="sect-Metadata-GenericComponent"/>.
					</para>
					<para>
						Distributors and software repository vendors must ensure that all things described in this tag are present in the package referenced in
						the associated <literal>pkgname</literal> tag (or in dependencies of it).
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-developer">
			<term>&lt;developer/&gt;</term>
			<listitem>
				<para>
					The <code>&lt;developer/&gt;</code> tag as described in the specification for a generic component. See <xref linkend="tag-developer"/> for more information.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-launchable">
				<term>&lt;launchable/&gt;</term>
				<listitem>
					<para>
						This tag follows the same schema as described for metainfo files in <xref linkend="tag-launchable"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-releases">
				<term>&lt;releases/&gt;</term>
				<listitem>
					<para>
						The <literal>releases</literal> tag and its <literal>release</literal> children are structured as described in <xref linkend="sect-Metadata-Releases"/>.
					</para>
					<para>
						Each <literal>release</literal> tag may have a <literal>description</literal> tag as child, containing a brief description of what is new in the release.
						The <literal>description</literal> tag is structured as described in <xref linkend="tag-ct-description"/>. This also applies to its translation rules.
					</para>
					<para>
						The AppStream catalog XML generator may shorten overlong lists of releases to a smaller list, for example of 4 <literal>release</literal> tags.
						It may also convert ISO 8601 <literal>date</literal> properties of the metainfo file into an UNIX timestamp <literal>timestamp</literal> property.
						It should avoid generating metadata containing both properties on a <literal>release</literal> tag.
					</para>
					<para>
						If a <xref linkend="tag-releases"/> tag in a metainfo file references an <literal>external</literal> release description, the release description should
						be read either from the release file provided locally, or, if possible and provided, be downloaded from the URL referenced in the component's <literal>releases</literal>
						tag.
					</para>
					<para>
						Example for a valid releases tag:
					</para>
					<programlisting language="XML"><![CDATA[<releases>
  <release version="1.8" timestamp="1424116753">
    <description>
      <p>This stable release fixes the following bug:</p>
      <ul>
        <li>CPU no longer overheats when you hold down spacebar</li>
      </ul>
    </description>
    <size type="download">12345678</size>
    <size type="installed">42424242</size>
  </release>
  <release version="1.2" timestamp="1397253600" />
  <release version="1.0" timestamp="1345932000" />
</releases>]]></programlisting>
					<para>
						In case a <code>&lt;release/&gt;</code> tag has a <code>&lt;description/&gt;</code> tag as parameter, describing the new release briefly, distributors are encouraged to provide 2-4
						<code>&lt;release/&gt;</code> release tags for every component. If no description is provided, one tag is enough.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-languages">
				<term>&lt;languages/&gt;</term>
				<listitem>
					<para>
						This tag gives information about the translations a component provides, and to which extent the software is translated.
					</para>
					<para>
						The tag is allowed to only occur once per component, and contains multiple <code>&lt;lang/&gt;</code> child nodes, which have
						a <ulink url="https://www.gnu.org/software/gettext/manual/html_node/Language-Codes.html">language code</ulink> as value.
						Each <code>&lt;lang/&gt;</code> node may have a <literal>percentage</literal> property, which describes the percentage value to which
						a component has been translated.
					</para>
					<para>
						The language data is expected to be extracted by the AppStream XML generator, and is not provided upstream. Generators may obtain the
						information from processing GNU Gettext files, which should cover most translation methods.
					</para>
					<para>
						Tag example:
					</para>
					<programlisting language="XML"><![CDATA[<languages>
  <lang percentage="96">gu</lang>
  <lang percentage="94">ca@valencia</lang>
  <lang percentage="91">de</lang>
  <lang percentage="93">eo</lang>
</languages>]]></programlisting>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-bundle">
				<term>&lt;bundle/&gt;</term>
				<listitem>
					<para>
						The optional <literal>bundle</literal> tag indicates that the described software is available as a software bundle via a
						3rd-party application installer. The value of this tag is an identification string for the bundle.
					</para>
					<para>
						Software centers may use the information of this tag to offer the user to install the software
						from 3rd-party sources, or just update an already installed software automatically via the normal update procedure.
						The <literal>bundle</literal> tag can coexist with the <literal>pkgname</literal> tag, in case a component is available from
						multiple sources.
					</para>
					<para>
						The <literal>type</literal> property of this tag indicates which 3rd-party software installation solution the bundle belongs to.
						Currently supported solutions are:
						<itemizedlist>
							<listitem><para><code>package</code> - For distribution package names.</para></listitem>
							<listitem><para><code>limba</code> - For <ulink url="https://people.freedesktop.org/~mak/limba/">Limba Project</ulink> bundles.</para></listitem>
							<listitem><para><code>flatpak</code> - For <ulink url="https://flatpak.org/">Flatpak</ulink> bundles.</para></listitem>
							<listitem><para><code>appimage</code> - For <ulink url="https://appimage.org/">AppImageKit</ulink> bundles.</para></listitem>
							<listitem><para><code>snap</code> - For <ulink url="https://snapcraft.io/">Snappy</ulink> snap bundles.</para></listitem>
							<listitem><para><code>tarball</code> - For plain and possibly compressed tarballs.</para></listitem>
							<listitem><para><code>cabinet</code> - For cabinet firmware deployments.</para></listitem>
							<listitem><para><code>linglong</code> - For <ulink url="https://linglong.dev/">Linglong</ulink> bundles.</para></listitem>
							<listitem><para><code>sysupdate</code> - For <ulink url="https://www.freedesktop.org/software/systemd/man/latest/systemd-sysupdate.html">systemd-sysupdate</ulink> bundles.</para></listitem>
						</itemizedlist>
					</para>
					<para>
						Example:
					</para>
					<programlisting language="XML"><![CDATA[<bundle type="limba">foobar-1.0.2</bundle>]]></programlisting>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-suggests">
				<term>&lt;suggests/&gt;</term>
				<listitem>
					<para>
						The optional <literal>suggests</literal> tag provides suggestions of other software made by this component.
						It follows the same schema as described for metainfo files in <xref linkend="tag-suggests"/>.
					</para>
					<para>
						Additionally to the <literal>upstream</literal> type allowed for metainfo files, the catalog data also allows a
						<literal>heuristic</literal> type, which is added by automatic recommendation services, and might be based on the user's
						preferences. It is commonly injected into existing metadata via a <literal>merge</literal> pseudo-component.
					</para>
					<para>
						Example:
					</para>
					<programlisting language="XML"><![CDATA[<suggests type="upstream">
  <id>org.kde.gwenview.desktop</id>
  <id>org.inkscape.Inkscape</id>
</suggests>
<suggests type="heuristic">
  <id>org.gimp.gimp.desktop</id>
</suggests>]]></programlisting>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-content_rating">
				<term>&lt;content_rating/&gt;</term>
				<listitem>
					<para>
						This optional tag follows the same schema as described for metainfo files in <xref linkend="tag-content_rating"/>.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry id="tag-ct-agreement">
				<term>&lt;agreement/&gt;</term>
				<listitem>
					<para>
						This optional tag follows the same schema as described for metainfo files in <xref linkend="tag-agreement"/>, with the exception
						of <literal>description</literal> tags in its <literal>agreement_section</literal> child tags now following the same translation
						rules as the toplevel <xref linkend="tag-ct-description"/> tag in catalog metadata.
					</para>
				</listitem>
			</varlistentry>

		</variablelist>
	</section>

	<section id="spec-asxml-example">
		<title>Example file</title>
		<para>
			This is an example AppStream metadata file:
		</para>
		<programlisting language="XML">
<![CDATA[<?xml version="1.0"?>
<components version="0.10">
  <component type="desktop-application">
    <id>org.mozilla.Firefox</id>
    <pkgname>firefox-bin</pkgname>
    <name>Firefox</name>
    <name lang="en_GB">Firefoux</name>
    <summary>Web browser</summary>
    <summary lang="fr_FR">Navigateur web</summary>
    <project_license>MPL-2.0</project_license>
    <keywords>
      <keyword>internet</keyword>
      <keyword>web</keyword>
      <keyword>browser</keyword>
      <keyword lang="fr_FR">navigateur</keyword>
    </keywords>
    <icon type="stock">web-browser</icon>
    <icon type="cached">firefox.png</icon>
    <categories>
      <category>network</category>
      <category>web</category>
    </categories>
    <url type="homepage">https://www.mozilla.com</url>
    <screenshots>
      <screenshot type="default">
        <image type="source" width="800" height="600">https://www.awesomedistro.example.org/en_US/firefox.desktop/main.png</image>
        <image type="thumbnail" width="200" height="150">https://www.awesomedistro.example.org/en_US/firefox.desktop/main-small.png</image>
      </screenshot>
    </screenshots>
    <provides>
      <binary>firefox</binary>

      <mediatype>text/html</mediatype>
      <mediatype>text/xml</mediatype>
      <mediatype>application/xhtml+xml</mediatype>
      <mediatype>application/vnd.mozilla.xul+xml</mediatype>
      <mediatype>text/mml</mediatype>
      <mediatype>application/x-xpinstall</mediatype>
      <mediatype>x-scheme-handler/http</mediatype>
      <mediatype>x-scheme-handler/https</mediatype>
    </provides>
  </component>
  <component>
    <id>org.freedesktop.PulseAudio</id>
    <name>PulseAudio</name>
    <summary>The PulseAudio sound server</summary>
    <url type="homepage">https://www.freedesktop.org/wiki/Software/PulseAudio/</url>
    <project_license>GPL-2.0+</project_license>
    <provides>
      <library>libpulse-simple.so.0</library>
      <library>libpulse.so.0</library>
      <binary>start-pulseaudio-kde</binary>
      <binary>start-pulseaudio-x11</binary>
    </provides>
    <release version="2.0"/>
  </component>
  <component type="font">
    <id>org.linuxlibertine.LinuxLibertine</id>
    <name>Linux Libertine</name>
    <summary>Linux Libertine Open fonts</summary>
    <provides>
      <font>LinLibertine_M.otf</font>
    </provides>
  </component>
  <!-- more components here! -->
</components>]]></programlisting>

	</section>
</section>