Home | About | Blog | Discussion |
Annotation Access Permissions
Permission Requirements
Levels of permissions
From discussions with potential users it is clear there is a need to have different levels of permissions, with the default being private, that is, only the creator of an annotation can see/edit/delete the annotation. Further levels can be group and public. A flexible solution for dealing with groups is the UNIX model, where users represent their own groups, but additional groups can be made to which multiple users can belong.
Transferring permissions
Each annotation must have see/edit/delete permissions for at least one user (typically the creator), but there may be a need to transfer permissions to another user. It may also be desirable to transfer full permissions to a group of users.
Operations permitted
The most basic permission is being able to read/see/view an annotation. Given that a user can create, retrieve, edit, and remove annotations, it makes sense to have separate permissions for different operations, e.g. seeing (reading) and changing or removing (writing). This can also be based on the UNIX model for read/write/execute permissions. The execute operation in UNIX has no meaningful correspondence in the annotation domain, so it can be discarded.
This results in the following list of requirements:
- R1: there should be permission levels for owner, group and public.
- R2: the operation types reading and writing should have their own permissions.
- R3: ownership should be transferrable.
- R4: owners should be able to change operation permissions per level and per group.
Permission model
Types of permissions:
- owner: the user who is the owner of the annotation. By default, this is the creator of the annotation, but it should be possible to transfer ownership to other users or groups of users. The owner can only be a single entity, e.g. either a single user or a single group.
- group: the group(s) who have access to the annotation. Each user represents their own group. Additional groups can be made that can have multiple members. Users may want to share an annotation with multiple users and/or multi-user groups, so this can be a list of groups (single-user and multi-user groups).
- public: the public represents any user. The server may return public annotations for requests without an authenticated user.
The owner of an annotation can have (What?)
Types of operations permitted:
- read: the permission to see/view/read an annotation. The responsibility lies with the server to return only annotations to a user who has read permissions.
- writing: the permission to make changes to an annotation, including deleting it. Changes are timestamped via the
modified
property. To avoid overly complex permission models, there should only be a single set of properties that are allowed to be changed. The properties relation to the creation of the annotation (e.g.creator
,created
) should not be changeable. The server should check with each PUT request whether the user has edit permissions. The client can indicate edit permissions through e.g. an edit button.
There are some issues regarding changing or deleting annotations. If an annotation is the target of a later annotation, it cannot be changed or removed without consequences. One way of dealing with this is to add a notification to annotations that target a changed/deleted annotation. Another way is to not allow changing/removing annotations that are targets of other annotations.
[BB: In Alexandria, there is no “editing” of an annotation as such, when you PUT to an existing annotation, this creates a new annotation that replaces the existing annotation, and increases the “version” number. When referring to the annotation by URI, it always refers to the latest version of the annotation, but all versions of the annotation can be retrieved by adding /ver/ + the version number to the annotation URI. Also, sending a DELETE to an annotation sets the state of that annotation to DELETED. DELETED annotations are hidden by default, but can still be retrieved. ( http://huygensing.github.io/alexandria/alexandria-acceptance-tests/concordion/nl/knaw/huygens/alexandria/annotation/Accessing.html ) This can be an alternative or an additional way of dealing with edit/delete.
There is also currently no provision in Alexandria for user-based access limitations, or grouping of users.]
Capturing groups and permissions in annotations
The W3C working group for Web Annotations suggests to use the audience property for any group-related aspects and that authorization and authentication are not responsibilities of the annotation data model (as discussed in this issue on GitHub: How do we model “groups” in the Annotation Model).
Authentication is dealt with by the annotation server. The annotation protocol can deal with authorization through URL query parameters.
Access permission parameters:
can_see
: list of users who can see but not edit an annotationcan_edit
: list of users who can see and edit an annotation
Access status parameter:
access_status
: determines whether an annotation isprivate
,shared
orpublic
. An owner/creator can always change the status ofprivate
andshared
annotations. Question: should an owner/creator be able to change the status ofpublic
annotations back toshared
orprivate
?- When
POST
ing an annotation, a creator can indicate theaccess_status
of the annotation, and where relevant, the access permission parameters.- The default
access_status
isprivate
. An annotationPOST
ed without specifying itsaccess_status
is assumed to be private. Forprivate
annotations, no additional permission parameters are required or allowed. Owners/creators can always see and edit their own annotations. - For
shared
annotations, the owner/creator MAY indicate whocan_see
and whocan_edit
. If no permissions are specified, no changes in permissions are made (e.g. if userPOSTS
a new annotation areshared
or changes an existing annotation fromprivate
toshared
without listing other users, the status is set toshared
but only the user has access. Owners/creators do not have to list themselves in theshared
permission lists, as they always retaincan_see
andcan_edit
permissions. - For
public
annotations, only the owner/creator has permissions to change or delete the annotation. Question: shouldpublic
annotations be deletable?
- The default
POST /annotations/?access_status=restricted&can_see=Bob&can_edit=Charlie
Host: {annotation-server-address}
Accept: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
Content-Type: application/ld+json; profile="http://www.w3.org/ns/anno.jsonld"
{
"@context": "http://www.w3.org/ns/anno.jsonld",
"type": "Annotation",
"body": [
{
"value": "Communication",
"purpose": "classifying",
"id": "http://dbpedia.org/resource/Communication"
}
],
"creator": "Alice",
"target": [
{
"@context": "http://boot.huygens.knaw.nl/annotate/vangoghontology.ttl#",
"type": ["Text", "Letter"],
"id": "urn:vangogh:let001"
}
]
}
In the above annotation, Alice is the owner/creator of the annotation, Bob can only see but not edit the annotation, while Charlie can see and edit the annotation, as well as delete it. Both Alice and Charlie can change who can_see
and can_edit
the annotation, although Charlie cannot change or remove the permissions of Alice as she remains the owner/creator of the annotation and does not have to be specified in the parameters.
Bulk updating permissions
TO DO: finish this section.
A user may want to update a set of annotations to have the same acccess status and permissions. To enable bulk setting or updating of permissions, a user can PUT
an AnnotationContainer
using Prefer
type PreferContainedIRIs
in the request header, and the access status and permissions in the URL parameters.
For sharing annotations with large numbers of users, specifying them in the URL is cumbersome. There might be a clean way to add permission information in the container representation.