Event Notifications in Value-Adding Networks

Living Document,

This version:
https://www.eventnotifications.net
Issue Tracking:
GitHub
Editors:
(Ghent University Library)
(meemoo - Flemish Institute for Archives)
(IDLab - Ghent University)
(Antleaf)
(Los Alamos National Laboratory)
(IDLab - Ghent University)

Abstract

This document lists the possible notifications that can be used in the network.

Feedback welcome: value-adding-networks@googlegroups.com.

1. Introduction

Notification
Notification
Artifact
Artifact
Agent
Agent
Agent
Agent
LDN Inbox
LDN Inbox
LDN Inbox
LDN Inbox
object
object
Data Node
Data Node
Service Node
Service Node
actor
actor
target
target
Notification
Notification
context
context
Agent
Agent
Agent
Agent
actor
actor
target
target
Service
result
Service...
object
object
Text is not SVG - cannot display

Overview of the network participants

This document pertains to decentralized networks in which actors make artifacts available in the network, add value to available artifacts, and exchange messages about these activities.

Artifacts are resources that are made available in a network of a community of use and the nature of the artifacts depends on that community. For example, in a research communication network, artifacts are research outputs such as preprints, reviewed articles, datasets, and software that are part of the scholarly record.

In the network, a distinction is made between data nodes where artifacts are hosted, and service nodes where value is added to artifacts hosted by data nodes.

Actors operate on behalf of data nodes or service nodes; they can be humans or machines, individuals or organizations, authors of artifacts or providers of value-adding services. These actors exchange messages that describe activities, each of which amounts to a lifecycle event in which an artifact that is hosted by a data node is involved. The considered activities are events in which:

Added value services don’t change the content of the original artifacts. Instead, the service result can be to make an artifact discoverable, providinge additional information pertaining to the artifact (e.g. a trusted timestamp, a linkage to another artifact), publishing a new resource that pertains to the artifact (e.g. a review, a comment), or is a derivative of the artifact (e.g. an enhanced version, a translation, an archival copy).

The messages exchanged by actors are expressed by means of a profile of the ActivityStreams 2.0 vocabulary (AS2) and exchanged using the Linked Data Notification protocol (LDN). The sender of the message uses an LDN Sender application to send messages as notification over the network. The receiver uses an LDN Receiver application to store the messages as notifications in an LDN Inbox.

The activities are the payloads of the messages that are sent as LDN notifications.

In open data context the activities can express when research data artifacts are made available, who is (re)using the datasets in the network, which publications are referring to the dataset and how it entered in scientific search engines. Based on these activities the nodes in the network can inform the creators about reuse of their datasets or update the metadata of the datasets providing interlinking to network resources.

In publishing context the activities express the various stages in the publication process of artifacts. The activities can, for instance, express when a publication is time stamped by network service, when it was submitted or accepted by a journal, when peer-review was conducted, when it was entered in an abstract & index database, and at which date archived copies were made available in a web archive.

In archiving context the activities can express the various production states of artifacts and provide in this way information about the digital provenance of the artifact. The activity can express when an artifact was created, who updated the artifact, when it was publicly available and when it was removed.

2. Document Conventions

Within this document, the following namespace prefix bindings are used:

Prefix Namespace
as https://www.w3.org/ns/activitystreams#
ldp http://www.w3.org/ns/ldp#

Examples of notification payloads use [JSON-LD] as syntax.

3. Network entities

This section clarifies the terminology that was introduced in the introduction.

3.1. Artifact

An artifact is a resource identified by a [URL] that serves as the main focus of interaction between actors. Examples are a digitized image in an archive, the webpage of a scientific publication, a digital representation of a cultural heritage object, or a data set in a repository.

Artifacts can be atomic or can be of arbitrary complexity. How they are organized is outside the scope of this document and is dependent on the implementing community.

3.2. Data node

A data node is an HTTP server that hosts artifacts and provides one or more LDN Inboxes via which actors that operate on behalf of the data node can be reached. These LDN Inboxes are able to receive JSON-LD messages pertaining to life cycle events in which an artifact hosted by the data node is involved (See Section 6 Below).

3.3. Service node

A service node is an HTTP server that provides value-added services for artifacts hosted by data nodes and provides one or more LDN Inboxes via which actors that operate on behalf of the service node can receive service requests pertaining to the data node artifacts (See Section 6 Below). The result of providing a value-added service for an artifact - whether requested or volunteered - is communicated to an actor that operates on behalf of the data node that hosts the artifact in the form of a JSON-LD message delivered to that actor’s LDN Inbox.

When a service node creates a new artifact as a result of providing a value-added service for an artifact hosted by a data node, then this new artifact can be made available in the network in its own right and can itself become the subject of activities and messages. As a result, at that point, the service node must have an associated data node via which the new artifact is made available.

3.4. Service result

A service result is any outcome of providing a value-added service for an artifact hosted by a data node. Service results can be resources that are made available at a network address or inline data that is provided in the JSON-LD messages that are communicated to the actor that operates on behalf of the data node that hosts the artifact.

3.5. Actor

