search

pixelfed / starter-kits

Pixelfed Starter Kits provide a simple and easy way for new accounts to automatically apply a curated set of actions and settings to enhance their initial experience.
6 stars 0 forks source link

Schema #1

Open dansup opened 1 day ago

dansup commented 1 day ago

StarterKit Extension Documentation

Specification

Base Structure

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Collection",
  "id": "https://example.org/recommendations/category-name",
  "name": "Human Readable Name",
  "summary": "Description of these recommendations",
  "totalItems": 0,
  "items": []
}

Properties

Property Type Required Description
@context string Yes Should contain "https://www.w3.org/ns/activitystreams"
type string Yes Must be "Collection" or "OrderedCollection"
id string Yes Unique URI identifying the collection
name string No Human-readable name of the collection
summary string No Description of the collection's purpose
totalItems number Yes Total number of items in the collection
items array Yes Array of Person and Hashtag objects
published string No ISO 8601 timestamp of creation
updated string No ISO 8601 timestamp of last update

Item Types

The items array can contain two types of objects:

Person Objects

{
  "type": "Person",
  "id": "https://example.org/users/username",
  "name": "Display Name"
}
Property Type Required Description
type string Yes Must be "Person"
id string Yes ActivityPub ID of the account
name string Yes Display name of the account

Hashtag Objects

{
  "type": "Hashtag",
  "id": "https://example.org/tags/tagname",
  "name": "#tagname"
}
Property Type Required Description
type string Yes Must be "Hashtag"
id string Yes URI identifying the hashtag
name string Yes Hashtag string (must include '#' prefix)

Example Activity

{
  "@context": "https://www.w3.org/ns/activitystreams",
  "type": "Collection",
  "id": "https://pixelfed.social/starter-kit/1",
  "name": "Photography Recommendations",
  "summary": "Recommended follows for photography enthusiasts",
  "totalItems": 4,
  "items": [
    {
      "type": "Person",
      "id": "https://example.org/users/photographer1",
      "name": "Nature Photographer"
    },
    {
      "type": "Person",
      "id": "https://other.org/users/photographer2",
      "name": "Street Photography"
    },
    {
      "type": "Hashtag",
      "id": "https://example.org/tags/photography",
      "name": "#photography"
    },
    {
      "type": "Hashtag",
      "id": "https://example.org/tags/naturephotography",
      "name": "#naturephotography"
    }
  ]
}
ThisIsMissEm commented 1 day ago

Hashtags should probably use the as:Hashtag object type.

dansup commented 1 day ago

Hashtags should probably use the as:Hashtag object type.

Good catch, updated!

ThisIsMissEm commented 1 day ago

I don't think Collection is correct at the top level here, instead it's the "follow recommendations" that are the collection.

i also don't think "auto follow" is necessarily a good idea, I'd think of these more as recommendations where you can choose to follow some of the accounts or all, ditto with following hashtags.

Finally, I don't think "auto blocking" belongs in starter kits, but in a separate system, nor account privacy/reach settings, since it'd be difficult to map this accurately across different fediverse software.

ThisIsMissEm commented 1 day ago

Also, the Collection can be mixed typed, i.e., one collection can include both Person/Group actors and Hashtags, it's then up to software to choose how to display the collection, whether as a simple list or as separated out by object type.

Additionally, a starter pack for the Fediverse should almost certainly recommend instances that a new person may want to join. (Gosh I wish we had an Instance/Server object type)

ThisIsMissEm commented 1 day ago

The current structure here of everything sorted out by Object type means that you cannot reuse the Collection pagination logic

dansup commented 1 day ago

The current structure here of everything sorted out by Object type means that you cannot reuse the Collection pagination logic

Good point, I've updated it, let me know what you think!

ThisIsMissEm commented 1 day ago

To further expand on this:

Finally, I don't think "auto blocking" belongs in starter kits, but in a separate system, nor account privacy/reach settings, since it'd be difficult to map this accurately across different fediverse software.

I think Starter Packs are fundamentally different to Safety Packs, the former helps you get started somewhere and follow a bunch of people. The latter is after you have an account, though may be recommended by the former.

In a Starter Pack it's a one-time type of deal, not a subscription to a list of people to follow, where as for Safety Packs, that's an ongoing and evolving need, safety doesn't just happen once, it continues to happen constantly. Special care also needs to be taken to make sure retractions happen correctly (which I think are likely beyond the Add / Remove semantics of Collections). I do think Safety Packs could be built off the ideas I put fourth in the background information for my FIRES project.

ThisIsMissEm commented 1 day ago

The current structure here of everything sorted out by Object type means that you cannot reuse the Collection pagination logic

Good point, I've updated it, let me know what you think!

For hashtags, I'd omit the id since hashtags occupy a global namespace, and it generally isn't possible to subscribe to a specific hashtag on a specific server at present.

ThisIsMissEm commented 1 day ago

For Actors, you probably also want to include some additional properties, e.g., url, preferredUsername and probably a handle (though handle needs to be defined — there was that FEP that was going from Actor to Webfinger acct, maybe that has a property to use?)

jfietkau commented 21 hours ago

Hey Dan, good stuff, thanks for putting something forward.

If I'm understanding your concept correctly, it's intended to offer a starter kit specific to each ActivityPub server, and it's either auto-applied or suggested to new users when they create an account on that server.

