FreeDesktop.Org specifications

FreeDesktop.Org provides specifications (and software) for configuring foundational features to a desktop user experience, which GNOME, KDE, and other smaller UI frameworks implements. It’s not (grumble grumble) implemented by Mac, Windows, Android, or iOS.

These elegant specs are a joy to implement & have supported an impressive variety of experiences! Personally I find them invaluable for addressing complexity in some certain other standards.

FreeDesktop.Org places these configuration files in $XDG_DATA_HOME (defaults to ~/.local/share/), $XDG_CONFIG_HOME (default ~/.config/), $XDG_DATA_DIRS (default /usr/{local/,}share/), $XDG_CONFIG_DIRS (default /etc/xdg/), or $XDG_CACHE_HOME (default ~/.cache).

These files typically use the syntax I’ll call “INI-style”:

    other[locale]=localized value

Or (unnamespaced) XML.

Placing these INI-style files under $XDG_DATA_DIRS/applications/ defines installed apps with their branding, the command(s) to run it, supported mimetypes (and via the x-scheme-handler/ prefix, URI schemes), and any special “actions” offered. These will usually be available by rightclicking the app icon, though other UXs are valid.

Apps may optionally expose a DBus API providing methods to activate, open files, & run actions. They must provide an equivalent commandline interface.

You can define filetypes by placing an XML file at {$XDG_DATA_HOME,$XDG_DATA_DIRS}/mime/$MIMETYPE.xmldescribing how to programmatically recognize a file of that type, relationships to other MIMEtypes, & branding. Running the update-mime-database command aggregates all this information into a handful of also standardized files describing how to “sniff” the mimetype where it’s unknown (no attached user.mime_type file attribute).

Both filetypes & apps can be represented by a named icon from the installed icon theme. These icon themes are directory hierarchies in ~/.icons/, $XDG_DATA_DIRS/icons/, and/or /usr/share/pixmaps with a INI-style file in it’s root directory describing the which subfolders to use for different icon sizes (as well as labelling).

Another spec names some other icons you should expect to be able to find in an icon theme.

Fun fact: my browsers expose this standard via xdg-icon: URIs!

Place or symlink .desktop files describing an app in $XDG_CONFIG_DIRS/autostart/ for it to run at startup.

You can place another INI-style file named {$XDG_CURRENT_DESKTOP-,}mimeapps.list in the config and/or apps directories to add or remove associations from MIMEtypes to apps. Or set a prioritized defaults list for a MIMEtype.

XML files in $XDG_CONFIG_DIRS/menus/ finalizes the categorization of apps in your desktop’s launcher. .desktop files define the initial categorization.

URI Schemes

FreeDesktop.Org has standardized appstream:// URIs for linking to an app’s installation screen regardless of distro. (See why I’m grumbling about lack of support in proprietary desktops?)

They’ve standardized file:// because I’m guessing it wasn’t before.

They have help: to display documents in $XDG_DATA_DIRS/help/$LOCALE/.

elementary’s spearheading setting: URIs for linking to settings panes, but there’s lack of agreement on requirements.


They have a suite of standards filling in X11 gaps (hence “XDG” for “X11 Desktop Group”), which have now been superceded by their non-DBus Wayland protocol.

And they have another suite allowing running apps to communicate between each other & the rest of the desktop using their DBus Remote Procedure Call protocol (which, yes, is network-transparant).

Underlying the RPC DBus defines how to parse binary data according to an ASCII type signature, packetize datastreams, & authenticate.

DBus packets may represent a method call, method return, error, or event being triggered. There’s usually a daemon routing packets to the specified RPC object with possible access control, though I’ve seen discussions wanting Linux to give them a IPC medium more performant for their uses.

The daemon may also, if configured via an INI-style file in a “bus”-specific directory, automatically run daemons upon first contact.

FreeDesktop.Org standardizes DBus interfaces for: