Dashes and underscores in desktop file IDs

[Simon McVittie]

For historical reasons, D-Bus well-known bus names allow both dashes
and underscores (but D-Bus object paths and interface names don't allow
dashes). The Desktop Entry Specification has inherited this oddity.
This causes intermittent problems in adjacent specifications like
Flatpak app IDs and the DBusActivatable API, where there need to be
strange special cases if you happen to own a domain name containing
dashes, most recently
<https://github.com/flatpak/flatpak-builder/issues/37>
<https://github.com/parnold-x/nasc/issues/67> and
<https://github.com/elementary/houston/issues/436>.

Relatedly, it isn't obvious what to do if your domain name contains
a label (element) starting with a digit. I would like to clarify this
by putting some recommendations and anti-recommendations in the
relevant specifications, so that the story is clearer for app authors.
It would be a compatibility break to actually *forbid* one or the other,
but I think we can safely recommend against it (as in SHOULD NOT rather
than MUST NOT).

I personally think the recommendation should be:

* Don't use dashes in new app IDs
* Replace dashes with underscores
* Prepend an underscore to elements that would otherwise start with a
digit

and I've proposed some possible patches for the Desktop Entry spec on
<https://bugs.freedesktop.org/show_bug.cgi?id=103216>. The D-Bus
Specification should also have a corresponding change, when we've
agreed on what the change should be.

If there is consensus that the recommendation should be dashes and not
underscores, I'd be willing to go with that instead, but I think we
should pick one.

Unfortunately it looks as though the AppStream spec currently allows
dashes but not underscores, which (if enforced) conflicts fairly badly
with Flatpak renaming AppStream XML that doesn't match the Flatpak app
IDs (underscores but not dashes). Would the maintainers of AppStream
be willing/able to relax the spec for <id> to allow underscores?
If not, then I think the AppStream spec should explain what you should
do if your desktop file ID contains an underscore (presumably replacing
it with a dash).

Thoughts?

Thanks,
smcv

[r***@gmail.com]

Post by Simon McVittie
If there is consensus that the recommendation should be dashes and not
underscores, I'd be willing to go with that instead, but I think we
should pick one.

I'd like to cast a vote in favor of dashes instead of underscores, primarily
because (at least on US keyboards), typing an underscore requires pressing
<shift> while typing a dash does not.

I do agree that a standard would be nice--in lots of situations (not just app
names, but also filenames for example), either might be used, and if I need to
glance at a filename, store it in short term wetwork memory, I always have
trouble distinguishing and remembering whether what I saw was a dash or an
underbar. It requires an extra level of concentration which I would prefer to
avoid.

(I suppose I will eventually train myself to look more carefully at things
like filenames with underbars or dashes rather than have to go back and look a
2nd time.)

Post by Simon McVittie
Unfortunately it looks as though the AppStream spec currently allows
dashes but not underscores, which (if enforced) conflicts fairly badly
with Flatpak renaming AppStream XML that doesn't match the Flatpak app
IDs (underscores but not dashes). Would the maintainers of AppStream
be willing/able to relax the spec for <id> to allow underscores?
If not, then I think the AppStream spec should explain what you should
do if your desktop file ID contains an underscore (presumably replacing
it with a dash).

[Simon McVittie]

Post by r***@gmail.com

Post by Simon McVittie
If there is consensus that the recommendation should be dashes and not
underscores, I'd be willing to go with that instead, but I think we
should pick one.

I'd like to cast a vote in favor of dashes instead of underscores, primarily
because (at least on US keyboards), typing an underscore requires pressing
<shift> while typing a dash does not.

Sorry, but I think the syntactic restrictions in various protocols
and specifications (some of which would be an API/ABI break to change)
should be a more important consideration here than ease of typing.

smcv

[Matthias Klumpp]

Hey, sorry for the late reply!

Post by Simon McVittie
For historical reasons, D-Bus well-known bus names allow both dashes
and underscores (but D-Bus object paths and interface names don't allow
dashes). The Desktop Entry Specification has inherited this oddity.
This causes intermittent problems in adjacent specifications like
Flatpak app IDs and the DBusActivatable API, where there need to be
strange special cases if you happen to own a domain name containing
dashes, most recently
<https://github.com/flatpak/flatpak-builder/issues/37>
<https://github.com/parnold-x/nasc/issues/67> and
<https://github.com/elementary/houston/issues/436>.
Relatedly, it isn't obvious what to do if your domain name contains
a label (element) starting with a digit. I would like to clarify this
by putting some recommendations and anti-recommendations in the
relevant specifications, so that the story is clearer for app authors.
It would be a compatibility break to actually *forbid* one or the other,
but I think we can safely recommend against it (as in SHOULD NOT rather
than MUST NOT).

Sounds good to me!

Post by Simon McVittie
* Don't use dashes in new app IDs
* Replace dashes with underscores
* Prepend an underscore to elements that would otherwise start with a
digit
and I've proposed some possible patches for the Desktop Entry spec on
<https://bugs.freedesktop.org/show_bug.cgi?id=103216>. The D-Bus
Specification should also have a corresponding change, when we've
agreed on what the change should be.
If there is consensus that the recommendation should be dashes and not
underscores, I'd be willing to go with that instead, but I think we
should pick one.

Is there a chance that DBus and other tools can get rid of the naming
limitations anytime soon? Or does the "no-digit-start, no-dash" rule
have to stay forever?