The past few weeks I've been discussing a version of ActivityPub starter packs with various people that has more flexible interaction modes: being created and shared by users, giving people the option to mention a starter pack in a post so clients can show specific UI for it (mainly a "follow all" button but also ways to explore the contents of the starter pack), and established accounts on different servers being able and encouraged to use and share starter packs from around the fediverse.

I'm personally a fan of the idea to build starter packs that can be used backwards-compatibly by people on current versions of AP platforms without specific starter pack support, by implementing starter packs as "boost bots" (actors of type Service) which follow all the accounts in the starter pack and boost their public posts. That way, people on older versions can follow the starter pack like a regular account and get its contents that way, while people on newer versions with specific support for starter packs can get a better UI with a "follow all" button to establish follow relationships that don't go through the bot account. (We'd probably want to establish some custom property that allows servers and clients to distinguish starter pack service actors from other bots.) Relating it to your concept, the starter pack collection would be the actor's following collection, although this would be unable to contain hashtags.

My design notes can be found here. I'm told Newsmast has a version of starter packs planned that matches my concept fairly closely. Neither of us have started a proper implementation yet.

Do you think it's possible to adapt your spec to fit these additional ideas too, or are the concepts too different?

Some relevant discussion threads I participated in:

  1. https://ruby.social/@getajobmike/113442936451176472 (This one contains input from the Mastodon team.)
  2. https://windbag.org/@adam/113445644571384633
michael-patchwork commented 20 hours ago

Great to see this created! Two really good ideas here - server specific packs, and ones which replicate the Bluesky experience, where they have been very successful, passed around independent of servers. We have boost bot tech as @jfietkau mentions which could be repurposed for this. We’re just finishing an application of this approach to Fediverse custom feeds. Not underway yet on starter packs - just joining the discussion at the moment

trwnh commented 15 hours ago

@context | string | Required | Must be "https://www.w3.org/ns/activitystreams"

why? the @context may be different if there are extension properties, and also @context shouldn't be considered at all if you aren't doing LD processing. in other words, DO NOT ATTEMPT TO VALIDATE @context -- you are only introducing bugs!

type | string | Required | Must be "Collection"

name | string | Not required | Human-readable name of the collection totalItems | number | Required | Total number of items in the collection

why is the name not required, but the totalItems is?

The items array can contain two types of objects:

why?

type | string | Required | Must be "Person" name | string | Required | Display name of the account

type | string | Required | Must be "Hashtag" id | string | Required | URI identifying the hashtag

Example Activity

this isn't an activity, it's a Collection object

more generally

i see a lot of problems with this conceptually. the schema has problems, sure, but those can be fixed; what is far more important is that i don't see any protocol or behavioral considerations here:

there is a lot of thought that needs to be put into such a proposal before even getting to a schema, and unfortunately i'm not seeing any of it anywhere here.

ThisIsMissEm commented 14 hours ago

For as:Hashtag we should reference https://purl.archive.org/miscellany from https://swicg.github.io/miscellany/

if i start a new server then every single "hashtag recommendation" is useless without a source for additional data.

This is correct, but for a user using a starter pack to join an existing server, hashtag recommendations may make sense.

The items array can contain two types of objects:

why?

The items array can contain any Actor type and any as:Hashtag might be a better way to put it?

trwnh commented 9 hours ago

any Actor type

actors can be any type. just because mastodon restricts you to 5 types doesn't mean that everyone else has to use only those 5 types

shleeable commented 8 hours ago

I'd argue against requiring approval to add people to new packs, but they should be notified with a button to remove themselves on demand.

jfietkau commented 7 hours ago

I'd argue against requiring approval to add people to new packs, but they should be notified with a button to remove themselves on demand.

Generally speaking, for these "opt in or opt out" questions, I like to ask myself what is the kind way to treat people who have never heard of $thing and don't have time to investigate every new feature. We don't have an existing consent mechanism that matches starter packs exactly, but my feeling is that the discoverable flag should be taken into account when deciding whether it is okay to add someone to a starter pack.

I've been thinking something along these lines:

  1. discoverable flag set and account does not manually approve followers: can safely be added to starter pack
  2. something in between: ask before adding (Bridgy Fed style)
  3. discoverable flag not set and manually approves followers or #nobot in bio: do not attempt to add to starter pack

I've been planning to treat #nobot as a general opt-out since in my concept, each starter pack is a bot account. Maybe that doesn't apply if you're working purely with lists.

On top of that, notifying someone when they're added to a starter pack and giving the option to self-remove makes sense. Within the possibilities afforded by current implementations, someone blocking the actor that corresponds to the starter pack could be interpreted as "I want no part of this". It would be nice to have a way to say "allow all" and "deny all", but that's a bit harder unless all starter packs go through a central server.

Is this the right place to discuss this type of starter pack? If it's extremely out of scope for what Pixelfed starter kits are trying to accomplish, then I don't want to be rude about pushing this. But my impression is still that the schema would ultimately not be all that different and that it's worth avoiding having a handful of mutually incompatible types of ActivityPub starter packs with slightly different features.

goodevilgenius commented 2 hours ago

You have Collection as an example of an Activity. That's not really an Activity. Maybe use Create, instead.