COAR Notify Protocol version 0.9.0 Deprecated! Go to most recent version

COAR Notify Protocol 0.9.0

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC 2119.

COAR Notify notifications are designed to be sent and received using the W3C Linked Data Notifications (LDN) standard. Payloads have a predictable structure, based primarily on Activity Streams 2.0, with some additional vocabularies included for particular properties. COAR Notify implements the generic notifications described by the Event Notifications in Value-Adding Networks specification.

In the COAR Notify protocol, we call these standardised payloads Patterns.

Patterns

All COAR Notify patterns MUST define an Activity Streams 2.0 activity. The following properties and their descriptions represents a baseline set of requirements. The individual patterns may add additional constraints. The workflows which use the patterns may, in turn, add additional constraints.

The activity MUST contain the following

@context

@context is REQUIRED. This is the JSON-LD 'context' for the activity.

id

id is REQUIRED. This must be a URI, and the use of URN:UUID is recommended. An HTTP URI may be used, but in such cases the URI should resolve to a resource which represents the activity.

type

type is REQUIRED. This should include one of the Activity Stream 2.0 Activity Types. It may (depending on the activity) also include a type from the Notify Activity Types vocabulary

origin

origin is REQUIRED. The originator of the activity, typically the service responsible for sending the notification.

target

target is REQUIRED. The intended destination of the activity, typically the service which consumes the notification.

object

object is REQUIRED. This should be the focus of the activity. Other object properties may appear in notifications, as properties of other properties.

The activity MAY contain the following

actor

actor is RECOMMENDED. It describes the party responsible for this activity. It:

  • MUST have an id which MUST be a URI identifying the actor (HTTP URIs are RECOMMENDED, but any valid URI is permitted)
  • MUST have a type which MUST be one of: Application, Group, Organization, Person or Service from Activity Streams 2.0.
  • MAY have a name

The inclusion of actor is highly RECOMMENDED in order to facilitate the broadest possible interoperability beyond the immediate COAR Notify context. Some external systems which can usefully consume notifications based on Activity Streams 2.0 may require the presence of an actor to function correctly.

inReplyTo

inReplyTo is OPTIONAL. This property is used when the notification is a direct response to a previous notification (usually a request) and references the Activity Streams 2.0 activity id of the previous notification.

context

context is OPTIONAL. This identifies another resource which is relevant to understanding the notification.

summary

summary is OPTIONAL. This is used rarely, but may be used to provide a brief textual summary of the notification (for example in the case of an error)

Patterns

Notify Activity Types

References