3.2. AppStream collection YAML

⁠3.2. AppStream collection YAML

⁠3.2.1. Introduction

DEP-11 is a YAML implementation of the AppStream collection specification, which is primarily used by Debian and its derivatives. This document describes the DEP-11 YAML. All AppStream support libraries available today are able to read both the YAML and the XML specification.

Important

If you want to use AppStream in your distribution, and are not based on Debian, please use the XML specification (unless you have strong reasons for preferring YAML). XML is the official format for AppStream collection metadata.

The DEP-11 YAML metadata can be validated for correctness using the dep11-validate tool from the AppStream DEP-11 utils.

Fields not mentioned in this document are not recognized by DEP-11 YAML parsers.

⁠3.2.2. File naming and location

Take a look at Section 3.1.2, “File naming and location” for AppStream XML files. While the XML data belongs into the xmls subdirectory in /usr/share/app-info (or /var/cache/app-info), the YAML data is stored in the yaml subdirectory. All other rules affecting the XML apply the DEP-11 YAML as well, including the recommendation to compress the files with gzip.

⁠3.2.3. General DEP-11 YAML structure

Each YAML file starts with a header document, which defines the basic properties of the metadata, which is followed by the actual metadata in form of one YAML document per AppStream component.

The header document contains the following fields, all of them are required or at least strongly recommended.

File: This field identifies the file as DEP-11 file. Its value is always DEP-11.
Field info: value-type:str, required:yes
Version: The version of the AppStream specification this file was built for.
Field info: value-type:str, required:yes
Origin: Defines the repository-id this file belongs to. This usually matches the filename without extension. On Debian systems, it is the <suite>-<component> combination, e.g. jessie-main.
Field info: value-type:str, required:yes
MediaBaseUrl: 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.
Field info: value-type:str, required:no
Architecture: 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.
Field info: value-type:str, required:no
Priority: The priorization of this metadata file over other metadata.
Field info: value-type:int, required:no

⁠3.2.4. Translated fields

Fields with translated values follow the following conventions:

They are of type dict
They must contain a key C, with the untranslated string as value
All languages are represented with their locale name as key in the dict and the translated content as value (which is of type str, unless explicitly stated otherwise)

In this document, the type localized is used to indicate that the field contains translated values following this schema.

Example for a translated Name field:

Name:
  C: I am the untranslated string.
  be@latin: Redaktar naładaŭ
  bg: Настройки на програмите
  pl: Edytor konfiguracji

⁠3.2.5. Valid fields

This document describes all valid fields in the DEP-11 YAML specification. The requirements for the values are exactly the same as in the XML specification, and each field links to its correspondent XML tag for reference.

⁠ID

The ID field is a short unique and usually lower-cases identifier for the component. Depending on the component's type, different naming conventions apply.

See <id/>.

Field info: value-type:str, required:yes

⁠Priority

The Priority field sets the priority this component's metadata should have over other meadata in the pool. Data with a higher priority replaces data with a lower priority.

See Section 3.1.4, “Valid tags for all component types”.

Field info: value-type:int, required:no

⁠Type

The type of this component. Allowed values are:

generic for Section 2.1, “Generic Component”
desktop-application for Section 2.2, “Desktop Applications”
console-application for Section 2.3, “Console Applications”
addon for Section 2.4, “Addons”
codec for Section 2.6, “Codecs”
inputmethod for Section 2.7, “Input Methods”
firmware for Section 2.8, “Firmware”

Field info: value-type:str, required:yes

⁠Merge

The optional Merge field describes the merge strategy that should be applied when merging data of this component into its base. It may assume the values append or replace.

See Section 3.1.4, “Valid tags for all component types” for a description on how merging works.

Field info: value-type:str, required:no

⁠Package

The name of the package which needs to be installed in order to make this component available on the system.

See <pkgname/>.

Field info: value-type:str, required:yes

⁠SourcePackage

See <source_pkgname/>.

Field info: value-type:str

⁠Name

See <name/>.

Field info: value-type:localized, required:yes

⁠Summary

See <summary/>.

Field info: value-type:localized, required:yes

⁠ProjectLicense

See <project_license/>.

Field info: value-type:str

⁠Description

See <description/>.

The markup for the description is the same as in the XML specification, so it can be read by anything parsing basic HTML markup.

Field info: value-type:localized

⁠Url

See <url/>.

The Url field contains the different url types as keys in its dict. Valid url types are defined in the main AppStream XML specification. All URL types must be lowercased.

Example:

Url:
  homepage: http://example.org
  faq: http://example.org/faq
  bugtracker: http://bugs.example.org/report-issue

Field info: value-type:dict

⁠ProjectGroup

