<?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-Metadata-Repository">
	<title>Repositories</title>

	<section id="spec-repository-introduction">
		<title>Introduction</title>
		<para>
			A repository component describes a remote archive of digital content, usually other
			software or additional data (e.g. themes, icons, books, music, ...). Upon installation of
			a component of this type, the repective repository is added to the system and activated,
			letting the user access the new content.
		</para>
		<para>
			The metadata described in this document is built upon the generic component metadata (see <xref linkend="sect-Metadata-GenericComponent"/>).
			All tags valid for a generic component are valid for a <literal>repository</literal> component as well.
		</para>
		<para>
			In order to add metadata about a software repository, projects can provide one or more metainfo files
			in <filename>/usr/share/metainfo/%{id}.metainfo.xml</filename>.
		</para>

	</section>

	<section id="spec-repository-filespec">
		<title>File specification</title>

		<para>
			The basic structure for a generic component as described at <xref linkend="spec-component-filespec"/> applies.
			Note that the XML root must have the <literal>type</literal> property set to <code>repository</code>, while in a generic component this
			property can be omitted. This clearly identified this metainfo document as describing a repository.
		</para>

		<para>
			The following list describes tags for <literal>repository</literal> upstream metadata and provides some additional information about the values
			the tags are expected to have.
			If no information is given about a tag, refer to the respective tag in <xref linkend="sect-Metadata-GenericComponent"/>.
		</para>

		<variablelist>
			<varlistentry id="tag-id-repo">
			<term>&lt;id/&gt;</term>
			<listitem>
				<para>
					For repositories, the <code>&lt;id/&gt;</code> tag value must follow the AppStream ID naming conventions (it should be a reverse-DNS name).
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;metadata_license/&gt;</term>
			<listitem>
				<para>
					The <code>&lt;metadata_license/&gt;</code> tag as described in <xref linkend="tag-metadata_license"/> must be present.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;name/&gt;</term>
			<listitem>
				<para>
					A <literal>name</literal> must be present for repositories. See <xref linkend="tag-name"/> for a detailed description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry>
			<term>&lt;summary/&gt;</term>
			<listitem>
				<para>
					A <literal>summary</literal> must be present for repositories. See <xref linkend="tag-summary"/> for a detailed description of this tag.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry id="tag-extends-repo">
			<term>&lt;extends/&gt;</term>
			<listitem>
				<para>
					This tag is refers to the ID of the component this repository is added to, similarly to how components of
					type <literal>addon</literal> work.
				</para>
				<para>
					Adding an <literal>extends</literal> tag ensures the respective repository is tied to its main component,
					e.g. a source for firmware downloads is tied to the firmware update service, or a repository for a
					site-specific package manager is tied to the tool that can actually install pieces from the repository.
				</para>
				<para>
					The <code>&lt;extends/&gt;</code> tag may be specified multiple times.
				</para>
			</listitem>
			</varlistentry>

			<varlistentry id="tag-agreement-repo">
			<term>&lt;agreement/&gt;</term>
			<listitem>
				<para>
					It is recommended to add a <ulink url="https://www.eugdpr.org/">GDPR</ulink> compliant privacy statement to <literal>repository</literal>
					components, in case any personal data is acquired when the repository is accessed.
				</para>
				<para>
					The <literal>agreement</literal> tag allows to add a privacy statement and other agreements easily. Refer to the <xref linkend="tag-agreement"/> tag
					as described for generic components for information on how to use agreements in AppStream.
				</para>
			</listitem>
			</varlistentry>

		</variablelist>

		<para>
			For a component of type <literal>repository</literal>, the following tags are required and must always be present: <xref linkend="tag-id-repo"/>,
			<xref linkend="tag-metadata_license"/>, <xref linkend="tag-name"/>, <xref linkend="tag-summary"/>.
		</para>

	</section>
</section>
