'slug', 'namespace' and 'managedBy' properties

There are 3 somewhat generic properties I’d like to discuss! I don’t have them in Vervis and there’s otherwise no specific need for them that I have in mind, but I do have ideas, and I do want to document them in case they soon do become more clearly useful.


On the Fediverse, as a user you have 2 names basically:

  1. Your username, that appears in your profile URL
  2. A not-necessarily-unique arbitrary name you can choose and change any time you like

If I recall correctly, the former is placed under the preferredUsername property, and is used for WebFinger lookup. The latter is placed under name and is used just for display in UI. For example, your preferredUsername may be “alice” and your name could be “Alice the adventurous explorer”.

Now let’s look at forges and repos. Repos too have 2 names:

  1. A generally-not-changing string with some strict rules such as having no spaces, which appears in the repo URL and is commonly used in shorthand references to the repo
  2. An arbitrary free-to-change name string

For example, the former may be “linux-libre” while the latter could be “Linux-Libre: A version of the Linux kernel with all proprietary bits removed”.

I don’t know if the former appears-in-URL name is useful in a federated context, but I do know it’s generally a recognizable name for a repo, much like on Mastodon people can change their name but you’d still recognize them by their @user@host (and their profile picture and so on).

I’m proposing to have a property for this concept, i.e. a generalization of preferredUsername for things that aren’t users, such as repos. We could call this property slug.


In a federated context, the only unique reference to a resource is its absolute URI. When displayed in UI, you may wish to use something shorter and recognizable. Sometimes URIs just look random. One thing you can do, to get started, is to separate the URI host and the URI path. And for local resources, you can entirely avoid displaying the host, much like on Mastodon local users are referred as @user and remote users as @user@host in activity feed displays. But in a general context that involves not just users but also repos, projects, issues, etc., if you split out the host you’re left with the URI path, which may still look long or even ugly.

A pretty example for a path of a repo URL is /user/repo, which is used on GitLab and on githu8 and in other places. But there are other options, for example gitweb may use something like /git/?p=REPO.git;a=summary, and someone may just use random UUIDs in the URI.

It could be nice, and maybe useful too, to have some way to refer to the logical position of the object on the instance, even if the object’s @id URI is ugly and isn’t useful or friendly to human eyes. We don’t have to require this logical position reference to be unique among all the objects hosted by the instance; maybe it’s enough for it to be unique among objects of its type, and the UI can display an indication of the type, making it recognizable reference to the object much like @user is.

For example, at pagure.io, some repos are at the “top level” namespace, and their URI looks like https://pagure.io/REPO, and some are on a secondary namespace, e.g. https://pagure.io/GROUP/REPO. For the former case, you could say the namespace is REPO, and for the latter it’s GROUP/REPO. Even if the URIs weren’t that pretty, and looked random, having access to this logical namespace info could be useful. For example in the gitweb example, /git/?p=REPO.git;a=summary, the namespace would be REPO.

Perhaps we could have a property namespace for this.


So far in ForgeFed we have 2 kinds of objects:

  • Objects that are generally agreed to be actors, and you can interact with them by POSTing to their inbox
  • Objects that aren’t necessarily actors, but you still may wish/need to interact with them, and that happens by POSTing to the inbox of the actor who “owns” the object

In the basic microblogging model e.g. in Mastodon, the object situation is in a way simple and everything revolves around users. But in the context of forges there are more types of objects and relationships, and it would be nice, and possibly very useful, to have a general way to determine how to interact with a given object, even if it doesn’t have its own inbox, and even if you don’t recognize its @type.

So I came up with a property named managedBy. If an object isn’t an actor, but is interacted with via some parent object, then managedBy is a way to point from the object to the parent that is an actor and has an inbox.

