Snap interface metadata (i.e. descriptions)

Applications that control Snap interfaces need to show descriptions to users. This is currently done using description text that the design and security teams came up with. For example, the “home” interface is described as “Access files in your home folder”. snapd provides summary text for each of the interfaces and this is shown when ‘snap interface’ is called. The “home” interface has the summary “allows access to non-hidden files in the home directory”. The text provided by snapd is unsuitable because it is not worded in a suitable way (sentence fragments, too technical) for the user interface and is not translatable.

$ snap interface 
Name                      Summary
appstream-metadata        allows access to AppStream metadata
audio-playback            allows audio playback via supporting services
browser-support           allows access to various APIs needed by modern web browsers
content                   allows sharing code and data with other snaps
cups-control              allows access to the CUPS control socket
desktop                   allows access to basic graphical desktop resources
desktop-legacy            allows privileged access to desktop legacy methods
gsettings                 allows access to any gsettings item of current user
hardware-observe          allows reading information about system hardware
home                      allows access to non-hidden files in the home directory
log-observe               allows read access to system logs
lxd-support               allows operating as the LXD service
mount-observe             allows reading mount table and quota information
network                   allows access to the network
network-bind              allows operating as a network service
network-manager           allows operating as the NetworkManager service
network-observe           allows querying network status
opengl                    allows access to OpenGL stack
packagekit-control        allows control of the PackageKit service
password-manager-service  allows access to common password manager services
process-control           allows controlling other processes
pulseaudio                allows operating as or interacting with the pulseaudio service
snapd-control             allows communicating with snapd
system-files              allows access to system files or directories
system-observe            allows observing all processes and drivers
unity7                    allows interacting with Unity 7 services
upower-observe            allows operating as or reading from the UPower service
wayland                   allows access to compositors supporting wayland protocol
x11                       allows interacting with or running as an X11 server

There is an ongoing issue that every time a new interface is created, clients need to update their table of descriptions. For example today, the system settings app doesn’t understand the audio-playback interface, as this was added after the text was decided for interfaces. So users just get the fallback behaviour of showing the interface name:
If we were to replace the text with the summaries provided by snapd, it would instead look like this (and only show in English):
We really need to manage the descriptions in a central location to allow this to scale. The following possibilities come to mind:

  • Change the summary text provided by snapd so that it is suitable for both the command line and GUI.

  • Add a new field to the snapd metadata that has text suitable for this case and keep existing summary text unchanged.

  • Implement translations in snapd. This is really required for the above two options.

  • Move the interface descriptions into snapd-glib as this is easier to update and many clients use this.

More detail on why “allows audio playback via supporting services” is not suitable in the settings app:

  • It is not a valid sentence - it does not start with a capital letter.
  • This requires the interface name to be used in the label, as it describes what the interface does, not what the app is allowed to do. If it described the app it would say “allow audio playback via supporting services”.
  • Since all the summaries start with “allows” it looks repetitive when listed with other interfaces.
  • It’s highly technical - what is a “supporting service”? The interface is a fairly simple concept (able to play sound) but the description confuses it. Note that we could more technical data shown elsewhere in the UI, but it shouldn’t be shown up front.

The current descriptions are meant to be developer-friendly and attempt to use a consistent style to convey what the interface is meant to do. IME it will be very difficult to strike the right balance between a developer-friendly string and a user-friendly string for the UI (look at pulseaudio-- it is trying to describe two points of view: being a service and being a client). The UI might, as you describe, need things formatted a certain way that maybe doesn’t make sense for the cli.

I agree that maintaining the user-friendly descriptions is a maintenance burden. We probably should add a new (translatable) field to all the interfaces (eg, “ui-summary”) that you can then consume. In the process of doing this, we could also add “ui-labels” or something that can contain things like “deprecated” or “transitional” or whatever makes sense.

1 Like

That’s interesting, I think they actually need to be admin friendly (as they appear in snap interface) which still probably does not make them suitable for re-use in a friendly GUI context.

Whether we want to maintain other descriptions suitable for other usages in snapd itself merits a bit more discussion.

Those don’t sound (G)UI specific, actually they sound partially developer oriented again.