Skip to the content.

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:

Permission model

Types of permissions:

The owner of an annotation can have (What?)

Types of operations permitted:

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. ( ) 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:

Access status parameter:

POST /annotations/?access_status=restricted&can_see=Bob&can_edit=Charlie
Host: {annotation-server-address}
Accept: application/ld+json; profile=""
Content-Type: application/ld+json; profile=""

    "@context": "",
    "type": "Annotation",
    "body": [
            "value": "Communication",
            "purpose": "classifying",
            "id": ""
    "creator": "Alice",
    "target": [
            "@context": "",
            "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.