See <project_group/>.

Field info: value-type:str

⁠Icon

See <icon/>.

The Icon field has the different icon types as keys for its dict.

stock: Contains the stock icon name.
Field info: value-type:str
cached: Contains a list of dictionaries with the keys width and height of type int specifying the dimensions of the icon, as well as the key name of type str specifying the name of the icon in the cache.
Field info: value-type:list ➟ dict
local: Contains a list of dictionaries with the keys width and height of type int specifying the dimensions of the icon, as well as the key name of type str specifying the absolute filename pointing to the right icon.
Field info: value-type:list ➟ dict
remote: Contains a list of dictionaries with the keys width and height of type int specifying the dimensions of the icon, as well as the key url of type str which contains a HTTP(S) or FTP URL to the icon.
Field info: value-type:list ➟ dict

Field info: value-type:dict

⁠Categories

See <categories/>.

This field follows its XML counterpart in almost all regards. The different XDG menu category names are encoded in the list, and are of type str.

Example:

Categories:
  - Network
  - Telephony

Field info: value-type:list

⁠Keywords

See <keywords/>.

This field contains the keywords for this component. The keys define the locales for the respective language, the values are of type list and contain the list of keywords for the respective language. An unlocalized C key must be present.

Example:

Keywords:
  C:
    - IDE
    - development
    - programming
  de:
    - IDE
    - entwicklung
    - programmierung

Field info: value-type:translated(list)

⁠Screenshots

See <screenshots/>.

The Screenshots field contains a list of screenshots. A screenshot is of type dict and contains the following keys:

default

If default is true, the screenshot is selected as default screenshot. There has to be at least one screenshot which is marked as default.

Field info: value-type:bool

source-image

Describes the source image for this screenshot. It has the following keys:

height
The image height (value-type:int)
width
The image width (value-type:int)
url
The full image url, or the url component added to MediaBaseUrl, if defined (value-type:str).
lang
The language this screenshot image is translated in. The value is a locale string. (value-type:str, required:no)

Field info: value-type:dict, required:yes

thumbnails

A list of an arbitrary number of screenshots. All screenshots are of type dict and must contain the same keys as described for source-image.

Field info: value-type:list, required:no

caption

A caption for this screenshot.

Field info: value-type:localized

Example for a Screenshots field containing one screenshot:

Screenshots:
  - default: true
    caption:
      C: Foobar showing kitchen-sink functionality
      si: Foobar shoeewing kischän-sünk funzionality
    source-image:
      height: 800
      url: http://www.example.org/en_US/main.png
      width: 600
    thumbnails:
      - height: 423
        width: 752
        url: http://www.example.org/en_US/main-large.png
      - height: 63
        width: 112
        url: http://www.example.org/en_US/main-small.png

Field info: value-type:list

⁠CompulsoryForDesktop

See <compulsory_for_desktop/>.

Field info: value-type:str

⁠Provides

See <provides/>.

The Provides field is of type dict and can have the following keys set with the described allowed values:

libraries: A list of provided library names.
Field info: value-type:list(str)
binaries: A list of provided binaries in PATH.
Field info: value-type:list(str)
mimetypes: A list of mimetypes this component can handle.
Field info: value-type:list(str)
firmware: A list of provided firmware. Each firmware entry is of type dict and has a type key, which has either runtime or flashed as value. Firmware of type flashed has a guid key, containing the GUID of the device the firmware is flashed on, while firmware of type runtime has a file key, containing the firmware filename which the kernel is looking for.
Field info: value-type:list(dict)
dbus: A list of provided DBus services. Each service entry in the list is of type dict and has a type key, which has either system or user as value. user means the DBus service name is for a user/session service, while system means it describes a system service. The service key contains the name of the DBus service file. All dict values are of type str.
Field info: value-type:list(dict)

Field info: value-type:dict

⁠DeveloperName

See <developer_name/>.

Field info: value-type:localized

⁠Releases

See <releases/>.

The Releases contains a list of releases, where each list items contains the following fields/keys:

version: The version number of this release.
Field info: value-type:str, required:yes
unix-timestamp: The UNIX timestamp of when this software was released.
One of the unix-timestamp or date fields must be present.
Field info: value-type:int, required:maybe
date: The ISO 8601 date of when this software was released.
One of the unix-timestamp or date fields must be present.
Field info: value-type:str, required:maybe
description: A description of this release. May contain allowed HTML markup.
Field info: value-type:localized

It is recommended to order this list starting with the latest timestamp to the olderst one.

Example:

Releases:
  - version: '1.8'
    unix-timestamp: 1424116753
    description:
      C: |
        <p>This stable release fixes the following bug:</p>
        <ul>
          <li>CPU no longer overheats when you hold down spacebar</li>
        </ul>
  - version: '1.2'
    unix-timestamp: 1397253600
  - version: '1.0'
    unix-timestamp: 1345932000

Field info: value-type:list(dict)

⁠Languages

See <languages/>.

The languages list is a list of dictionaries. They must contain a percentage key, indicating the completion of translation for this language, and a locale key, with the locale string as value.

Example:

Languages:
  - locale: gu
    percentage: 96
  - locale: ca@valencia
    percentage: 94
  - locale: de
    percentage: 91
  - locale: eo
    percentage: 93

Field info: value-type:list(dict)

⁠Bundles

See <bundle/>.

The Bundles contains a list of dictionaries with the keys type, having the ID for a specific bundling system (e.g. flatpak or limba) as value, and id for the associated bundle-id. See the XML tag description for information on all valid bundling systems.

Example:

Bundles:
  - type: limba
    id: foobar-1.0.2

Field info: value-type:list

⁠Extends

See <extends/>.

Contains a list of AppStream IDs of the other component extended by the described component. This field may only be used with component-type addon.

Field info: value-type:list(str)

⁠Suggests

See <suggests/>.

A list of dictionaries containing suggested software components. The dictionaries must have a type key with the string value upstream or heuristic depending on where the suggestion originates from. The also must have a ids key containing a list of component-ids of the suggested software.

Example:

Provides:
  - type: upstream
    ids:
      - org.example.Awesome
  - type: heuristic
    ids:
      - org.example.Test1
      - org.example.Test2

Field info: value-type:list(dict)

⁠3.2.6. Example YAML file

This is an example AppStream DEP-11 metadata file:

---
File: DEP-11
Version: '0.8'
Origin: chromodoris-main
MediaBaseUrl: http://metadata.tanglu.org/appstream/media/
---
Type: desktop-application
ID: gconf-editor.desktop
Icon:
  cached: gconf-editor_gconf-editor.png
Name:
  C: Configuration Editor
  be@latin: Redaktar naładaŭ
  bg: Настройки на програмите
  pl: Edytor konfiguracji
Package: gconf-editor
Summary:
  C: Directly edit your entire configuration database
  ar: حرّر مباشرة كامل قاعدة بيانات الإعدادات.
  de: Direkten Zugriff auf Ihre gesamte Konfigurationsdatenbank erlangen
Categories:
  - GNOME
  - GTK
  - System
---
Type: desktop-application
ID: kmplayer.desktop
Icon:
  cached: kmplayer_kmplayer.png
Name:
  C: KMPlayer
  hi: केएम-प्लेयर
  hne: केएम-प्लेयर
  ku: KMLêdar
  pa: KM-ਪਲੇਅਰ
  sr: КМ‑плејер
  sr@ijekavian: КМ‑плејер
  sv: Kmplayer
Package: kmplayer
Summary:
  C: KDE interface for MPlayer
Categories:
  - Qt
  - KDE
  - AudioVideo
  - Player
Provides:
  mimetypes:
    - application/ogg
    - application/smil
    - application/vnd.ms-asf
    - application/vnd.rn-realmedia
    - application/x-kmplayer
    - video/webm
    - video/x-avi
---
ID: texstudio.desktop
Type: desktop-application
Package: texstudio
Name:
  C: TeXstudio
Summary:
  C: LaTeX development environment
  fr: Environnement de développement LaTeX
Description:
  C: <p>TeXstudio is an integrated writing environment for creating LaTeX documents. It integrates editing,
    building and viewing into a single frontend.</p><p>Our goal is to make writing LaTeX as easy and comfortable
    as possible. This is achieved through a rich feature set including:</p>
Icon:
  cached: texstudio_texstudio.png
Keywords:
  C:
    - editor
    - latex
    - pdflatex
    - xelatex
    - lualatex
    - context
    - bibtex
ProjectLicense: GPL-2.0
Url:
  homepage: http://texstudio.sourceforge.net/
Categories:
  - Office
  - Publishing
Provides:
  mimetypes:
    - text/x-tex
Screenshots:
  - default: true
    source-image:
      height: 756
      url: texstudio_2.8.4+debian-3_amd64/screenshots/source/screenshot-1.png
      width: 1344
    thumbnails:
      - height: 423
        url: texstudio_2.8.4+debian-3_amd64/screenshots/752x423/screenshot-1.png
        width: 752
      - height: 351
        url: texstudio_2.8.4+debian-3_amd64/screenshots/624x351/screenshot-1.png
        width: 624
      - height: 63
        url: texstudio_2.8.4+debian-3_amd64/screenshots/112x63/screenshot-1.png
        width: 112