For example, suppose there’s an issue dependency object, that says “issue #2 depends on issue #1” and as a project team member, you decided to remove this dependency. You probably want to send a Delete activity, or maybe a Remove, but to whom do you send it? If issue dependencies aren’t actors, it would be nice to know who the responsible actor is. If you know ForgeFed terms, you can look at the issues #1 and #2, maybe discover they belong to the same repo, and check if that repo is an actor. Or some other logic. But if there’s no clear algorithm, or if your software doesn’t understand all the ForgeFed terms and tiny details, you can look at the managedBy property of the issue dependency object, GET the specified URI, which should be an actor with an inbox, and send your activity there. It allows for flexibility, because instead of having strict structures and algorithms (which isn’t necessarily easy because each web app has its own way to organize things), you can have this more generic property you can look at.

QUESTION 1: What are your thoughts about these properties?

QUESTION 2: Should we add them to the spec, and remove later if not really useful, or wait until there are signs of real need and use? It’s also an issue of spec clarity: These properties give real world access to otherwise abstract concepts, so I think it adds some value to mention them alongside the descriptions of the concepts.

Your argumentation makes sense to me, I have nothing to really criticise besides some nit-piking.

I think this distinction is a little bit unprecise; I’d put it slightly differently.
I do not mean to invalidate your statement, just having a deeper look.

You most likely have both of the following two in any system, no matter whether centralized or not:

  1. Your user name (username), e.g your Actor’s preferredUsername. Used for technical addressing. An “arbitrary name you can choose”, as you put it. But the character set is, for the sake of simpler (technical) addressing limited (for example to /a-z0-9._/i) (as you also mention in the repos section). The “change any time you like” part relies on the specific implementation, some do allow that, some do not. Example: criztovyl, stylized as @criztovyl.
  2. Your display name, for example your actor’s name. Arbitrary string, “you can choose and change any time you like” as you put it; with the addition that it has only little limitations of what characters you can choose and/because is not used for technical addressing, just for display. Example: “Christoph ‘criztovyl’ Schulz”

Now, in centralized systems your username will enough to uniquely address you. In federated networks (i.e. networks of centralized systems) you will also need to take into account the user’s instance.
Depending on the specificity of your system the instance might be all the additional information you need (SMTP; i.e. username@instance), but does not need to be (AS/AP) and you then need an general ID. (I don’t find good names so I’ll further refer to this two kinds by description.)

An intermediate summary is that for a AP-like federated system you have three “names”. I’d call them identifiers, which, in reverse order of specificity, are display name, username, ID.

In systems that additionally to the username only require the instance, the ID is memorable because it (most likely) combines two system specifically build for this purpose, usernames and the DNS, and are technically sufficient for (technical) addressing and delivery.

In systems that require other additional information, the technical challenge is not hard: Just use IRIs. In that case you don’t even need to care about usernames and instances for technical addressing and delivery: The username in this case is irrelevant and the instance is either encoded in the IRI (http) or there system does not even have a concept of “instances” (dat, torrent, etc) and the IRI is the only thing that (technically) counts.

Now you have an disadvantage over systems that only require the instance: Your IDs have no guarantee to be memorable and most likely won’t be.

To come back to the original topic, IRIs are pretty ugly to display, but you still have the other two identifiers! So, for (naive) display no new approaches are required, you can just reuse the user- and display-names.
New approaches are only required to deal with collisions, if you for example have two users which both use “Bob” and @bob; but the easiest way is to just also always display the IRI.

When it comes to repos, similarly as you described, I think the same things apply. A repository also has all three identifiers, just “username” needs a new (hah!) name. slug seems to be well.

To clarify it in context of my descriptions this derivation does not make sense there as I described IRIs as opaque. And even if there are patterns in the URI, there is no guarantee for it and therefore not useful.

The necessity you derive still keeps it’s validity, I am all with you to have an namespace property.

A thing I would add is that it might be useful to have this as a ordered list so you don’t have to encode “namespace X is below Y which is below Z” as "Z/Y/X" but instead as ["Z", "Y", "X"]. This would even add the possibility to easily refer to intermediate namespaces if you make the elements @ids: ["https://my.instance/group/foogroup", "https://my.instance/component/barcomponent"].


I’d say they should go to a spec. You also have expressed and describe the necessity for all three properties that I think count as “signs of real need”. The specific ForgeFed spec seems not to be the right place but an own spec sounds okay. It could for example live under peers.community or feneas umbrella.

