Fedify

Appearance

Pragmatics ​

NOTE

This section is a work in progress. Contributions are welcome.

While Fedify provides vocabulary API, it does not inherently define how to utilize those vocabularies. ActivityPub implementations like Mastodon and Misskey already have de facto norms for how to use them, which you should follow to get the desired results.

For example, you need to know which properties on a Person object should be populated with which values to display an avatar or header image, which property represents a date joined, and so on.

In this section, we will explain the pragmatic aspects of using Fedify, such as how to utilize the vocabulary API and the de facto norms of ActivityPub implementations.

Actors ​

The following five types of actors represent entities that can perform activities in ActivityPub:

  • Application describes a software application.
  • Group represents a formal or informal collective of actors.
  • Organization represents an organization.
  • Person represents an individual person.
  • Service represents a service of any kind.

The most common type of actor is Person, which represents an individual user. When you register an actor dispatcher, you should return an actor object of an appropriate type of the account.

Those five types of actors have the same set of properties, e.g., name, preferredUsername, summary, and published.

Application/Service: Automated/bot actors ​

If an actor is represented as an Application or Service object, it is considered an automated actor by Mastodon and a bot actor by Misskey.

typescript
new Application({  
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  // Other properties...
})

For example, the above actor object is displayed as an automated actor in Mastodon like the following:

Screenshot: An automated actor in Mastodon

Group ​

If an actor is represented as a Group object, it is considered a group actor by Mastodon.

typescript
new Group({  
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  // Other properties...
})

For example, the above actor object is displayed as a group actor in Mastodon like the following:

Screenshot: A group actor in Mastodon

TIP

Lemmy communities and Guppe groups are also represented as Group objects.

name: Display name ​

The name property is used as a display name in Mastodon and the most ActivityPub implementations. The display name is usually a full name or a nickname of a person, or a title of a group or an organization. It is displayed in the profile page of an actor and the timeline.

typescript
new Person({
  name: "Fedify Demo",  
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with display name Fedify Demo in Mastodon

summary: Bio ​

The summary property is used as a bio in Mastodon and the most ActivityPub implementations. The bio is displayed in the profile page of the actor.

NOTE

The summary property expects an HTML string, so you should escape HTML entities if it contains characters like <, >, and &.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",  
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a bio in Mastodon

published: Date joined ​

The published property is used as a date joined in Mastodon and Misskey. The date joined is displayed in the profile page of the actor.

NOTE

Although the published property contains a date and time, it is displayed as a date only in Mastodon and Misskey. However, there may be ActivityPub implementations that display the date and time.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  published: Temporal.Instant.from("2024-03-31T00:00:00Z"), 
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a date joined in Mastodon

icon: Avatar image ​

The icon property is used as an avatar image in Mastodon and the most ActivityPub implementations. The avatar image is displayed next to the name of the actor in the profile page and the timeline.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  icon: new Image({
    url: new URL("https://i.imgur.com/CUBXuVX.jpeg"),
    mediaType: "image/jpeg",
  }),
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a cat avatar image in Mastodon

image: Header image ​

The image property is used as a header image in Mastodon and Misskey. The header image is displayed on the top of the profile page.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  image: new Image({
    url: new URL("https://i.imgur.com/yEZ0EEw.jpeg"),
    mediaType: "image/jpeg",
  }),
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a cat header image in Mastodon

attachments: Custom fields ​

The attachments property is used as custom fields in Mastodon and Misskey. The custom fields are displayed as a table in the profile page.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  attachments: [
    new PropertyValue({
      name: "Location",
      value: "Seoul, South Korea",
    }),
    new PropertyValue({
      name: "Pronoun",
      value: "they/them",
    }),
    new PropertyValue({
      name: "Website",
      value: '<a href="https://fedify.dev/">fedify.dev</a>'
    }),
  ],
  // Other properties...
})

NOTE

The PropertyValue.value property expects an HTML string, so you should escape HTML entities if it contains characters like <, >, and &.

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with custom fields in Mastodon

manuallyApprovesFollowers: Lock account ​

The manuallyApprovesFollowers property is used to indicate that the actor manually approves followers. In Mastodon and Misskey, the actor is displayed as a locked account if the manuallyApprovesFollowers property is true.

WARNING

The manuallyApprovesFollowers property only indicates that the actor manually approves followers. The actual behavior of the actor is determined by the inbox listener for Follow activities. If it automatically sends Accept activities right after receiving Follow, the actor behaves as an unlocked account. If it sends Accept when the owner explicitly clicks the Accept button, the actor behaves as a locked account.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  manuallyApprovesFollowers: true,  
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a lock icon next to the handle in Mastodon

suspended ​

The suspended property is used to suspend an actor in Mastodon. If the suspended property is true, the profile page of the actor is displayed as suspended.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  suspended: true,  
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a suspended status in Mastodon

memorial ​

The memorial property is used to memorialize an actor in Mastodon. If the memorial property is true, the profile page of the actor is displayed as memorialized.

typescript
new Person({
  name: "Fedify Demo",
  preferredUsername: "demo",
  summary: "This is a Fedify Demo account",
  memorial: true,  
  // Other properties...
})

For example, the above actor object is displayed like the following in Mastodon:

Screenshot: An actor profile with a memorialized status in Mastodon

Federation.setFollowingDispatcher(): Following collection ​

The Federation.setFollowingDispatcher() method registers a dispatcher for the collection of actors that the actor follows. The number of the collection is displayed in the profile page of the actor. Each item in the collection is a URI of the actor that the actor follows, or an actor object itself.

typescript
federation
  .setFollowingDispatcher(
    "/users/{handle}/following", async (ctx, handle, cursor) => {
      // Loads the list of actors that the actor follows...
      return {
        items: [
          new URL("..."),
          new URL("..."),
          // ...
        ]
      };
    }
  )
  .setCounter((ctx, handle) => 123);

For example, the above following collection is displayed like the below in Mastodon:

Screenshot: An actor profile with 123 following in Mastodon

NOTE

Mastodon does not display the following collection of a remote actor, but other ActivityPub implementations may display it.

Federation.setFollowersDispatcher(): Followers collection ​

The Federation.setFollowersDispatcher() method registers a dispatcher for the collection of actors that follow the actor. The number of the collection is displayed in the profile page of the actor. Each item in the collection is a URI of the actor that follows the actor, or an actor object itself.

typescript
federation
  .setFollowersDispatcher(
    "/users/{handle}/followers", async (ctx, handle, cursor) => {
      // Loads the list of actors that follow the actor...
      return {
        items: [
          new URL("..."),
          new URL("..."),
          // ...
        ]
      };
    }
  )
  .setCounter((ctx, handle) => 456);

For example, the above followers collection is displayed like the below in Mastodon:

Screenshot: An actor profile with 456 followers in Mastodon

NOTE

Mastodon does not display the followers collection of a remote actor, but other ActivityPub implementations may display it.