COAR Notify Protocol version 1.0.0 Current version!

COAR Notify Protocol 1.0.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 MUST 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 represent 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. It takes an array of URIs which MUST include:

  • https://www.w3.org/ns/activitystreams

and MUST include ONE of the following:

  • https://coar-notify.net (preferred)
  • https://purl.org/coar/notify instead (deprecated)

id

id is REQUIRED. It MUST identify an Activity Streams 2.0 activity. Its value MUST be a single URI, and the use of URN:UUID is RECOMMENDED. An HTTP URI MAY be used instead, and in such cases the URI SHOULD resolve to a useful resource.

type

type is REQUIRED. It MUST 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. It describes the system which has sent the notification. It:

  • MUST have an id which MUST be an HTTP URI identifying the sending system
  • MUST have a type which SHOULD include the value Service from Activity Streams 2.0
  • MUST have an inbox which MUST have the HTTP URI of the LDN inbox for the origin.

target

target is REQUIRED. It describes the system which is intended to receive the notification. It:

  • MUST have an id which MUST be an HTTP URI identifying the receiving system
  • MUST have a type which SHOULD include the value Service from Activity Streams 2.0
  • MUST have an inbox which MUST have the HTTP URI of the LDN inbox for the target.

object

object is REQUIRED. It is the focus of the activity. Other object properties MAY appear in notifications, as sub-properties.

  • MUST have an id which MUST be a URI identifying the object.

The activity SHOULD 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 which is a string containing the name of the party responsible for this activity

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.


The activity MAY contain the following

inReplyTo

inReplyTo is OPTIONAL. It SHOULD be specified if this is a response to a previous notification. It takes the URI which identifies the activity for which this is a response.

context

context is OPTIONAL. It identifies a resource on the target which is relevant to understanding the notification. It SHOULD be used if the activity is related to a resource on the target. When used, context MUST at least have an id property, the value of which MUST be a URI.

summary

summary is OPTIONAL. It provides a brief, free-text summary of the notification (for example in the case of an error)

Patterns

Notify Activity Types

References