Actors operate on behalf of data nodes or service nodes; they can be humans or machines, individuals or organizations, authors of artifacts or providers of value-adding services. An actor, identified by a [URI], either:

3.6. Target

Targets are the intended receivers of messages that are exchanged on the network. The target is a human, or machine, individual or organization that is the intended audience of a message. A target, identified by a [URI], either:

3.7. Agent

Agents are the active participants in the network: they perform actions and can be identified or addressed. Agents are the actors or targets that can be addressed with a [URI] and that can send or receive messages via Linked Data Notifications.

4. Network communication patterns

In the decentralized network, nodes, in particular the actors that are responsible for the artifacts and services on these nodes, communicate by sending Linked Data Notification messages to each other. These messages are delivered to LDN Inboxes that are made available on the data and service nodes on behalf of the actors managing the artifacts and services on these nodes.

Depending on the type of interaction an actor is a sender or receiver of messages. This specification describes two communication patterns between the nodes in the network.

The first pattern describes the communication as one-way, expressing facts like "I did this activity on an artifact". These messages don’t expect a response back from other actors in the network.

A second communication pattern requires a more elaborate communication back and forth. This request-response style of communication can span many days, weeks or months and could contain many details for each particular service. However, the request-response patterns that are the focus of this specification are those that convey life cycle information to the actors at the side of the data node and the service node. The actual communication requirements to fulfill all the details of value-added services is not under consideration. The patterns listed in the next section only support conveying the factual end result of a (complicated, internal) process: what was added to the lifecycle of an artifact, the rest is treated as a black box.

4.1. One-way pattern

Data node
Data node
Notification
Notification
Artifact
Artifact
object
object
Archive
Archive
Web
Archive
Web...
Service
Node
Service...
Text is not SVG - cannot display

Figure 1. An Archive sends a message to a Web Archive about the update of an artifact.

The one-way pattern is used for sending an informative message pertaining to an artifact to another actor in the network. In the case of data nodes, one-way patterns are used to inform an actor about CRUD (Create, Read, Update, Delete) actions on artifacts. In most use-cases these messages are generated by automated processes that monitor artifacts. Examples of such messages are:

These two examples demonstrate how data nodes (such as the institutional repository and archive) can communicate with service nodes (the search engine and web archive) about artifact updates.

Data
Node
Data...
Notification
Notification
object
object
Overlay
Journal
Overla...
Institutional
Repository
Instit...
Service
Result
Service...
Artifact
Artifact
context
context
Service
Node
Service...
Text is not SVG - cannot display

Figure 2. An Overlay Journal sends a message to an Institutional Repository announcing one of its artifacts was published.

One-way communication in the other direction is also possible: a service node that sends an unsolicited message to a data node about an artifact. Examples of such messages are:

In the last example researcher A is acting as a service node. She has a HTTP server which contains the comment. She has the means to send Linked Data Notifications about this service result. When researcher A would publish this comment as artifact and receive Linked Data Notifications about it, then she would also be a data node.

LDN
Sender
LDN...
LDN
Receiver
LDN...
Notification
Notification
Artifact
Artifact
object
object
A
A
B
B
Text is not SVG - cannot display

Figure 3a. One-way pattern where a sender A as data node, using an LDN Sender, sends a notification about an Artifact to the receiver B, which has a LDN Receiver.

LDN
Sender
LDN...
LDN
Receiver
LDN...
Notification
Notification
Service
result
Service...
object
object
A
A
B
B
Text is not SVG - cannot display

Figure 3b. One-way pattern where a sender A as service node, using an LDN Sender, sends a notification about a Service result to the receiver B, which has a LDN Receiver.

In general, a one-way pattern is informative between two communicating nodes. The node that initiates the communication (node A in Figure 3a and Figure 3b), does not expect a reply from the receiving node (node B in Figure 3). The one-way pattern is used when the receiving actor at node B needs to be made aware of an activity pertaining to a resource hosted by the sender at node A, but does not necessarily need to respond. When the LDN Sender is a data node, the resource is an Artifact. When the LDN Sender is a service node the resource is a Service result.

4.2. Request-response pattern

Data
Node
Data...
Request
Notification
Request...
Artifact
Artifact
object
object
Ack
Notification
Ack...
context
context
object
object
Response
Notification
Response...
context
context
Service
Result
Service...
object
object
Institutional Repository
Institutional Repository
Peer-Review system
Peer-Review system
Service
Node
Service...
Text is not SVG - cannot display

Figure 4. An Institutional Repository requests for an artifact a peer service from a Peer-Review system. The Peer-Review system evaluates the request and sends an acknowledgment back indicating it is committed to provide this service. At some later date, the Peer-Review system responds with a link to a new peer review that contains the results of the peer review process.

The request-response pattern is used in more elaborate communication processes, in cases where actors need to ask for services from a service node and no direct results can be expected. This style of communication expects that the updates to the life cycle of artifacts can take hours, days or months to be processed. In these cases, it would be impractical to wait for an answer from the service node, or require software to poll a web service for status updates.

