AppStream Catalog YAML

Introduction DEP-11 is a YAML implementation of the AppStream catalog 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. 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 catalog metadata. Fields not mentioned in this document are not recognized by DEP-11 YAML parsers.

File naming and location Take a look at for AppStream XML files for reference. While the XML data belongs into the xml subdirectory in /usr/share/swcatalog (or /var/(lib|cache)/swcatalog), 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 and the icon search logic.

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

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:

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 . 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 . Field info: value-type:int, required:no Type The type of this component. Allowed values are: generic for desktop-application for console-application for addon for codec for inputmethod for firmware for 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 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 . Field info: value-type:str, required:yes SourcePackage See . Field info: value-type:str Name See . Field info: value-type:localized, required:yes Summary See . Field info: value-type:localized, required:yes ProjectLicense See . Field info: value-type:str Description See . 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 . 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: Field info: value-type:dict ProjectGroup See . Field info: value-type:str Icon See . 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 . 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: Field info: value-type:list Keywords See . 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: Field info: value-type:translated(list) Screenshots See . 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: Field info: value-type:list CompulsoryForDesktop See . Field info: value-type:str Provides See . 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) fonts A list of provided fonts. Each font entry is of type dict and has a name key. Field info: value-type:list(dict) modaliases A list of modalias globs representing the hardware types this component handles. Field info: value-type:list(str) mediatypes A list of media types (MIME types) 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) python3 A list of Python 3 modules this component provides. Field info: value-type:list(str) 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) ids A list of component-IDs that this component is able to provide all functionality of. Field info: value-type:list(str) Field info: value-type:dict DeveloperName See . Field info: value-type:dict Launchable See . A dictionary containing the launchable-type as key, and a list of IDs used for launching the application as value. Example: Field info: value-type:dict(list) Releases See . 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 type The release type. Allowed values are: stable development By default, if no release type is defined, stable is assumed. Field info: value-type:str, required:no urgency How important it is to install the new release as an update. Allowed values are: low medium high critical If no urgency is defined, a medium urgency is implicitly assumed. Field info: value-type:str, required:no 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) artifacts A list of dictionaries describing the artifacts published for this release. Refer to the XML specification for details, which is mapped to YAML following the usual scheme. Field info: value-type:list(dict) It is recommended to order this list starting with the latest timestamp to the oldest one. Example: This stable release fixes the following bug:

CPU no longer overheats when you hold down spacebar

- version: '1.2' unix-timestamp: 1397253600 - version: '1.0' unix-timestamp: 1345932000]]> Field info: value-type:list(dict) Languages See . 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: Field info: value-type:list(dict) Bundles See . 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: Field info: value-type:list Extends See . 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 . 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: Field info: value-type:list(dict) ContentRating See . 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: Field info: value-type:dict(dict) Requires, Recommends & Supports See . 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 << - Less than >> - Greater than <= - Less than or equal to >= - Greater than or equal to Example: = 4.15' - id: org.example.TestDependency version: == 1.2]]> Field info: value-type:list(dict) Agreements See . 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: -

If it breaks, you get to keep both pieces.

]]> Field info: value-type:list(dict) Tags See . Field info: value-type:list(dict) Example: References See . Field info: value-type:list(dict) Example: Custom See . Field info: value-type:list(dict)

Example YAML file This is an example AppStream DEP-11 metadata file: TeXstudio is an integrated writing environment for creating LaTeX documents. It integrates editing, building and viewing into a single frontend.

Our goal is to make writing LaTeX as easy and comfortable as possible. This is achieved through a rich feature set including:

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: mediatypes: - 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]]>