GNOME.org

Application IDs

This page documents application IDs, what they are used for, and best practices for how you should pick one.

Introduction

GNOME technologies make extensive use of "reverse DNS" style identifiers for applications. One of the first things that you will need to do when developing an application is to choose an appropriate identifier.

An example of such an identifier is "org.gnome.gedit".

Application identifiers are very widely used and changing them can cause problems. For this reason, you should choose your identifier carefully, with an eye to the future of your application.

Things that use application IDs

Application IDs are used in the following places:

  • by GtkApplication (or GApplication) as a method of identifying your application to the system, for ensuring that only one instance of your application is running at a given time, and as a way of passing messages to your application (such as an instruction to open a file)

  • by D-Bus, to name your application on the message bus. This is the primary means of communicating between applications and is visible via the gdbus commandline tool or the d-feet graphical D-Bus browser.

  • as the name of the ".desktop file" for your application. This file is how you describe your application to the system (so that it can be displayed in and launched by gnome-shell).

  • as the base name of any GSettings schemas that your application may install. These names are visible via the gsettings commandline tool or the dconf-editor graphical editor.

  • as a way for the system to remember state information about your applications (for example, which notifications it has requested to be shown to the user) and as a way for it to control settings about your application (for example, if its notifications have been blocked by the user)
  • as a way for the system to use your application to extend itself (for example, by way of search providers)
  • as the bundle name for application bundles

Rules for application IDs

The precise rules for what makes a valid application ID are as follows:

  • the application ID must be composed of two or more elements separated by a period ('.') character

  • each element must contain one or more of the alphanumeric characters (A-Z, a-z, 0-9) plus underscore ('_') and hyphen ('-') and must not start with a digit

  • the empty string is not a valid element (ie: your application ID may not start or end with a period and it is not valid to have two periods in a row)

  • the entire ID must be less than 255 characters in length

Guidelines for choosing an application ID

The most important thing in choosing a name is that it must be globally unique. Bad things will happen if two unrelated applications try to use the same application ID.

For this reason, it is very strongly recommended to choose a name based on the global public DNS system. For example, if you owned the domain yorba.org, you would probably want to name your application "myapp" like "org.yorba.myapp".

If your application is a member of or strongly affiliated with a given Free Software project then it is appropriate to use the public DNS name of that project, provided you follow their guidelines and policies. "Strongly affiliated" in this case generally means "using the version control, bugtracking, etc. of the project in question". In the case of the GNOME project, we are working on these guidelines at present and the board hopes to make a proposal in early 2019 and consult with the community. In the mean time, only applications which are hosted in the GNOME group on gitlab.gnome.org should use names like "org.gnome.myapp".

Sometimes it is not possible to choose an ID based on a domain that you own. In this case, it is usually possible to fall back to something reasonable, such as an account name on a public provider. Names such as "com.github.username.myapp" or "com.gmail.myemailaddr.myapp" are examples of those.