- Prev
- AppStream
- Next

## ⁠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:

1. They are of type dict
2. They must contain a key `C`, with the untranslated string as value
3. 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.6, “Addons”
  - `codec` for Section 2.9, “Codecs”
  - `inputmethod` for Section 2.10, “Input Methods”
  - `firmware` for Section 2.11, “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`, `replace` or `remove-component`.
  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: https://example.org
        faq: https://example.org/faq
        bugtracker: https://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. If this field is present, `videos` must not be present as well. The field valus is a dictionary with 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:conditional

  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`. This key must not be present if `videos` is present.

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

  videos
    Contains a list of video dicts for this screenshot. If this field is present, `source-image` must not be present as well. The field valus is a dictionary with the following keys:
    - `container`
      The video container format (value-type:str, values as described in the XML specification)
    - `codec`
      The video codec format (value-type:str, values as described in the XML specification)
    - `height`
      The video height (value-type:int)
    - `width`
      The video width (value-type:int)
    - `url`
      The full video url, or the url component added to `MediaBaseUrl`, if defined (value-type:str).
    - `lang`
      The language this screenshot video is translated in. The value is a locale string. (value-type:str, required:no)

    Field info: value-type:list(dict), required:conditional

  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: https://www.example.org/en_US/main.png
            width: 600
          thumbnails:
            - height: 423
              width: 752
              url: https://www.example.org/en_US/main-large.png
            - height: 63
              width: 112
              url: https://www.example.org/en_US/main-small.png
        - source-video:
            container: matroska
            codec: av1
            height: 900
            url: https://www.example.org/en_US/screencast.mkv
            width: 1600

  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

⁠Launchable
  See <launchable/>.
  A dictionary containing the launchable-type as key, and a list of IDs used for launching the application as value.
  Example:

      Launch:
        desktop-id:
          - org.gnome.Sysprof2.desktop

  Field info: value-type:dict(list)

⁠Releases
  See <releases/>.
  The `Releases` contains a list of releases sorted latest-to-oldest, 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 complete 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

  issues
    A list of dictionaries describing the issues resolved by this release. The dictionaries contain a `id` key for the value of an issue as described in the XML specification, as well as a `type` and `url` key for the tag properties of the same name described in the XML AppStream specification.

    Field info: value-type:list(dict)

  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:

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

  Field info: value-type:list(dict)

⁠ContentRating
  See <content_rating/>.
  A dictionary containing the rating system as key, and a dictionary of rating-values as value. The value-dictionary itself has the content rating IDs as keys and the intensity values as values. The intensity values as well as IDs and rating system names match the values from the XML exactly.
  Example:

      ContentRating:
        oars-1.0:
          drugs-alcohol: moderate
          language-humor: mild

  Field info: value-type:dict(dict)

⁠Requires & Recommends
  See <requires/> & <recommends/>.
  A list of dictionaries containing the referenced items. The dictionaries in the list must have one key denoting the item type, which has the respective item value as value. Refer to the XML description for a list of possible types.
  Each dictionary may have a `version` field with contains a version comparison string. The first two characters denote the version comparison operation, and are followed by the version number to be compared with. The comparison operation may be one of:
  - `==` - Equal to
  - `!=` - Not equal to
  - `<<` - Lesser than
  - `>>` - Greater than
  - `<=` - Lesser than or equal to
  - `>=` - Greater than or equal to
  Example:

      Recommends:
      - memory: '2500'
      - modalias: usb:v1130p0202d*
      Requires:
      - kernel: Linux
        version: '>= 4.15'
      - id: org.example.TestDependency
        version: == 1.2

  Field info: value-type:list(dict)

⁠Agreements
  See <agreement/>.
  A list containing the agreements as dictionaries, with a `sections` key containing a list of sections. All dict values are the same as the respective XML tag values / properties.
  Example:

      Agreements:
      - type: eula
        version_id: 1.2.3a
        sections:
        - type: intro
          name:
            C: Intro\n"
          description:
            C: >-
              <p>If it breaks, you get to keep both pieces.</p>

  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: https://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: https://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

- PrevChapter 3. Collection Metadata
- Up
- Home
- Next3.3. Icon Cache