The pattern starts by offering an artifact from a data node to a service node. The service node can optionally evaluate the artifact and can decide if it can commit to providing services on the artifact. In the form of an acknowledgment or rejection this information can be sent to the data node. The service node can start an internal process (which is not in scope of this specification) to fulfill the service request. The end result of the internal process will be the announcement of a new result artifact, or a rejection without a new artifact being created.

Examples of such a request-response pattern are:

LDN
Sender
LDN...
Request
Notification
Request...
Artifact
Artifact
object
object
Ack
Notification
Ack...
context
context
object
object
Response
Notification
Response...
context
context
Service
Result
Service...
object
object
LDN
Receiver
LDN...
LDN
Sender
LDN...
LDN
Receiver
LDN...
A
A
B
B
Text is not SVG - cannot display

Figure 5. Request-response pattern where A, using a LDN Sender, sends a notification about a local Artifact to the LDN Receiver endpoint of B. After some time B, using its own LDN Sender, sends an acknowledgment to the LDN Receiver endpoint of A. The final result of the service that B provides, the Service Result, is sent by B, using an LDN Sender, to the LDN Receiver endpoint of A.

In general, the request-response pattern is transactional. The initiator of a request notification (node A in Figure 5) expects the receiver (node B in Figure), to send a response notification with the result of some value-added service. The request-response pattern is used when the receiving actor at node B is requested to provide a service pertaining to an artifact hosted by the sender at node A; the answer to the service request is delivered as a response notification. This pattern can optionally include an acknowledgment phase, where, prior to providing the service, the receiving actor can send an acknowledgement notification to indicate whether or not it commits to providing the service requested by the request notification.

4.3. Chained pattern

Data
Node
Data...
Notification
Notification
A
A
B
B
Service
Result
Service...
Artifact
Artifact
context
context
Service
Node
Service...
Data node
Data node
Notification
Notification
Artifact
Artifact
object
object
C
C
Service
Node
Service...
object
object
D
D
=
=
Text is not SVG - cannot display

Figure 6. The output of one workflow can be the input of a second workflow. In the top part a service node A creates a value-added service result for an artifact that is stored on a data node B. The service result is made available as a network resource as Artifact on a data node C that is associated with the service node. For this Artifact a new value-added service can be requested from node D.

The chained pattern is used when the service result of a value-added service is made available on an associated data node. This makes the service result available as a new artifact for which new value-added services can be provided. An example of such a pattern is:

5. Activities

A notification is sent by an agent to inform another agent about an activity. An activity is either an event pertaining to a certain artifact or an event related to a service requested pertaining to an artifact in the network. An activity is described by a notification payload.

Notification payloads are expressed using the ActivityStreams 2.0 vocabulary and use [JSON-LD] as default syntax (other RDF syntaxes are allowed as well). Every notification message is uniquely identified, indicates the type of activity it is describing, and includes at least the publication date of the activity. It also describes the entities involved (depending on the network communication pattern). The table below described the possible entities for each pattern and the intended use.

Table 1. ActivityStreams 2.0 entities used by the One-Way and Request-Response communication pattern messages

AS2 elements One-Way Pattern One-Way Pattern Request-Response Pattern Request-Response Pattern
Data node sends Service node sends Data node Request Service node Response
id Message identifier Message identifier Message identifier Message identifier
type Activity type Activity type Activity type Activity type
published Activity datetime Activity datetime Activity datetime Activity datetime
actor Agent that performed the activity Agent that performed the activity Agent that performed the activity Agent that provided the added-value service for an artifact on a data node
origin Agent responsible for sending the notification Agent responsible for sending the notification Agent responsible for sending the notification Agent responsible for sending the notification
context Not used The artifact on the data node for which an added-value service was provided The artifact on the data node for which an added-value service was provided The artifact on the data node for which an added-value service was provided
inReplyTo Not used Not used Not used The message identifier of the request
object The artifact that is the subject of the activity The result of the added-value service provided for an artifact on the data node The artifact that is the subject of the activity The result of the added-value service provided for an artifact on the data node
target The agent at the service node that is the addressee of the notification The agent at the data node that is the addressee of the notification The agent at the service node that is the addressee of the notification The agent at the data node that is the addressee of the notification

The minimal example below illustrates an interaction between the two human actors Alice and Bob. Alice (actor) notifies Bob (target) via her data repository (origin) to inform him about the artifact (object) she created.

EXAMPLE 1. Alice notifies Bob in a one-way pattern (data node sends) about the creation of the new artifact http://acme.org/artifacts/alice/five_steps_to_success.html

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:0F402B08-F676-40EE-9D4B-480B3F985B65",
    "type": "Create",
    "published": "2022-06-12T12:12:12Z",
    "summary": "Alice created an artifact",
    "actor": {
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    },
    "origin": {
       "id": "https://acme.org/system",
       "name": "ACME Research Institute System",
       "type": "Application"
    },
    "object": {
       "id": "https://acme.org/artifacts/alice/five_steps_to_success.html",
       "type": "Article"
    },
    "target": {     
       "id": "https://orcid.org/0000-0109-01931-191019",
       "inbox": "https://infinity.science.com/inbox/bob",
       "name": "Bob",
       "type": "Person"
    }
  }

