Group Access, Scope and Types

open_groups.md

This is my overall assessment of what groups “mean” as an intersection of prose requirements and what the h backend app currently has in its code. Some (most?) of this may be rehash and may elicit the “yeah, right, we already know this” response, but if that happens, yay, we’re in alignment and if you think “gosh, this is wrong in some/all ways” that’s a good thing to identify, too.

Extreme tl;dr:

1. For open groups, Group resources need an additional constraint that defines what the set of valid URLs are for target documents that may be annotated within that group, and this is distinct from access or permissions. I am calling that constraint scope for shorthand, which may be a totally terrible name.
2. The list of “this user’s groups” is variable and depends on scope/context.
3. I’m not proposing a specific way to implement a scope constraint (yet, at least) in the data model

Vocabulary Interlude

I am going to use the following terms as defined here. Some of this may seem overtly pedantic, but I think the vocabulary alignment is critical so that we all know if/that we’re talking about the same things, so here is stuff for reference.

• application: For the context of this document, I’m talking about the h web service and backend, not the client, when I say “application”.
• authority: I promise this is the toughest term to define in this document. All Hypothesis users have an associated authority. In the simplest case (and the most common), this is Hypothesis itself—these users authenticate directly against Hypothesis. But for certain partners (most immediately-relevant: eLife), a third-party service “owns” the identity of the user and their actual credentials. That means that eLife users are in a different authority than Hypothesis-authority-Hypothesis users (though they are still Hypothesis users—a bit confusing, eh?). This term can be mind-muddling. It’s roughly a collection of users. It’s important to note that groups also have an associated authority, such that some groups may apply only to a certain authority’s users.
• creator: The user who created a group. Definitely relevant in the full picture of groups, but not touched on in this document.
• group: A resource. It is a container that holds annotations. A group resource currently has bits of metadata, if you will, that define who can see annotations in it, who can “join it” and who can write annotations to it. A group also has an associated authority.
• member and membership: In some, but not all cases, users are members of the groups in which they view and post annotations. Membership in a group, from the application’s perspective, equates to a relationship existing in the database between a user and a group. One can trip up on this term because there are some group types that do not require membership to act within them.
• moderator (used interchangeably with admin in the app code): A privileged user in a group who can act on the group, e.g. moderate annotations. Important concept in groups but not examined in this document.

Group Permissions

Group Types (described momentarily) are concepts that represent a combination of different individual permissions for a given group. While this is a somewhat of an implementation detail, it’s helpful to understand those individual permissions as their terms will pop up as we go further. The extant permissions for a given group include:

• Readable By: Who can see the annotations posted in this group. Possible values:
  • world: anyone, even those not logged in
  • authority: anyone who is logged in to the same authority as the group is associated with
• Writeable By: Who can put annotations into this group. You have to be logged in as someone to post content, so “world” is not a valid option here. Possible values:
  • authority: anyone who is logged in to the same authority as the group is associated with
  • members: only those who are actual members of the group
• Joinable By: Who can join the group. This is a little confusing because not all group types can be joined. Also note that this doesn’t take into account the notion of being invited to a group. Possible values:
  • authority: anyone who is logged in to the same authority as the group is associated with
  • None: This group is of a type that is not join-able (has no membership)

Group Types

What follows is a prose definition of each kind of group type I know about—those that exist already in some form of implementation in the app, those we are aiming to develop and some alternative terminology used.

• open group: A group whose annotations can be read by anyone in the world—even non-logged-in users. Users logged into a given authority can post annotations in any open group also within that authority. This type of group has not been implemented yet but is the focus of this examination.
• private group: The easiest kind of group to understand, and which has existed in Hypothesis for quite some time. A private group’s annotations can only be seen by its members. Only members may post annotations to private groups.
• publisher group: A hybrid, early-prototype variant of open groups, with some slight differences, created to support eLife. This is implemented in the application but may well not continue to exist as it was created to satisfy a unique user requirement.
• restricted group: A group whose annotations can be read by anyone in the world—even non-logged-in users. But to post annotations, a user must be logged into the group’s authority and a member of the group (notionally by invite, but the mechanism is not relevant at the moment). This type of group has not been implemented yet.
• public: Let’s not use this term because it’s confusing (it was previously a term used interchangeably with restricted group). But, for the record, the application code has its own opinion as to what public means: at the moment, the application considers any group that is world-readable to be “public”). Now let’s not talk about public anymore as it’s just going to confuse us. You won’t see it again here.

Group-Document Scope, or Something Like That

One of the tricky things about extending the groups model is that we keep banging up against notions of “control” or “visibility” or “when groups should show up” and related themes. In common-sense terms, a customer FooBar, Inc. may only want their open group(s) visible on their domain foobar.com. That seems straightforward enough at first blush: “only FooBar’s defined open groups on foobar.com,” right?

Right now, the backend application doesn’t care “where you are”—in a domain/URL sense—when you ask it for a list of relevant groups for the current user.

