From the description, the requirement for groups is that only members of the group be able to see the annotation (and hence it's an access control issue).

#8 is explicitly not about access control, as raised by Irina and subsequently discussed and clarified at TPAC, which is recorded in the issue. Access control requires Authentication and Authorization, which we have resolved previously as out of scope, and on 2015-12-02 call decided to action chairs + staff contacts to find appropriate external advisors, per #19. You could have access control that allows only people in a group to see the annotations, but the audience be a different set. For example, an organization for the ACLs, and an audience of managers -- only people in the organization can see it, and although non-managers can see it, they're not the intended audience and hence may wish to filter it out.

There seemed to be agreement on that call that the model should not include access control lists, that access control was at best a protocol issue, which is reinforced by the description -- you publish/create an annotation, and then only certain users (in the group) can see/retrieve it.

So I propose that we do not accept the issue as stated:

• It is access control related, which has been discussed as being out of scope
• It is not a model issue
• It is orthogonal to #8

Hi Rob,

I'm having some trouble following the logic of how it is orthogonal to #8 . Access control requires Authentication and Authorization both of which require an "of what/who" question to be answered. The answer of the question easily overlaps with Audience.

Specifically, you propose that the group with access to an annotation will be different than the audience for that annotation. This may be true but only in cases where the set of entities with access contains the set of entities that are the audience. Otherwise it becomes a bit silly as the annotations will never be viewed by the intended audience.

Other than that nitpick I'm +1 for not accepting this issue:

• Agree that this is out of scope (but I also think #8 was out of scope so there may be a consistency of approach issue that needs to addressed)
• Agree that it is not an issue for the annotation model (this is some other modeling problem)
• Don't agree that is perfectly orthogonal to #8 (it's more like a bridge between #8 and #19 ).

Regards,

Jacob

P.S. I know we agreed to recommend schema:audience but should we provide a mapping between it and dc:audience for the community using the latter (i.e., does #8 need some additional text a la #18 's solution)?

I agree it's not completely disjoint. I think it is orthogonal, in that:

• Both audience and access control via membership in a group are possible at the same time. They could both be present, either could be present or neither. They could have the same value or different values, with different behaviors from each.
• Access Control is a protocol issue in that it is who is allowed to access (or manage) the resource, audience is a model issue in that it describes who might find the resource interesting or useful

Can you add the dc:audience equivalency to #8 please?

1. A "groups" feature is not only about authorization and access control (though that's a major part of it); there may be "open groups" that are more about distribution and default views (which could have overlaps with "audience"), and who can access an annotation, or who it's distributed to, may change over time. For example, one of my colleagues requested a feature in W3C's annotation service that would allow spec review annotations to be limited to the reviewing Working Group, so individuals could vet their impressions with other WG participants, then if the WG agreed, the annotation could have its viewability changed to "public", so everyone (including the spec's WG) could see the comment; this is a clear reflection of the overlap of audience and groups.

2. Access control is probably going to be implemented at the service level (e.g. on the server, or in some cases, in the client); but since this is a distributed system, there needs to be a way for each annotation to signal what group it's intended for. Any particular service (client or server) may handle the access control differently (or not handle it at all), but each annotation should have its own "group" property; it shouldn't only be a service-level detail left out of the annotation.

I see overlap between "audience" and "group", in a very functional way; I think they should be handled the same, since the overlapping cases are obvious and we should prefer general capabilities over specific ones, where possible. But even if that notion is rejected, there should still be a way to express a target "group" in an annotation and a collection of annotations (and maybe in the protocol).

To be honest, I am a little bit lost in this discussion.

We agreed to use the schema.org/Audience class. It has a bunch of subclasses defined by schema.org, these can (and I presume will) evolve in future but, luckily, we do not manage those changes. But already at this point, the Audience class[1] is pretty open to be used for many different things; and instance can use the audienceType property whose value is any text, and that can be used to model any collection of users, a.k.a. groups in this sense. What this tells me is that the non-authorization and non-access-control aspect of a group can be modeled by Audience, ie, by what we have accepted to use. That part is done.

We also agreed that authorization and access control is out of scope in the model, and mostly out of scope for the Working Group altogether.

Bottom line: I do not know what we are missing and what we are really discussing. My feeling is that there is simply no issue to solve here.

[1] https://schema.org/Audience

@iherman When we add a feature, we need to know what the requirements are, so we can make sure it has the right characteristics. My expectation is that this will be pretty simple, and I'd like Hypothes.is and others who have implemented a "groups" feature to let us know what is needed.

While I agree that we shouldn't define the details of authorization and access control, if we want interoperability, we may wish to add a normative requirement that a UA SHOULD honor a stated restriction, whether that is group or some other well-defined "audience" (I can imagine that students might not have access to instructor annotations on a textbook, for example).

To be clear, I'm not suggesting we define those access-restricted categories, just that we enable communities to do so.

@iherman https://github.com/iherman When we add a feature, we need to know what the requirements are, so we can make sure it has the right characteristics. My expectation is that this will be pretty simple, and I'd like Hypothes.is and others who have implemented a "groups" feature to let us know what is needed.

Well, I do not know what this feature is, in fact (apart from what can already be modeled with the Audience, as I said in my previous reply). I still do not know what we are really discussing.
While I agree that we shouldn't define the details of authorization and access control, if we want interoperability, we may wish to add a normative requirement that a UA SHOULD honor a stated restriction, whether that is group or some other well-defined "audience" (I can imagine that students might not have access to instructor annotations on a textbook, for example).

I think this falls under the resolution we decided for issue #19

A Group may be the agent that creates an annotation. As has been discussed Groups can have a role in authorization and access control (which in my mind is quite distinct from audience role). And of course a Group may be the target audience of an annotation. Clearly Groups are complex and in the annotation ecosystem will play more roles than just that of audience. Since we are primarily concerned with annotations, not groups, I think it best to avoid as much as possible the temptation of offering our own new ontology for describing Groups in common roles (audience, author, access control). Such semantics (mostly at least) exist. When modeling annotations it seems better to point to existing semantics adequate for describing a Group in the context of a particular annotation.

The schema.org audience property and Audience class is generally adequate as is to describe a Group as the audience of an annotation, allowing annotation authors to point to a further description of a Group when needed, and as necessary allows communities to offer their own extended models of audience-related attributes of a Group. Using schema.org annotation agents can name the Group that is the target of an annotation (schema:audienceType), and for certain existing sub-types of Audience (e.g., PeopleAudience), annotation agents can provide additional audience-relevant attributes of the Group, e.g., gender, min. age, max age. And of course through schema:url, schema:sameAs, additional rdfa typeOf, annotation creators can link to further information about a Group relevant to its other (non-audience) roles in the annotation ecosystem.

So I would agree that this issue is orthogonal to #8.

I cede to @nickstenning here who the technical insight from our perspective.

And to be clear my comment earlier in this thread about the sufficiency of schema:audience and schema:Audience and about the orthogonality of this issue to #8 was in regard specifically to how we talk in an annotation about groups having the role of target audience for an annotation. While semantics also do exist for talking about groups in roles other than audience, there could be a need to come up with additional keys and objects to support a level of functionality and interoperability we deem essential for annotations having groups fulfilling other roles. Just as long as we are careful not to reinvent the wheel in the process and as long as we don't get monolithic about how groups mentioned in annotations are described.

@shepazu your quote from earlier contains access control language (emphasis added):

we may wish to add a normative requirement that a UA SHOULD honor a stated restriction,
whether that is group or some other well-defined "audience" (I can
imagine that students might not have access to instructor annotations
on a textbook, for example).

If we were to add such a normative requirement, it should not be at the UA level, but at the protocol level--which I think has been said a few times now...

Consequently, if we reword this issue and document requirements for groups as a thing in relation to the protocol doc, then I think we can get back on track.

@BigBlueHat Why should groups (or even access control) only be done via the protocol? What about annotations that are stored locally, or exchanged offline, or otherwise not accessed via the protocol (which not every UA may use)? How is a client supposed to know how to treat those, if there's no property contained in the annotation itself?

it should not be at the UA level, but at the protocol level--
which I think has been said a few times now

It's true that several people have that opinion. I am not yet convinced that a related property shouldn't be in the model, as well, and I've stated the technical reasons why.

Saying "some people agree with me" doesn't tell us tell us the technical rationale.

@tcole said:

The schema.org audience property and Audience class is generally adequate as is to describe a Group as the audience of an annotation, allowing annotation authors to point to a further description of a Group when needed, and as necessary allows communities to offer their own extended models of audience-related attributes of a Group. Using schema.org annotation agents can name the Group that is the target of an annotation (schema:audienceType), and for certain existing sub-types of Audience (e.g., PeopleAudience), annotation agents can provide additional audience-relevant attributes of the Group, e.g., gender, min. age, max age. And of course through schema:url, schema:sameAs, additional rdfa typeOf, annotation creators can link to further information about a Group relevant to its other (non-audience) roles in the annotation ecosystem.

This seems to reinforce what I claimed:

We agreed to use the schema.org/Audience class. It has a bunch of subclasses defined by schema.org[…] an instance can use the audienceType property whose value is any text, and that can be used to model any collection of users, a.k.a. groups in this sense. What this tells me is that the non-authorization and non-access-control aspect of a group can be modeled by Audience, ie, by what we have accepted to use. That part is done.

And I keep to my opinion: that is covered, and we should not introduce a new concept for a "group" in our terminology and into our model. My proposal is to close down that aspect of the issue.

(As @tcole said, there may be a more complex concept of a group, but I would object to get into a complex set of description to characterize those entities; I am not even sure what would really be what we described. Leave that for either future releases or for other groups (sic!) out there.)

On the "authorization" aspect, @shepazu also said:

[…] if we want interoperability, we may wish to add a normative requirement that a UA SHOULD honor a stated restriction, whether that is group or some other well-defined "audience" (I can imagine that students might not have access to instructor annotations on a textbook, for example).

and also added:

To be clear, I'm not suggesting we define those access-restricted categories, just that we enable communities to do so

The way I read these lines is to add something saying:

“User Agents should honor any access restrictions that may be specified for a given audience, although this specification does not define how to express those access restrictions.”

(or something similar after suitable wordsmithing.)

I am fine with such a statement being added which probably reflects what we all think (and covers the example @shepazu gave). This can be added to the text about audiences (as a note, for example, not to disrupt that flow of the text).

This may allow to close this issue and move on.

This is a tricky topic, so let's not be surprised that there's miscommunication going on. As has already pointed out elsewhere, "groups" is a heavily overloaded word, so let's try and be clear about what we want to achieve.

Sometimes you want to have an annotation published only to a particular group, and you may wish to let only those people see it.

As written, this is absolutely an access control requirement. You want the ability to give certain collections of people/machines/whatever the ability to perform certain actions on certain resources. To my mind this doesn't place any requirements on the model, but it does (as @BigBlueHat) and others have suggested, have implications for the protocol.

@BigBlueHat and @azaroth42: are you imagining that "containers" will be one important unit of access control granularity? That is, a container could represent a group's annotations, and I will be able to see and/or modify specific containers dependent on membership of that group?

What about annotations that are stored locally, or exchanged offline, or otherwise not accessed via the protocol (which not every UA may use)? How is a client supposed to know how to treat those, if there's no property contained in the annotation itself?

If I have the serialised content of an annotation, no matter how I received it, then by definition I have the ability to view the abstract entity represented by that data. Trying to enforce anything else through model properties doesn't make any sense. They're just bits on a computer I control...

If I have the serialised content of an annotation, but no idea where it lives in an annotation store, then I'm not sure what it even means to ask "do I have permission to edit this annotation"? Again, it's just some bits on a computer I control. I can edit them, but that's not "editing" in any meaningful sense. Without an annotation service (even a private one for my own use) I can't republish those edits.

So, overall, I think yes, this is an access control issue.

But, there is one important aspect in which I think this does touch on the model, and I suspect that @shepazu may be thinking in these terms. A potential user interface for annotating:

1. May need to be able to signal to a user that an annotation comes from a particular group.
2. May need to know whether a user can create annotations in the group in order to correctly display or hide editing controls.
3. May need to know what permissions the user has on specific annotations within the group as a result of a role conferred within that group (such as "moderator", "administrator", "teacher", etc.)

It's not immediately clear to me that any of these considerations place hard requirements on the model, as all of them could in principle be achieved by other means (the client maintains state about where each annotation came from, and identity/permissions information also could come from elsewhere). But I think there is one very important scenario that we're not yet really considering: federation.

If a client retrieves an annotation from its "canonical" data store (whatever that means) then I can maintain state about where it came from and who's allowed to do what with it.

But what if a client retrieves an annotation from a data store which is republishing that annotation? What if a client retrieves annotations through an "aggregator" API that exposes annotations from multiple underlying containers through one set of endpoints?

AIUI there is at the moment no support in the model for specifying the provenance of such annotations, or for including any kind of reference to where changes to such annotations need to be submitted (because I would guess the answer would probably not be "back to the aggregator").

In summary, then:

• There is an access control component to this which (IMO) doesn't/shouldn't form part of the model.
• There are, however, considerations around display which fundamentally boil down to support within the model for discovering an annotation's provenance. Perhaps we should open an issue to discuss this if we don't have one already?
• I don't think the "audience" field discussed in #8 has anything to do with groups. It seems to me that independent of any discussion of groups, an "audience" field for hinting display intent to a potential user agent is a useful thing to pursue.

Good thoughts, @nickstenning. I'll reply to most of them here, but for this specific issue, I think we should:

1. accept @iherman's proposed text (or something based on it)
2. close this particular issue
3. move this conversation to the mailing list where it's a better fit--as we're not directly "solving for X" here, we're discussing what could be, etc.

Once we have some action items out of further discussions, we can certainly create those here as issues and come to consensus and act on them.

So, to that end, let's move the conversation to the list (please):
https://lists.w3.org/Archives/Public/public-annotation/

@nickstenning oh. Forgot this bit. In response to:

There are, however, considerations around display which fundamentally boil down to support within the model for discovering an annotation's provenance. Perhaps we should open an issue to discuss this if we don't have one already?

Check out these issues:

• #19
• #115
• #111
• #96

They all in some way touch on provenance, federation, and distributed annotation.

(For completeness of the discussion, see also the mail of Lutz Suhrbier on the mailing list)

1. I don't think that we really need to model groups, but I think that the openid and a name for the group that is the "owner" of the annotations is needed. With the basic meaning that all members of that groups are able to edit/delete the annotation. As this is actually a provenance information, it should be present in the Annotation... until it dies (as we also have the name of mother and father on any of our IDs!).
   Conclusion: I agree that we need to be able to represent groups in the provenance information (which is now the creator field. How to model it correctly is another discussion)
2. I think it was made clear that ACL is needed, and that this should go to the protocol part of the standard. Still ... do not forget that a (hard-)link between the Annotation and ACL must exist explicitly! And this link must be bidirectional (in the sense that the ACL should be retrieved on the annotation-id, and the annotation should be retrieved by some protocol token)!
   And we have also a wining standard for the ACL ... the Oauth2

For me it is a pitty that this is not implemented in the first version, as groups are the first thing one needs, when the amount of annotations is growing (think a bit of how offen @ and # are used in social media)