The second example below illustrates an interaction between a service node, Fairfield City Repository, and Alice involving an artifact on her data node. Fairfield City Repository (actor) notifies Alice (target) via their Darwin System (origin) about a new relationship between a resource in the Fairfield City Repository and an artifact in Alice’s data node.

EXAMPLE 2. Fairfield City Repository notifies Alice in a one-way pattern (service node sends) about the announcement of a new relationship between Alice’s artifact on her data node and an archival copy in the Fairfield City Darwin system.

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:239FD510-03F4-4B56-B3A0-0D3B92F3826D",
    "type": "Announce",
    "published": "2022-06-15T03:55:50Z",
    "summary": "Fairfield Repository created an archival copy of your artifact",
    "actor": {
       "id": "https://fairfield.org/about#us",
       "inbox": "https://fairfield.org/inbox",
       "name": "Fairfield City Repository",
       "type": "Organization"
    },
    "origin": {
       "id": "https://darwin.fairfield.org/system",
       "name": "Fairfield City Darwin System",
       "type": "Application"
    },
    "context":"https://acme.org/artifacts/alice/five_steps_to_success.html",
    "object": {
       "id": "urn:uuid:CF21A499-1BDD-4B59-984A-FC94CF6FBA86",
       "type": "Relationship",
       "subject":"https://acme.org/artifacts/alice/five_steps_to_success.html",
       "relationship":"https://www.iana.org/memento",
       "object":"https://darwin.fairfield.org/objects/317831-13210"
    },
    "target": {     
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    }
  }

5.1. Types of activities

Notification payloads apply the ActivityStreams 2.0 vocabulary. Therefore, the notification payload MUST be typed as a as:Activity or as one of its more specialized subtypes.

The nodes in the network use a limited subset AS2.0 Activity Types. The activities, along with their types, are divided into two categories:

The following table summarizes the possible activity types according to category.

Activity Type Purpose
Activities about an artefact’s state
as:Create An actor created an artefact in a data node.
as:Update An actor updated an artefact in a data node.
as:Remove An actor deletes an artefact in a data node.
as:Announce An actor announces the existence of an artefact. This activity is different from as:Create, which denotes a fact (ie. the what, when, where and how a new artefact was created). With as:Announce, the sender doesn’t say anything about when the artefact was created, but only desires that the target is notified about its existence.
Activities pertain to applying value-adding services
as:Offer An agent offers an artefact to another agent in order to invoke a service. The execution of this service may lead to a new activity with the same artefact as the object.
as:Accept An agent accepts to execute a service on a specified artefact, as requested by another agent. This is a direct reply to a received as:Offer.
as:Reject An agent rejects to execute a service on a specified artefact, because it is somehow unable to fulfill the request by another agent. This is a direct reply to a received as:Offer.
as:Announce An agent announces the artefact that resulted from executing a requested service.
as:Undo An agent etracts a prior activity, which can be of any of the above types.

In addition to the listed activity types above, an activity MAY have additional subtypes imposed by the application domain. For instance, when a service node would like to Announcethe endorsement of a publication the schema:EndorseAction can be used. The schema.org can be imported into the activity by adding it to the @context section.

EXAMPLE 3 Bob announces that he endorses the publication of Alice by writing a review

{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      { "schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:42D2F3DC-0770-4F47-BF37-4F01E0382E32",
    "type": [ "Announce" , "schema:EndorseAction" ],
    "published": "2022-08-01T13:49:01Z",
    "summary": "Bob endorses Alice's artifact",
    "actor": {
       "id": "https://orcid.org/0000-0109-01931-191019",
       "inbox": "https://infinity.science.com/inbox/bob",
       "name": "Bob",
       "type": [ "Person" , "schema:publisher" ]
    },
    "origin": {
       "id": "https://infinity.science.com",
       "name": "Infiniti science publishing",
       "type": "Application"
    },
    "context": "https://acme.org/artifacts/alice/five_steps_to_success.html",
    "object": {
       "id": "https://infinity.science.com/artifacts/bob/review_123.html",
       "type": "Article"
    },
    "target": {     
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    }
  }

5.2. Identifying an activity

To establish robust communication on the network, activities have to be at least uniquely identifiable within the scope of the network. Therefore, an identifier of any kind used MUST be a valid [URI].

There are two identifiers that operate at the level of the notification:

In the network typically the activity identifier is the most visible identifier. This one can be read from the notification payload document. In the example 1 above, the activity identifier is:

urn:uuid:0F402B08-F676-40EE-9D4B-480B3F985B65

The **notification identifier is the URL of the notification itself. This is the URL that is used to retrieve a copy of the notification. For example, if the inbox of Bob is implemented as an Linked Data Platform Container (as specified in the Linked Data Notifications specification), then it would have an URL such as:

https://infinity.science.com/inbox/bob/F9800F41-4636-44F7-8307-CCCEE7C5F0D7

In some cases the activity identifier and notification identifier can overlap. When a node makes notifications publicly available (for instance, via ActivityPub outboxes) the notification will be available at a URL which is reflected in the choice of activity identifier.

EXAMPLE 4 Alice notifies Bob about the creation of a new artifact. She also makes this notification public available at http://acme.org/events/alice/0F402B08-F676-40EE-9D4B-480B3F985B65

GET /events/alice/0F402B08-F676-40EE-9D4B-480B3F985B65 HTTP/1.1
Host: acme.org
Accept: application/ld+json
{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "http://acme.org/events/alice/0F402B08-F676-40EE-9D4B-480B3F985B65",
    "type": "Create",
    "published": "2022-06-12T12:12:12Z",
    "summary": "Alice created an artifact",
    "actor": {
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    },
    "origin": {
       "id": "https://acme.org/system",
       "name": "ACME Research Institute System",
       "type": "Application"
    },
    "object": {
       "id": "https://acme.org/artifacts/alice/five_steps_to_success.html",
       "type": "Article"
    },
    "target": {     
       "id": "https://orcid.org/0000-0109-01931-191019",
       "inbox": "https://infinity.science.com/inbox/bob",
       "name": "Bob",
       "type": "Person"
    }
  }

When referring to an activity always the activity identifier MUST be used. The activity identifier of a notification MUST NOT be edited or removed by any node in the network when processing incoming or outgoing notifications. The notification identifier doesn’t have any restrictions and can have any format (preferably a HTTPS address).

5.3. The object of an activity

All activities MUST contain an object using the as:object predicate. Depending on the activity type, the object can refer to:

An object MUST contain an identifier, which must be an [URI]. The object identifier SHOULD be dereferenceable, so possible artifacts can be retrieved.

5.3.1. Out-of-band versus in-band descriptions

The description of the object SHOULD be delivered by one of two methods:

Whether an implementation gives priority to in-band or out-of-band is left up to the implementer.

As a general recommendation: give in-band descriptions priority to a dereferenceable out-of-band description. Receivers may of course dereference the object identifier to retrieve an additional description as well. However in case conflicts arise between both descriptions, the most recent description should be given priority. This can be identified by comparing the Last-Modified date of the HTTP response with the activity published data in as:published.

5.3.2. Direct and response activities

There are two types of activities:

5.3.2.1. Direct activities

The object of a direct activity MUST describe the artifact on which the activity has effect. An artifact MUST be of type as:Object or one of the ActivityStreams Object Types. Additionally, an artifact MAY have additional types imposed by the application domain (e.g., schema:Dataset in a cultural heritage network or schema:Document in a scholarly communication network).

EXAMPLE 5 Alice offers a dataset she wants to submit to Data Archive XYZ.

{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "type": "Offer",
    "published": "2022-06-12T12:12:12Z",
    "summary": "Data submission 1234",
    "actor": {
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    },
    "origin": {
       "id": "https://acme.org/system",
       "name": "ACME Research Institute System",
       "type": "Application"
    },
    "object": {
       "id": "http://acme.org/artifacts/alice/data-set-2022-01-19.zip",
       "type": "schema:Dataset"
    },
    "target": {     
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Application"
    }
  }
5.3.2.2. Response activities

If an activity is of type as:Reject, as:Accept, or as:Undo, the object MUST be an activity with type as:Activity.

Response activities MUST have an as:inReplyTo field which contains the activity identifier of the previous activity on which the current activity is a response.

EXAMPLE 6 Data Archive XYZ send a response to the offer and indicates data set was accepted for further processing

{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:9CEE5D10-E280-4DC8-909A-A5BF0F7EADF0",
    "type": ["Accept","schema:ArriveAction"],
    "published": "2022-06-13T00:00:01Z",
    "summary": "Data Archive XYZ ingest process accepts submission 1234 from Alice",
    "actor": {
       "id": "https://data.archive.xyz.net/process/ingest",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Application"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/",
       "name": "Data Archive XYZ",
       "type": "Application"
    },
    "context": "http://acme.org/artifacts/alice/data-set-2022-01-19.zip",
    "inReplyTo": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "object": {
       "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
       "type": "Offer"
    },
    "target": {     
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    }
  }  

5.4. Addressing the receiver and sender

Notifications that are sent to a network node are delivered to an inbox. Since inboxes can be shared by more than one actor, the notification’s payload should indicate what actor it intends to address. Thus, an activity MUST contain a target using the as:target predicate.

Accordingly, the payload should also indicate which actor performed the activity. Hence, an activity MUST also contain an actor using the as:actor predicate.

The target, origin (when used, see below) and actor MUST be identifiable with an HTTP [URI]. They MUST be of the following Activity Streams 2.0 Object type:

Additionally, an actor MAY have additional types imposed by the application domain.

The actor and target SHOULD have an ldp:inbox that refers to the inbox [URI] where the actor can be reached.

The actor and target MAY have a name using as:name.

EXAMPLE 7 A Publisher accepts Alice’s publication for publication in a forthcoming journal and sends a response to Alice

{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:9CEE5D10-E280-4DC8-909A-A5BF0F7EADF0",
    "type": "Accept",
    "published": "2022-06-13T00:00:01Z",
    "summary": "Infinity Science accepts submission 1234 from Alice",
    "actor": {
       "id": "https://infinity.science.com/people/Jane#me",
       "inbox": "https://infinity.science.com/people/Jane/inbox/",
       "name": "Jane Doe",
       "type": [ "Person" , "schema:publisher" ]
    },
    "context": "http://acme.org/artifacts/alice/data-set-2022-01-19.zip",
    "inReplyTo": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "origin": {
       "id": "https://infinity.science.com/service/card#i",
       "name": "Infinity Science Repository",
       "type": "Application"
    },
    "object": {
       "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
       "type": "Offer"
    },
    "target": {     
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    }
  }  

5.5. The originating software application

A notification can provide more information on how the notification got sent. Therefore, an activity SHOULD provide an origin using the as:origin predicate. It refers to the software component, such as the repository, that was responsible for sending the activity over the network (the software that acted as LDN Sender).

The origin MAY have an ldp:inbox that refers to an inbox [URI] where it can be reached.

When a network node intends to respond to a notification, it MUST send the response notification to all discovered inbox URLs.

A valid inbox URL MUST be discovered from:

5.6. The artifact context

All notifications in the network are artifact centric, a notification thread starts with an agent that starts some activities on an artifact or requests services for an artifact. To be able to refer in a notification back to the original artifact which started the notification communication between the nodes ActivityStream2 as:context can be used. The as:context , when used, MUST contain the URL to the original artifact that initiated the notification exchange.

In the example 5 above, Data Archive XYZ sends an as:Accept in context of the as:Offer on the artifact http://acme.org/artifacts/alice/data-set-2022-01-19.zip.

6. One-way notification patterns

This section covers notification patterns using activity types as:Create, as:Remove, as:Update, and as:Announce. The [JSON-LD] payload MUST contain at least the following properties:

The [JSON-LD] payload SHOULD also contain the following property:

The [JSON-LD] payload MAY also contain the context property when a service node provides a value added service for an artifact on a data node:

6.1. Pattern 1: An agent creates a new artifact

This pattern is used to disseminate new artifacts. An agent makes another agent aware of the creation of that artifact, without expecting immediate action.

EXAMPLE 8 Springfield library informs the National Archive about the creation of a new dataset, on their hosted ImagesTool platform

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:B4201A8A-4EE2-4DB6-AA00-B0D2F628B434",
    "type": "Create",
    "published": "2022-11-21T00:00:01Z",
    "summary": "Springfield library created a new image dataset",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "object": {
       "id": "https://imagetool.com/customer/123-321/data/set-1234/",
       "type": "Page"
    },
    "target": {     
       "id": "https://nationalarchive.org/library/ingest#service",
       "inbox": "https://nationalarchive.org/library/ingest/inbox",
       "name": "National Archives Library Project",
       "type": "Application"
    }
  }

