From 2abb40a0caf729941a0de1f8f8c02cdcfbcc2372 Mon Sep 17 00:00:00 2001 From: dholms Date: Wed, 23 Sep 2026 17:14:51 -0500 Subject: [PATCH] split out readme & proposal --- README.md | 25 +++++++++++++++++++++++++ proposal.md | 48 ++++++++++++------------------------------------ 2 files changed, 37 insertions(+), 36 deletions(-) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..362eb07 --- /dev/null +++ b/README.md @@ -0,0 +1,25 @@ +# opensocial.group + +`opensocial.group` is a proposed standard for groups that share the same identity, presence, and data across multiple applications and modalities. These **atmospheric groups** may also have a web presence of their own. + +Because an atmospheric group spans applications, those applications need a shared understanding of what a group is and how to interact with it. `opensocial.group` provides that interface as a suite of lexicons describing space types, record types, and methods. + +The standard builds on the [permissioned data protocol](https://github.com/bluesky-social/proposals/tree/main/0016-permissioned-data), particularly its **spaces** primitive. The underlying protocol deliberately does not define application semantics; this proposal adds the concepts needed to model groups, including membership, roles, group presence, and moderation. + +The proposal focuses on three areas: + +- roles and access +- presence and discoverability +- moderation + +## Design Posture + +The standard defines the **interface between the group and the application**. In the same way that the permissioned data protocol ruthlessly avoids describing application semantics, the group standard should avoid describing both group governance and application semantics. This is not to underrate the importance of those, if anything it is to acknowledge just how important those are. By not standardizing them, we leave the freedom of implementation up to group stewards. + +The standard should be as **minimal as possible**. Standards like this are hard to change. By making this as minimal as possible (but no more minimal), we give the best chance for experimentation, growth, and applicability across many different groups. + +The standard should **target the 90% case.** Every group is different and some have bespoke or idiosyncratic needs. Reflecting all of those needs in the standard will increase complexity for all implementers. Instead, we target the 90% case. *Most* groups should be able to be modeled directly on the atmospheric group standard. If a group needs something more complicated, it can still do whatever it wants, and then project its backend state onto the group standard. + +## Read the proposal + +See [proposal.md](proposal.md) for the protocol model and the proposed spaces, records, actions, and methods. diff --git a/proposal.md b/proposal.md index 258b083..02a892e 100644 --- a/proposal.md +++ b/proposal.md @@ -1,30 +1,6 @@ # opensocial.group proposal -## Introduction - -An **atmospheric group** is a cross-modality, cross-app group that may have a web presence of its own as well. The “atmospheric” quality is that the same group identity, presence, and data is shared and remixed across these different applications. - -Because atmospheric groups span multiple applications, applications need to have a shared understanding of what a group is. In other words, they need a *standard* for interfacing with these groups. - -The [permissioned data protocol](https://github.com/bluesky-social/proposals/tree/main/0016-permissioned-data) gives us some of that, specifically **spaces** which is a new primitive that allows for the creation of essentially “mini permissioned atprotos”. However the protocol is very un-opinionated about their use. As such, it doesn’t include notions of membership, roles, group moderation, or application semantics. - -An atmospheric group standard then builds on the permissioned data protocol and introduces a suite of lexicons (spaces, records, and methods) for modeling groups on top of the new data protocol. - -There are three main pieces to this: - -* Roles & access -* Presence & discoverability -* Moderation - -## Design Posture - -The standard defines the **interface between the group and the application**. In the same way that the permissioned data protocol ruthlessly avoids describing application semantics, the group standard should avoid describing both group governance and application semantics. This is not to underrate the importance of those, if anything it is to acknowledge just how important those are. By not standardizing them, we leave the freedom of implementation up to group stewards. - -The standard should be as **minimal as possible**. Standards like this are hard to change. By making this as minimal as possible (but no more minimal), we give the best chance for experimentation, growth, and applicability across many different groups. - -The standard should **target the 90% case.** Every group is different and some have bespoke or idiosyncratic needs. Reflecting all of those needs in the standard will increase complexity for all implementers. Instead, we target the 90% case. *Most* groups should be able to be modeled directly on the atmospheric group standard. If a group needs something more complicated, it can still do whatever it wants, and then project its backend state onto the group standard. - -## Proposal +This document specifies the proposed `opensocial.group` model. See the [project README](README.md) for an overview, background, and design posture. An **atmospheric group** is a DID with a bunch of permissioned spaces under it. @@ -34,7 +10,7 @@ Groups run on `opensocial.group`\-compliant space hosts. These are servers that `opensocial.group` is a *peer* to the [simplespace implementation](https://github.com/bluesky-social/proposals/tree/main/0016-permissioned-data#required-pds-space-management-simplespace) that is required for PDSes to implement. It is not expected to operate on most PDSes and does not layer on top of simplespaces. -### The spaces +## The spaces There are two `opensocial.group` spaces: @@ -45,7 +21,7 @@ The `opensocial.group` spaces are specifically intended for records *about* the Rather, a group hosts an additional space for each application or modality. If a group wants to enable event applications, it might create a `group.lexicon.calendar.events` space. All `group.lexicon.*` records will then be published into this modality-specific space rather than into a universal “group” space. -### Roles & Access +## Roles & Access Authorization & access is modeled as flat RBAC (role-based access control). The group defines **many roles** and assigns one or more roles to each member. Each role gives access to a set of standardized actions. @@ -61,7 +37,7 @@ Each space in the group (both modality-specific spaces & `opensocial.group` spac All other types of access are considered **modality-specific** and as such are **app features.** Who can write to a space, who can pin a thread, who can post to an announcements channel, who can create an event, etc. Each of these are declared in the modality’s **own lexicon** within the relevant space. However, these authorization declarations may still make use of the group-defined roles. -### Writing as the Group DID +## Writing as the Group DID Certain modality-specific records need to be created *by the group DID*. For instance, pinning a post at the top of a forum may require a `pin` record created by the group DID in the forum space. @@ -73,7 +49,7 @@ The OAuth scopes that each user/role is able to request for the group DID are al Applications are in charge of juggling these credentials. They may choose to offer an “account switcher” where an admin switches to using the group account, or they may do this more transparently and just use the group account credential when the admin performs some action that requires it. -### Presence & Discoverability +## Presence & Discoverability Each group has a profile that it publishes in its `meta` space. This includes some basic metadata about the group such as a display name and a profile picture. It also includes records describing the rules of the group. @@ -83,7 +59,7 @@ Many groups will wish to make their `meta` space public, even if the rest of the Groups that wish to be easily discoverable may also publish a `declaration` record to the public broadcast protocol. This record simply includes a pointer to the public `meta` space for the group. -### Moderation +## Moderation Each group is also a **moderation service** with moderation authority over all content in the group. @@ -97,7 +73,7 @@ On top of this, a simple moderation information architecture is specified. In th Groups at scale may support significantly more complex moderation systems. However this will likely require bespoke group moderation software and wouldn’t be done through in-app flows. -### Invites +## Invites An invite is an interesting case because it must reach someone who isn’t yet a member and therefore does not necessarily have access to the group’s spaces. Invites usually should not be broadcast publicly. @@ -105,7 +81,7 @@ Instead, each user who is interested in receiving invites to groups hosts an `in Only the user (and authorized applications) may read the space. In other words, the inviting group writes the record but can’t read other invites in the space. -### Group governance +## Group governance The `opensocial.group` standard is intended for standardizing the interface between applications and groups. Therefore group governance is generally considered out of scope. @@ -113,7 +89,7 @@ A group may implement arbitrarily complex governance, including things like voti ## Spaces, records, and methods: at a glance -### **Space types** +### Space types | Space type | skey | Purpose | | ----- | ----- | ----- | @@ -122,7 +98,7 @@ A group may implement arbitrarily complex governance, including things like voti | `group.opensocial.invites` | `self` | Hosted by each **user**, not by groups. Where invites arrive. | | *(modality spaces)* | any | `com.atmoboards.forum`, `app.bsky.group`, etc. Not specified here. | -### **Record types** +### Record types | Record | Space | Author | Key | Purpose | | ----- | ----- | ----- | ----- | ----- | @@ -138,7 +114,7 @@ A group may implement arbitrarily complex governance, including things like voti | `group.opensocial.label` | any space | authority | tid | A moderation label, written into the space its subject lives in. | | `group.opensocial.invite` | invites | inviting group | tid | An invitation, delivered into the invitee's own space. | -### **Actions** +### Actions | Action | Governs | | ----- | ----- | @@ -155,7 +131,7 @@ A group may implement arbitrarily complex governance, including things like voti | `space.delete` | delete a space | | `group.configure` | edit the profile, rules, roles, and permissions | -### **Methods** +### Methods | Method | Requires | Purpose | | ----- | ----- | ----- | -- knotmirror 0.0.1