The reason that eLife’s open group(s) happen to show up on eLife’s own domain(s) (only) is a function of authority. eLife’s groups have eLife as their associated authority, and, well, the eLife authority only extends as far as their own domain(s). That is, a user can’t be logged into eLife outside of that anyway, so they don’t see the eLife group(s) outside of eLife. This is confusing because it seems like there is a domain association here, but there isn’t, technically.

But the open groups requirements do have such a notional domain restriction for groups themselves: regardless of authority association, open groups should only “show up” on a defined set of pages (or a domain, if you want).

To better define “show up”, that is: be one of the listed available groups in the Hypothesis client that annotations can be viewed within or added to, i.e. shows up in the Groups Menu [1].

Right now, the client asks the API “what groups are available to this user (in this authority)[2]?” To be able to satisfy the open groups requirement, however, the client needs to ask the API “what groups are available or applicable for this user (in this authority) for this target document?” That is, the applicable groups depend on the URL of the document being annotated as well as the who the user is.

But not always! The target document is relevant when we want the right list of groups for a user who is using a client to annotate, but notsomuch when a user is visiting pages on h’s web service.

Say a user visits their activity page. There the correct answer to “what are this user’s groups?” is some sort of combination of groups in which that user is a member and non-membership groups in which that user has had activity. Confused yet? The salient point here is that the document/domain restrictions for an open group don’t apply here (this is my interpretation, anyway). Here, as well as in search results, is where the notion of the Readable By permission is more clearly articulated. As I understand the vision, in the future a user should be able to see their annotations across all groups in which they are a member of or have contributed to[3].

OK, blah blah blah, what I’m getting with a lot of words already at is a notion that a bunch of us on the dev team have already landed on: the idea that a group resource is going to need an additional bit of metadata to satisfy the “this group should show up on x, y and z domains” requirement. Just with a slightly different emphasis because I think:

• Though this scope constraint would be an attribute on the group itself, it is really about documents associated with annotations in the group—it constrains what set of URLs [4] are valid documents to be annotated within the group at hand. Groups can “show up” outside of their URL/domain restrictions, like on activity pages and the like, but only documents within their scope should be allowed to be annotated.
• Talking about this helps us not overload the “readable by” permission, which was, in requirements matrices, conflating “readable by” with this document scope notion I’m getting at.

I don’t know the right term for this constraint yet. I’ve bandied around in my head: scope, context, applies to. I tend to resist domain for a few reasons: we’re already using that term elsewhere to mean something else; there may be multiple domains for a given group; this constraint could apply to more-specific-than-domain-level URLs (e.g. foo.com/baz).

Open and Restricted Groups Technically have Sub-Types

Looking forward at future enhancements to groups, there’s a notion that any user of Hypothesis should be able to create and manage their own open and restricted groups. It’s my hunch, however, that these groups would not have a document-scope constraint — that notion is reserved for “privileged” Hypothesis users and partners, as I understand it. Thus, I have included in my matrix here

OK, Enough Words, How about a Table?

Oh, jeez, you say, yet another matrix?! In this table, I attempt to bring requirements matrices from various requirement docs into alignment with the technical underpinnings of the application and how I interpret things.

…	Private Group	Publisher Group	Scoped Open Group	Scoped Restricted Group	Global Open Group	Global Restricted Group
Briefly...	The original group type we know and love	Prototyped for eLife	What we're building now	What we'll build soon	Future: Open Groups created by any user	Future: Restricted Groups created by any user
Annotations in this kind of group can be read by...	members	anybody	anybody	anybody	anybody	anybody
Annotations in this kind of group can be created by...	members	users in the same authority	users in the same authority	members	users in the same authority[]	users in the same authority?
Who can join this type of group?	users in the same authority	nobody	nobody	users in the same authority	nobody	users in the same authority
Who can create this type of group?	any user	specific partner (eLife)	privileged partner (publisher, e.g.)	privileged partner (publisher, e.g.)	any user	any user
Is this group type "scoped" to a particular set of document URLs?	nope	nope	yep	yep	nope	nope

Note:

• anybody means anybody—even people not logged in
• nobody can join certain types of groups because “membership” doesn’t apply to all types of groups
• The “who can create” values are fairly conjectural

[1]: How to deal with read-only groups is beyond the scope of this document.

[2]: authority can be derived from the user, so it’s implied in the question

[3]: I am ignoring the complexity of cross-authority stuff here, which could be really challenging.

[4]: And yes, though I initially worried that a strictly URL/domain-based “scope” restriction for groups was perhaps too specific, the fact that document targets are identified by URL makes this seem more fine

I like the idea that a group's scope constraint functions to constrain both what documents can be annotated in this group and what pages the group will appear in the groups menu on. Does the scope constraint belong on the group, though? Or is that actually a property of the publisher or organization that owns the group? It can go on the group at first, of course, until we actually have "publishers" or "organizations" as domain model entities, but in the longer term? I guess if it might ever be the case that a single publisher/community/organization might want to own different groups with different scopes, then the scope does belong on the group rather than on the publisher/community/organization. So I think I might have talked my way around to putting scope on groups as you've said.