6.2. Pattern 2: An agent updates an existing artifact

This pattern is used to inform involved actors about artifact changes on the data node. An agent informs another agent without obligation that the artifact on the data node has been updated and follow-up action might be needed.

EXAMPLE 9 Springfield library informs the National Archive about the update of an item in the dataset, on their hosted ImagesTool platform

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:56BAAE95-AE3F-4DFD-AC37-2EFFE1E32BA9",
    "type": "Update",
    "published": "2022-11-21T07:30:35Z",
    "summary": "Springfield library added a new image",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "object": {
       "id": "https://imagetool.com/customer/123-321/data/set-1234/image1.png",
       "type": "Image"
    },
    "target": {     
       "id": "https://nationalarchive.org/library/ingest#service",
       "inbox": "https://nationalarchive.org/library/ingest/inbox",
       "name": "National Archives Library Project",
       "type": "Application"
    }
}

6.3. Pattern 3: An agent removes an artifact

This pattern is used to inform involved actors about deleted artifacts from the data node. An agent another agent without obligation that an artifact has been removed from the data node and follow-up action might be needed.

EXAMPLE 10 Springfield library informs the National Archive about the removal of an item in the dataset, on their hosted ImagesTool platform

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:781D5279-A047-432F-ADD1-A88D7D8449CE",
    "type": "Remove",
    "published": "2023-04-01T12:01:59Z",
    "summary": "Springfield library removed an image",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "object": {
       "id": "https://imagetool.com/customer/123-321/data/set-1234/image1.png",
       "type": "Image"
    },
    "target": {     
       "id": "https://nationalarchive.org/library/ingest#service",
       "inbox": "https://nationalarchive.org/library/ingest/inbox",
       "name": "National Archives Library Project",
       "type": "Application"
    }
}

6.4. Pattern 4: An agent draws attention to an artifact

This pattern is used to inform involved actors about an existing artifact on a data node. An agent informs another agent without obligation that an artifact exists in a data node.

EXAMPLE 11 Springfield library informs a Alice about an item in the dataset, on their hosted ImagesTool platform

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:778A422E-7E98-4D48-9AB7-00A9DCF65705",
    "type": "Announce",
    "published": "2023-01-29T18:59:23Z",
    "summary": "Springfield library found an image about you",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "object": {
       "id": "https://imagetool.com/customer/123-321/data/set-1234/image102.png",
       "type": "Image"
    },
    "target": {     
       "id": "https://orcid.org/0000-0007-01219-312199",
       "inbox": "https://acme.org/inbox/alice",
       "name": "Alice",
       "type": "Person"
    }
  }