Post by Simon McVittie
Unfortunately it looks as though the AppStream spec currently allows
dashes but not underscores, which (if enforced) conflicts fairly badly
with Flatpak renaming AppStream XML that doesn't match the Flatpak app
IDs (underscores but not dashes). Would the maintainers of AppStream
be willing/able to relax the spec for <id> to allow underscores?

Urgh, that is definitely a bug, AppStream should allow underscores for
sure. I will fix that with the next release.

Post by Simon McVittie
If not, then I think the AppStream spec should explain what you should
do if your desktop file ID contains an underscore (presumably replacing
it with a dash).

There's no need for that, fortunately :-)
I will add the naming recommendations you outlined above to AppStream
in the next release, because the AppStream ID is used by Flatpak to
generate bundle names (and to reduce confusion). The AS spec should
really allow underscores, because they are an allowed character in
domain names, so that part is just a bug, and likely my mistake.

Thanks for raising this issue!
Cheers,
Matthias

[Alexander Larsson]

Post by Matthias Klumpp
Hey, sorry for the late reply!

Post by Simon McVittie
For historical reasons, D-Bus well-known bus names allow both dashes
and underscores (but D-Bus object paths and interface names don't allow
dashes). The Desktop Entry Specification has inherited this oddity.
This causes intermittent problems in adjacent specifications like
Flatpak app IDs and the DBusActivatable API, where there need to be
strange special cases if you happen to own a domain name containing
dashes, most recently
<https://github.com/flatpak/flatpak-builder/issues/37>
<https://github.com/parnold-x/nasc/issues/67> and
<https://github.com/elementary/houston/issues/436>.
Relatedly, it isn't obvious what to do if your domain name contains
a label (element) starting with a digit. I would like to clarify this
by putting some recommendations and anti-recommendations in the
relevant specifications, so that the story is clearer for app authors.
It would be a compatibility break to actually *forbid* one or the other,
but I think we can safely recommend against it (as in SHOULD NOT rather
than MUST NOT).

Sounds good to me!

Post by Simon McVittie
* Don't use dashes in new app IDs
* Replace dashes with underscores
* Prepend an underscore to elements that would otherwise start with a
digit
and I've proposed some possible patches for the Desktop Entry spec on
<https://bugs.freedesktop.org/show_bug.cgi?id=103216>. The D-Bus
Specification should also have a corresponding change, when we've
agreed on what the change should be.
If there is consensus that the recommendation should be dashes and not
underscores, I'd be willing to go with that instead, but I think we
should pick one.

Is there a chance that DBus and other tools can get rid of the naming
limitations anytime soon? Or does the "no-digit-start, no-dash" rule
have to stay forever?

Flatpak sort of relies on this in the exported-filename-prefix rules.
In particular, to avoid conflicts, all exported files must have the app
id as prefix, followed by a dot, or an invalid character.

So, for example org.the.App is allowed to export:
org.the.App
org.the.App.png
org.the.App-symbolic.png

But not:
org.the.AppOther
org.the.App_symbolic.png

So, if - was allowed, then we could not export the symbolic icons.

[Simon McVittie]

Post by Matthias Klumpp
Is there a chance that DBus and other tools can get rid of the naming
limitations anytime soon? Or does the "no-digit-start, no-dash" rule
have to stay forever?

Given the number of D-Bus implementations floating around, and the
historical behaviour of the reference implementation (libdbus enforces
syntax rules strictly but historically didn't have public API to do
the necessary checks, so every language binding had to NIH the correct
validation), I think that would be an incompatible change of the sort
that we Do Not Do.

Also, encouraging underscores and deprecating dashes would align
the recommended character set for D-Bus well-known names with the
required character set for D-Bus interface names, which are more
strict than well-known names (and in particular have never allowed
dashes). Interface names are designed to be usable in code generation
(e.g. some C++ bindings would map D-Bus com.example.MyInterface.MyMethod
to C++ com::example::MyInterface::MyMethod) which I believe is why we
never allowed dashes and leading digits there, and should not in future.

Post by Matthias Klumpp
Urgh, that is definitely a bug, AppStream should allow underscores for
sure. I will fix that with the next release.

Thanks!

Post by Matthias Klumpp
The AS spec should
really allow underscores, because they are an allowed character in
domain names, so that part is just a bug, and likely my mistake.

Underscores are an allowed character in the DNS protocol. They are *not*
an allowed character in domain names[1], and that's why replacing dashes with
underscores does not risk collisions: the owner of awesome-software.com
is free to use com.awesome_software in their desktop file ID, D-Bus API,
AppStream etc. in the knowledge that they are not conflicting with the
owner of awesome_software.com, because awesome_software.com cannot exist.

(This is also why underscores are used in DNS SRV: they're allowed in
the DNS protocol, but cannot appear in hostnames or domain names, so
the special SRV DNS names like _ipp._tcp.example.com cannot collide with
anyone's hostname or domain name.)

However, underscores are an allowed character in D-Bus well-known names,
and the recommended syntax for desktop file IDs is a D-Bus well-known name,
which suggests that designs that reflect or mimic desktop file IDs (like
the AppStream <id>) should probably allow underscores anyway.

smcv

[1] https://tools.ietf.org/html/rfc1035 "The labels must follow the
rules for ARPANET host names. They must start with a letter, end with a
letter or digit, and have as interior characters only letters, digits,
and hyphen."