Re your matrix of group types: private group, publisher group, scoped open group, scoped restricted group, global open group, global restricted group. I think the thing about scoped open groups is that they're not only scoped, they also belong to a publisher. In later mockups (but not much later, this story is likely coming up quite soon) these groups are grouped by publisher in the groups menu:

In future (not on any card or rqmnts yet)we might also want to support browsing groups by publisher on activity pages, or at least showing the publisher's name and icon on the group's activity page or next to the groups annotations etc.

So, I wonder if publisher open group, publisher restricted group, community open group, and community restricted group might be better names? Where publisher open group is meant to denote that it both belongs to a publisher and is scoped to that publisher's domain(s). And "communities" are meant to be understood as organizations not scoped to a domain.

Or maybe we actually need "scoped publisher open group" and "global publisher open group" :( (i.e. maybe being scoped and belonging to a publisher or community or organization are two separate properties)

Good point about activity pages. As well as the groups menu in the client:

there's also a groups menu in the top right of activity pages:

We're always focusing too narrowly on the client's UI when designing Hypothesis features, in my opinion, and not enough on the Hypothesis platform as a whole (including the h web app, via, bouncer, ...). So the way these publisher-associated scoped open groups will work is that they appear in the groups menu in the client whenever the client is on the publisher's site. But how are they gonna work in activity pages?

If I go to the publisher's site and open the client then I can click on a link in the client UI that'll take me to the activity page for the open group. Fine. But how can I navigate to open groups from within the h web app itself, without always having to go via the client? If I go to an open group's activity page via the client, and then by clicking links on the activity page I end up on some other activity page, how can I navigate back to the open group's activity page?

We can't just show all the open groups in the groups menu on activity pages because there'd be too many of them.

P.S. This same argument about over-focusing on the client also goes for other future features.

For example: multiple account support. We have mockups showing how we'll add stuff to the client's UI so that you can log in to and out of multiple accounts and annotation services, and see groups from multiple accounts:

But how is this all going to function no activity pages? I hope we're not going to be adding multiple account or multiple annotation service support to the client, because that would mean that all my groups and annotations etc from those other accounts would not appear at all on activity pages. (Not to mention that waiting around for the client to retrieve my group lists from half a dozen different servers every time I launch it sounds fun.) I think that support should instead be added to h, and the client should get them via h (h would aggregate stuff from multiple accounts for the client).

@seanh

We can't just show all the open groups in the groups menu on activity pages because there'd be too many of them.

I had envisioned the activity page for a user showing these groups:

• Any group they are actual a member of (private groups, at present)
• Any non-membership group (open, e.g.) that they have participated in (i.e. put annotations into)

Would that list still be too long?

(I think "discoverability" overall for open groups is important, something to think about in future sprints.)

I had envisioned the activity page for a user showing these groups:

Any group they are actual a member of (private groups, at present)
Any non-membership group (open, e.g.) that they have participated in (i.e. put annotations into)

Would that list still be too long?

Dunno if it'd be too long. I think just adding in open groups that you've participated in might be a good intermediate step. In the longer term I would guess:

• Users might want to remove groups from their activity pages groups menu. Just because I annotated in it once, may not mean I want it in my menu forever.
• Users might want to add groups into their menu without having to annotate in them. Groups that I'm interested in reading but don't write in (may not even have permission to write in, once restricted groups exist)

I think there's also a separate question of discoverability of the groups themselves in the first place - how do I discover that interesting open or restricted groups that I might want to read or participate in even exist? We can sidestep that one and just let people discover groups outside of Hypothesis, e.g. they see them on publisher's sites, or people tweet, blog, email links to their groups. But I guess one day we'll want some in-app (by app I mean probably h not the client) way of discovering groups.

In fact, we probably want a better in-app way of discovering interesting annotations (or interesting annotated documents) altogether. https://hypothes.is/search is our story for that right now but it doesn't do a very good job. (All you get is a list of most recently annotated documents across all of Hypothesis, and if you know what to search for then you can find stuff by searching. You can also browse by clicking on the users, tags and groups of the annotations you happen to see, but I'm not sure how effective that is for discoverability.)

The types of groups that we are building here are simple:

• Open Groups
• Restricted Groups
  Anyone of the groups can be Publisher groups if they are declared authoritative over their domain.

I think we need to remember that this gist is a rumination by Lyza on how things might go together - as Lyza mentioned here: https://hypothes-is.slack.com/archives/C4K6M7P5E/p1517072651000160, these notes are not a specification, and the work that will be implemented for a first pass is outlined here: hypothesis/product-backlog#417

The groups structure that we are working to implement is outlined here: https://github.com/hypothesis/product-backlog/wiki/Groups-Structure (this is the same structure that was drafted in the original Groups MVP document - I've just moved it to Github). Screenshot below. If anyone has questions on this, please ask me.