6.5. Pattern 5: A service node notifies a data node about linking event

This pattern is used by a service node that wishes to inform a data node about a resource that includes one or more artifacts from the data node.

EXAMPLE 12 The Riverside Data Service informs Springfield library about the inclusion of one of its images in their "Summer in Springfield" dataset

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:778A422E-7E98-4D48-9AB7-00A9DCF65705",
    "type": "Announce",
    "published": "2023-01-29T18:59:23Z",
    "summary": "Riverside Data Service included two Springfield library images in their Summer in Springfield dataset",
    "actor": {
       "id": "https://riverside.data.net/about#us",
       "inbox": "https://riverside.data.net/inbox/",
       "name": "Riverside Data Service",
       "type": "Organization"
    },
    "origin": {
       "id": "https://lambda.riverside.data.net/profile/card#i",
       "name": "Lambda Repository",
       "type": "Application"
    },
    "object": [
      {
       "id": "urn:uuid:96985D9C-7757-4642-AE83-A11436C70B47",
       "type": "Relationship",
       "subject": "https://imagetool.com/customer/123-321/data/set-1234/image102.png",
       "relationship":" http://purl.org/dc/terms/isPartOf",
       "object": "https://riverside.data.net/data/summer-in-springfield"
      },
      {
       "id": "urn:uuid:5EFFB5A9-8644-40FB-908D-1A6C7F8C298F",
       "type": "Relationship",
       "subject": "https://imagetool.com/customer/123-321/data/set-1234/image104.png",
       "relationship":" http://purl.org/dc/terms/isPartOf",
       "object": "https://riverside.data.net/data/summer-in-springfield"
      }
    ],
    "target": {     
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    }
}

7. Request-response notification patterns

This section covers notification patterns using activity types as:Offer, as:Reject, as:Accept, as:Undo, and as:Announce. These patterns are used in interactions where a sender sends a notification to a receiver (request notification) and eventually expects to receive a new notification as reply (response notification).

An agent employs a request notification to offer one of its artefacts for some value-added service to be conducted by a second agent. Therefore, the enclosed activity is always of type as:Offer. The receiving agent can decide to respond in a direct or indirect way:

7.1. Pattern 5: A service request with acknowledgment

This pattern is used where a service is requested and immediate acknowledgment is required, eg. to provide guarantees that the service will be conducted. Hence, an offer acknowledgment notification is always about the activity it is replying to.

7.1.1. Service Request

A request [JSON-LD] payload MUST contain at least the following properties:

The [JSON-LD] payload SHOULD also contain the following property:

EXAMPLE 13 Springfield library request the indexation of their image collection from ACME Search Engine

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:4FAF311A-2459-4CEF-A74C-29CCE0552672",
    "type": "Offer",
    "published": "2023-01-20T13:55:00Z",
    "summary": "Springfield library requests indexation of data/set-1234",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "object": {
       "id": "https://imagetool.com/customer/123-321/data/set-1234/",
       "type": "Page"
    },
    "target": {     
       "id": "https://acme.webindex.com/webcrawler#me",
       "inbox": "https://acme.webindex.com/webcrawler/queue",
       "name": "ACME Search Engine",
       "type": "Application"
    }
}
  

7.1.2. Service Response

A response [JSON-LD] payload MUST contain at least the following properties:

The [JSON-LD] payload SHOULD also contain the following property:

7.1.2.1. Accept Offer

A service node accepts the offer by an actor.

EXAMPLE 14 ACME Search Engine evaluated the offer to index the image collection from Springfield library and accepts it, while starting a new indexation process (which is not yet finished)

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:AB20397A-549C-40F1-9BB7-D8E4A1F9616B",
    "type": "Accept",
    "published": "2023-01-20T13:55:00Z",
    "summary": "ACME accepted your data/set-1234 for indexation",
    "actor": {
       "id": "https://acme.webindex.com/webcrawler#me",
       "inbox": "https://acme.webindex.com/webcrawler/queue",
       "name": "ACME Search Engine",
       "type": "Application"
    },
    "origin": {
       "id": "https://acme.webindex.com/profile/card#i",
       "name": "ACME Search Engine",
       "type": "Application"
    },
    "inReplyTo":"urn:uuid:4FAF311A-2459-4CEF-A74C-29CCE0552672",
    "context":"https://imagetool.com/customer/123-321/data/set-1234/",
    "object": {
       "id": "urn:uuid:4FAF311A-2459-4CEF-A74C-29CCE0552672",
       "type": "Offer"
    },
    "target": { 
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"   
    }
}
  
7.1.2.2. Reject Offer

A Service node rejects the offer by an actor.