Why not just use preferredUsername for Actors and name for repositories? I’m not sure there is a need for an extra property?

I’m not convinced of this one either, it feels premature optimization of use cases for someone that might come up. As always before, I would encourage to think simple. AS2 is extensible. There is no need to think of everything, forcing everyone to consider the cases. You’ve taken a huge task to yourself, I would encourage to keep a minimalist approach and get the important details right (like federation).

As before, I’m going to disagree for the need of this too :smiley: (I bet you love my interactions hehe)

I don’t see why repositories would not be actors themselves. In reality a repository will have many owners in larger projects. By saying “it must be owned by an actor” it’s going to be a huge limitation to a lot of projects. For example the Feneas projects would be impossible to place under one owner.

As for “which actor the repo is under”, I’d say just use the standard attributedTo. That is what it is for, no need for a new property imho.

For example (without contexts and a lot of other things):

  "id": "https://git.feneas.org/feneas/association",
  "type": "Repository",
  "attributedTo": "https://git.feneas.org/feneas",
  "name": "association",
  "summary": "Documents and management of the Federated Networks Association (Feneas)."

Then the repository has of course an inbox you can post into.

What are the reasons it can’t be simplified to this?

@criztovyl, thanks for the detailed comment :slight_smile:

@jaywink, there’s already use of preferredUsername and name at the same time. This makes sense for Person actors on Mastodon and the rest of the Fediverse. But there’s value in having an equivalent of preferredUsername for things that aren’t users, such as repos. For example your repo’s “username” could be “myproject” while the name is “My cool project that does magic”. The former can be used for repo search and auto-completion in UI. Technically we can use preferredUsername for this even for repos, but it’s very misleading because:

  1. It’s not a username, it’s a reponame
  2. It could end up getting in the way of WebFinger integration

So I’m proposing slug. In UI, you’d start typing e.g. “@linux-libre” and the search results would include both users whose username matches that string, and other things such as repos, whose slug matches that name. It would allow to search for repos, tickets, e.g. in a similar way to how people search for users.

I realize that UI is not federation, and that repo slugs probably aren’t needed for S2S logic, but:

  • ActivityPub has C2S too
  • I’m unsure about taking a minimalist approach, because it means that every case we haven’t thought of doesn’t get handled. WIth slug, namespace, etc. we have a chance to provide some generally useful properties and see how they get used, and remove them later if they end up not being needed. The spec does tell people how to represent things in JSON-LD and real forges do have UIs and people would need to pick a property to use. So I feel comfortable to give them answers. Removing late is much easier than adding late.

However, point taken: I won’t introduce slug and namespace before there’s some serious discussion about how actor search and WebFinger would work when there are multiple namespaces involved (which is the case for forges). Then we can have a clearer argument for their existence (or discard them).

managedBy: @jaywink, who said repos wouldn’t be actors? :slight_smile: repos should probably be actors, but there are smaller objects that probably won’t be. For example, tickets, ticket dependencies, patches, merge requests. And if you want to interact with those, managedBy tells you who the responsible actor is (for example, a ticket’s managedBy could be the repo actor to which the ticket belongs).

Here’s the current status:

  • slug: The uses of this are UI display (not critical right now) and WebFinger lookup (not critical right now). So for the first draft, slug will NOT be in the spec.
  • namespace: Not needed right now, will NOT be in first draft.
  • managedBy: So far no use in the spec, but it may be needed for S2S federation. If the need arises, I’ll comment here and we’ll see how to do it. @jaywink, you suggested to use attributedTo to state to which user/group a repo belongs, I have thoughts about this: attributedTo sounds kind of like “who created this object”, what if attributedTo also points to the actor who created the repo, and even to the Create activity? Now one can’t tell which of the attributedTo values is the one that says “repo belongs under this user”. Also, how about “to which repo a ticket belongs”, a ticket’s attributedTo is currently the user who opened the ticket. Either way, managedBy not needed right now, just challenging the use of attributedTo for this :slight_smile:
1 Like