EXAMPLE 15 ACME Search Engine evaluated the offer to index the image collection from Springfield library and rejected it

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:55D5C3C5-C284-4A55-9D97-4A329547B220",
    "type": "Reject",
    "published": "2023-01-20T13:55:00Z",
    "summary": "ACME Search Engine rejected indexation of data/set-1234",
    "actor": {
       "id": "https://acme.webindex.com/webcrawler#me",
       "inbox": "https://acme.webindex.com/webcrawler/queue",
       "name": "ACME Search Engine",
       "type": "Application"
    },
    "origin": {
       "id": "https://acme.webindex.com/profile/card#i",
       "name": "ACME Search Engine",
       "type": "Application"
    },
    "inReplyTo":"urn:uuid:4FAF311A-2459-4CEF-A74C-29CCE0552672",
    "context":"https://imagetool.com/customer/123-321/data/set-1234/",
    "object": {
       "id": "urn:uuid:4FAF311A-2459-4CEF-A74C-29CCE0552672",
       "type": "Offer"
    },
    "target": { 
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"   
    }
} 

7.2. Pattern 6: A service request with offer response

This pattern is used where a service is requested and no immediate acknowledgment is required, as long as a follow-up activity is eventually returned, ie. an agent that it processed an artefact as a result or a prior offer. Hence, an offer response notification is about an artefact that is somehow related to the activity in the request notification.

7.2.1. Service Request

A request [JSON-LD] payload MUST contain at least the following properties:

The [JSON-LD] payload SHOULD also contain the following property:

EXAMPLE 16 Springfield library offers an image collection to the national archive for archiving

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:8B938492-663B-479C-8431-07F9049B4E5D",
    "type": "Offer",
    "published": "2022-12-01T00:55:00Z",
    "summary": "Springfield library offers data/set-1234 for archiving",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "object": {
       "id": "https://imagetool.com/customer/123-321/data/set-1234/",
       "type": "Page"
    },
    "target": {     
       "id": "https://nationalarchive.org/library/ingest#service",
       "inbox": "https://nationalarchive.org/library/ingest/inbox",
       "name": "National Archives Library Project",
       "type": "Application"
    }
}
  

7.2.2. Service Response

An offer response notification [JSON-LD] payload MUST contain at least the following properties:

The [JSON-LD] payload SHOULD also contain the following property:

EXAMPLE 17 The national archive announces an archived version of the Springfield library dataset

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:8B938492-663B-479C-8431-07F9049B4E5D",
    "type": "Announce",
    "published": "2022-12-02T07:00:01Z",
    "summary": "National archive archived Springfield library data/set-1234",
    "actor": {  
       "id": "https://nationalarchive.org/library/ingest#service",
       "inbox": "https://nationalarchive.org/library/ingest/inbox",
       "name": "National Archives Library Project",
       "type": "Application"
    },
    "origin": {
       "id": "https://nationalarchive.org/ltparchiver#i",
       "name": "National Archives Archiver",
       "type": "Application"
    },
    "inReplyTo":"urn:uuid:8B938492-663B-479C-8431-07F9049B4E5D",
    "context":"https://imagetool.com/customer/123-321/data/set-1234/",
    "object": {
       "id": "https://nationalarchive.org/versions/20221202070000/https://imagetool.com/customer/123-321/data/set-1234/",
       "type": "Page"
    },
    "target": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    }
}
  

7.3. Pattern 7: Retracting a prior offer

This pattern is used where a prior offer needs to be retracted. Hence, a retraction is about an artefact that is somehow related to the activity in the request notification.

A [JSON-LD] payload MUST contain at least the following properties:

The [JSON-LD] payload SHOULD also contain the following property:

EXAMPLE 18 Springfield library retracts her offer for an image collection to be archived by the national archive

{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:00C2F77A-A7C2-4B95-9D61-5377EA3BA0AE",
    "type": "Undo",
    "published": "2022-12-01T00:55:00Z",
    "summary": "Springfield library undo's offer data/set-1234 for archiving",
    "actor": {
       "id": "https://springfield.library.net/about#us",
       "inbox": "https://springfield.library.net/inbox/",
       "name": "Springfield Library",
       "type": "Organization"
    },
    "origin": {
       "id": "https://imagetool.com/profile/card#i",
       "name": "ImageTool Inc.",
       "type": "Application"
    },
    "inReplyTo":"urn:uuid:8B938492-663B-479C-8431-07F9049B4E5D",
    "context":"https://imagetool.com/customer/123-321/data/set-1234/",
    "object": {
       "id": "urn:uuid:8B938492-663B-479C-8431-07F9049B4E5D",
       "type": "Offer"
    },
    "target": {     
       "id": "https://nationalarchive.org/library/ingest#service",
       "inbox": "https://nationalarchive.org/library/ingest/inbox",
       "name": "National Archives Library Project",
       "type": "Application"
    }
}
  

8. Acknowledgements

Our work is funded by the Andrew W. Mellon Foundation (grant number: 1903-06675).

Conformance

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[FETCH]
Anne van Kesteren. Fetch Standard. Living Standard. URL: https://fetch.spec.whatwg.org/
[FileAPI]
Marijn Kruisselbrink; Arun Ranganathan. File API. 11 September 2019. WD. URL: https://www.w3.org/TR/FileAPI/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119

Informative References

[JSON-LD]
Manu Sporny; Gregg Kellogg; Markus Lanthaler. JSON-LD 1.0. 16 January 2014. REC. URL: https://www.w3.org/TR/json-ld/
[URI]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://tools.ietf.org/html/rfc3986
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/