Event Notifications in Value-Adding Networks

Living Document,

This version:
https://www.eventnotifications.net
Latest published version:
https://www.eventnotifications.net
Previous Versions:
Feedback:
Inline In Spec
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

Overview of the network participants

Figure 1: Overview of the network participants

This specification details a profile for using Linked Data Notifications [LDN] with ActivityStreams2 [AS2] payloads in value-adding networks.

A value-added network, as considered by this specification, is a network in which Web resources, for the purpose of this specification named Artifacts, are made available by nodes in the network, value is added to these Artifacts by other nodes in the network, and LDN+AS2 notifications with that regard are exchanged among network nodes.

The type of web resources that are considered Artifacts in a value-adding network depends on its community of use. For example, in a research communication value-adding network, Artifacts would include research outputs such as preprints, reviewed articles, datasets, workflows, and software that are part of the scholarly record.

A value-adding service applied to an Artifact does not change its content. Rather, the outcome of applying the service, for the purpose of this specification named Service Result, can be associated with the Artifact. It could, for example, be information that an Artifact was made discoverable by a portal; a trusted timestamp for an Artifact; information about a linkage the Artifact is involved in; the creation of a new resource related to the artifact (e.g. an enhanced version, a translation, an archival copy).

Regarding the exchange of these LDN+AS2 notifications, the specification distinguishes between two logical roles Data Node and Service Node:

In order to be able to communicate, each Data Node and Service Node has LDN Sender and LDN Receiver (LDN Inbox) capabilities that are used:

Agents operate on behalf of Data Node and Service Node; they can be humans or machines, individuals or organizations. These Agents exchange LDN notifications, each of which pertains to an Artifact that is hosted by a Data Node.

The intended communication style among Nodes is point-to-point, requiring no centralized hubs. It is push-oriented, with only the relevant Nodes being updated about new information as it becomes available. Interactions among Nodes are necessarily asynchronous because certain notification patterns do not require a response and, in patterns that do, such as requesting a service for an Artifact, the time between a request and the announcement of the Service Result is unpredictable and could range between almost immediate to months.

The communication patterns are action-oriented. The patterns express when an activity was initiated, acknowledged, or yielded a result. Message payloads contain only core information (in most cases [URL] identifiers) to convey in which value-adding activities Data Nodes, Service Nodes, and Artifacts are involved and what the Service Results are. The assumption is that further information about the entities involved is available by using their identifiers in auto-discovery mechanisms. As such, message payloads are typically expressed by reference (i.e. by means of the [URL] of an entity) rather than by value (i.e. by means of a description of an entity).

A common scenario covered by the specification is depicted in Figure 1, which shows, on the dashed lines, prefixed by AS, the AS2 element used in the LDN+AS2 payloads to convey the respective entity involved in the value-adding network:

From the perspective of LDN:

From the perspective of AS2:

2. 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]

3. Document Conventions

Within this document, the following namespace prefix bindings to [URI]-s are used:

Prefix Namespace
rdf http://www.w3.org/1999/02/22-rdf-syntax-ns#
as https://www.w3.org/ns/activitystreams#
ldp http://www.w3.org/ns/ldp#
schema http://schema.org/

When in the textual parts of this document a namespace prefix is used, it should be interpreted with the bindings as stated above. In our examples LDN+AS2 payloads we use JSON-LD as syntax. In our JSON-LD examples we don’t explicity write the prefixes. The @context element in JSON-LD defines a mapping from terms to [URI]-s. We refer to the [JSON-LD] specification for more information about this more concise way of notation.

4. Network entities

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

4.1. Agent

An Agent is an active participant in the network: an Agent performs actions, can be human or machine, individual or organization, and operates on behalf of a Data Node or a Service Node.

4.2. Artifact

An Artifact is a Web resource identified by a [URL] that is made available to the network by a Data Node, and that serves as the main focus of interaction between Agents. An Artifact can be atomic or arbitrary complex. The manner in which Artifacts are organized is outside the scope of this specification and depends on the implementing community.

4.3. Data Node

A Data Node is a network node that makes Artifacts available to the network. A Data Node provides one or more LDN Inboxes via which Agents that operate on behalf of the Data Node can be reached. These LDN Inboxes are set up to receive LDN+AS2 notifications pertaining to the Artifacts that are made available to the network by the Data Node. A Data Node must be identified by a [URL], which preferably is a [WebID]. From this URL, additional information about the Data Node, such as the location of its LDN Inbox(es), can be made discoverable.

4.4. Service Node

A Service Node is a network node that provides value-added services for Artifacts hosted by Data Nodes. A Service Node provides one or more LDN Inboxes via which Agents that operate on behalf of the Service Node can be reached. These LDN Inboxes are set up to receive LDN+AS2 notifications pertaining to Artifacts that are made available to the network by Data Nodes. A Service Node must be identified by a [URL], which preferably is a [WebID]. From this URL, additional information about the Service Node, such as the location of its LDN Inbox(es), can be made discoverable.

4.5. Service Result

A Service Result is the outcome of the provision of a value-added service by a Service Node for an Artifact that is made available to the network by a Data Node. A Service Result can be a Web resource identified by a [URL] or information that is provided inline in an LDN+AS2 notification.

A Service Result that is a Web resource identified by a [URL] can itself become an Artifact when it is made available to the network by a Data Node that, for example, is associated with the Service Node that generated the Service Result. This makes a Service Result available as a new Artifact for which new value-added services can be provided.

5. Properties in LDN+AS2 Notifications

In a value-adding network, LDN notifications are sent from one Agent to another Agent. Notification payloads are expressed using the ActivityStreams 2.0 vocabulary and SHOULD use [JSON-LD] as default syntax, but other RDF syntaxes MAY be used. Each notification describes an AS2 Activity that involves either an Artifact, a Service Result pertaining to an Artifact, or a previous AS2 Activity.

This section describes the properties that are used in the notifications to describe an activity and provides details on their content: the core JSON-LD id and type properties and the AS2 object, origin, target, actor, context, inReplyTo properties.

5.1. JSON-LD id

An LDN+AS2 notification MUST specify an identifier for the activity, expressed in JSON-LD as @id or shortened as id, and its value MUST be a valid [URI]. In case this [URI] is a [URL], it MUST be dereferencable and return a representation of the notification itself. When referring to an activity, its activity identifier MUST be used. Nodes in the network MUST NOT edit or remove the activity identifier when processing LDN+AS2 notifications.

Note that the activity identifier is distinct from the notification identifier, which is the [URL] minted by the LDN Receiver when the LDN+AS2 notification that describes the activity is received in its LDN Inbox. An LDN Receiver may choose to reflect components of the activity identifier in the notification identifier it mints but, in case this happens, network nodes can not infer a relationship between the activity identifier and the notification identifier on this basis.

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].

Alice notifies Bob about the creation of a new Artifact. In the LDN+AS2 payload:
{ 
   "@context": "https://www.w3.org/ns/activitystreams",
   "id": "https://acme.org/events/alice/0F402B08-F676-40EE-9D4B-480B3F985B65",
   "type": "Create",
   "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"
   }
}

5.2. JSON-LD type

An LDN+AS2 notification MUST specify an activity type, expressed in JSON-LD as @type or shortened as type, and its value MUST be the type of AS2 Activity that it describes. Only the subset of AS2 Activity Types shown here are supported:

In addition to these AS2 Activity Types, types ([URI]s) originating from vocabularies chosen by an application domain MAY be specified.

Bob announces that he endorses the publication of Alice by sharing a review. In the LDN+AS2 notification payload:
{ 
   "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      { "schema": "https://schema.org/"}
   ], 
   "id": "urn:uuid:42D2F3DC-0770-4F47-BF37-4F01E0382E32",
   "type": [ "Announce" , "schema:EndorseAction" ],
   "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.3. AS2 object

An LDN+AS2 notification MUST specify an AS2 object, expressed by means of the as:object property. Depending on the activity type, the AS2 object can refer to:

For as:object, one of the core Object Types MUST be expressed. In addition to these Object Types, types ([URI]s) originating from vocabularies chosen by an application domain MAY be specified.

In case the AS2 object is an Artifact, it MUST specify the Artifact’s [URL] and it is RECOMMENDED that this [URL] supports auto-discovery mechanisms (e.g. a typed link in the HTTP Link header) to allow network clients to obtain additional information about the Artifact. Such additional information pertaining to the Artifact MAY also be provided inline as part of the value of the AS2 object.

In case the AS2 object is a Service Result:

In EXAMPLE 1, Alice’s Artifact is the AS2 object and its [URL] https://acme.org/artifacts/alice/five_steps_to_success.html is provided as the value of the object property.
In EXAMPLE 2, Bob’s Service Result is the AS2 object and its [URL] https://infinity.science.com/artifacts/bob/review_123.html is provided as the value of the object property.
Bob announces a linkage between Alice’s Artifact and his review thereof:
{ 
   "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      { "schema": "https://schema.org/"}
   ], 
   "id": "urn:uuid:42D2F3DC-0770-4F47-BF37-4F01E0382E32",
   "type": [ "Announce" , "schema:EndorseAction" ],
   "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": "urn:uuid:98ED7A80-BBF8-4F01-A9CD-AA781F769CCD",
      "type": "Relationship",
      "subject": "https://infinity.science.com/artifacts/bob/review_123.html",
      "relationship": "http://purl.org/spar/cito/reviews",
      "object": "https://acme.org/artifacts/alice/five_steps_to_success.html"
   },
   "target": {     
      "id": "https://orcid.org/0000-0007-01219-312199",
      "inbox": "https://acme.org/inbox/alice",
      "name": "Alice",
      "type": "Person"
   }
}

5.4. AS2 actor, AS2 origin, and AS2 target

An LDN+AS2 notification:

For both as:actor, as:origin, and as:target, one of the core AS2 Actor Types MUST be expressed. In addition to these AS2 Actor Types, types ([URI]s) originating from vocabularies chosen by an application domain MAY be specified.

Both as:actor, as:origin, and as:target SHOULD have an LDN Inbox. The [URL] of the LDN Inbox:

In EXAMPLE 5:

5.5. AS2 context

When sending a notification to a Data Node that pertains to one of the Artifacts it makes available, the LDN+AS2 notification SHOULD include the as:context property and, when included, MUST at least convey the Artifact’s [URL] as its value. This specification accords no specific meaning to the use of as:context for notifications sent to a Service Node.

For as:context, one of the core Object Types MAY be expressed. In addition to these Object Types, types ([URIs]) originating from vocabularies chosen by an application domain MAY be specified.

In EXAMPLE 2 and EXAMPLE 5, Bob sends notifications about Service Results that pertain to Alice’s Artifact. The [URL] https://acme.org/artifacts/alice/five_steps_to_success.html of that Artifact is provided in the as:context property of these notifications.
In EXAMPLE 1, Alice sends a notification announcing the availability of her Artifact. The [URL] of the Artifact is provided using the as:object property whereas as:context is not used because the announcement does not pertain to an Artifact that is made available at the recipient’s end.

5.6. AS2 inReplyTo

An LDN+AS2 notification that is sent in response to a previously received notification, MUST include the as:inReplyTo property, and its value MUST be the activity identifier (value of the id property) of the previous notification. For such a notification, the as:object property also reflects the activity identifier of the previous notification but can include additional information, see § 5.3 AS2 object.

Examples are provided in § 6.2.2 Service Node provides Service Result and § 6.3.2 Service Node provides Service Result.

6. Network communication patterns

In a value-adding network, Nodes, in particular the Agents operating on behalf of Nodes, communicate by sending LDN+AS2 notifications to each other. These notifications are delivered to LDN Inboxes that are made available by Data Nodes and Service Nodes for the benefit of Agents that manage Artifacts and service provision, respectively.

Depending on the type of interaction an Agent is a sender or receiver of messages. This specification describes the following communication patterns between the Nodes in the network: one-way communication and request-response communication patterns. They are detailed in the remainder of this section.

6.1. One-way communication patterns

In the one-way communication patterns, notifications express facts such as “I performed this activity on an Artifact”. There is no expectation that such notifications yield a response.

In general, in a one-way communication, a Node provides unsolicited information to another Node. Various one-way patterns exist:

6.1.1. Data Node to Service Node

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

Figure 2: A Data Node sends a notification about an Artifact to a Service Node.

The one-way Data Node to Service Node pattern is used for sending unsolicited information pertaining to an Artifact to another Agent in the network. These cases that are considered:

For such a notification:

Table 1: One-way Data Node to Service Node requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Optional as:origin, as:target
Not used as:context , as:inReplyTo

The ACME Research Institute (Data Node) notifies Infinity Science (Service Node) in a one-way pattern 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",
    "actor": {
       "id": "https://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute",
       "type": "Organization"
    },
    "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://infinity.science.com/profile/card#us",
      "inbox": "https://infinity.science.com/inbox/",
      "name": "Infinity Science",
      "type": "Organization"
   }
}

6.1.2. Service Node to Data Node

Data
Node
Data...
Notification
Notification
object
object
Service
Result
Service...
Artifact
Artifact
context
context
Service
Node
Service...
Text is not SVG - cannot display

Figure 3: A Service Node sends a notification about a Service Result pertaining to an Artifact to a Data Node.

The one-way Service Node to Data Node pattern is used to send an unsolicited notification about a Service Result pertaining to an Artifact to an Agent at the end of the Data Node that makes the Artifact available.

For such a notification:

Table 2: One-way Service Node to Data Node requirements.
Requirements Properties
Required @id, @type, as:actor, as:context, as:object
Optional as:origin, as:target
Not used as:inReplyTo
The Fairfield City Repository (Service Node) notifies ACME Research Institute (Data Node) in a one-way pattern about the creation of an archival copy Service Result https://darwin.fairfield.org/objects/317831-13210 related to ACME’s Artifact http://acme.org/artifacts/alice/five_steps_to_success.html.
{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:239FD510-03F4-4B56-B3A0-0D3B92F3826D",
    "type": "Announce",
    "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://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute ",
       "type": "Organization"
    }
  }

6.1.3. Service Node to Service Node

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

Figure 4: Service Node A sends a notification about a Service Result pertaining to an Artifact of some Data Node to another Service Node B.

The one-way Service Node to Service Node pattern is used to forward an unsolicited Service Result from one Service Node to another Service Node. An Agent operating on behalf of the sending Service Node volunteers a Service Result by sending a notification to an Agent at the end of the receiving Service Node. The Service Result is the outcome of the provision of a service for an Artifact that is made available by a Data Node.

For such a notification:

Table 3: One-way Service Node to Service Node requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Optional as:context, as:origin, as:target
Not used as:inReplyTo
The Fairfield City Repository (Service Node) notifies the Arsip Nasional Republik Indonesia (Service Node) in a one-way pattern about the creation of an archival copy Service Result https://darwin.fairfield.org/objects/317831-13210 of an Artifact at the ACME Research Institute (Data Node).
{ 
    "@context": "https://www.w3.org/ns/activitystreams",
    "id": "urn:uuid:239FD510-03F4-4B56-B3A0-0D3B92F3826D",
    "type": "Announce",
    "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://anri.go.id/profile/card#us",
       "inbox": "https://anri.go.id/inbox/",
       "name": "Arsip Nasional Republik Indonesia",
       "type": "Organization"
    }
  }

6.2. Request-response: Data Node to Service Node

The request-response communication pattern between Data Node and Service Node entails a more elaborate back and forth communication regarding the provision, by a Service Node, of a value-added service for an Artifact that is made available by a Data Node. In a request-response communication regarding the provision of a service, notifications can be exchanged between Nodes over time spans that could be near immediate but could also span days, weeks, or even months. The manner in which a service is provided is not in scope of this specification. The aspects that are considered are only whether a Service Node is willing to provide a requested service or not, and if so, what the Service Result is.

In general, this request-response pattern is transactional. The Data Node that initiates the communication, expects a reply from the Service Node. The overall information flow in a request-response communication is as follows:

6.2.1. Data Node requests service

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

Figure 5: A Data Node sends a notification with activity type as:Offer to a Service Node as a means to request a value-added service for one of its Artifacts.

The request-response pattern between a Data Node and a Service Node starts when an Agent operating on behalf of a Data Node sends a notification to an Agent operating at the end of a Service Node asking for the provision of a service for an Artifact that is made available by the Data Node.

For such a notification:

Table 4: Request-response Data Node requests service requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Optional as:origin, as:target
Not used as:context , as:inReplyTo
The ACME Research Institute (Data Node) notifies the Data Archive XYZ (Service Node) in a request-response pattern about the Artifact http://acme.org/artifacts/alice/data-set-2022-01-19.zip on ACME’s system they want to Offer for archivation.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "type": "Offer",
    "actor": {
       "id": "https://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute",
       "type": "Organization"
    },
    "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": [ "Document" , "schema:Dataset" ]
    },
    "target": {     
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    }
  }

6.2.2. Service Node provides Service Result

Data node
Data node
Notification
Notification
Artifact
Artifact
context
context
Service
Node
Service...
Service
Result
Service...
object
object
Text is not SVG - cannot display

Figure 6: The Service Node has a Service Result available pertaining to the Artifact on the Data Node. The Service Node sends an Announce notification to the Data Node about this fact.

The request-response pattern between a Data Node and a Service Node completes when an Agent operating on behalf of a Service Node sends a notification to an Agent operating at the end of a Data Node conveying the Service Result for a service that was previously requested.

For such a notification:

Table 5: Request-response Service Node provides Service Result requirements.
Requirements Properties
Required @id, @type, as:actor, as:object, as:inReplyTo
Recommended as:context
Optional as:origin, as:target
The Data Archive XYZ (Service Node) notifies the ACME Research Institute (Data Node) in a request-response pattern that it announces a new Service Result pertaining to ACME’s Artifact http://acme.org/artifacts/alice/data-set-2022-01-19.zip.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:ED0E06DA-4294-43C0-8E87-800558E4045B",
    "type": "Announce",
    "actor": {
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "inReplyTo" : "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495" ,
    "context" : "http://acme.org/artifacts/alice/data-set-2022-01-19.zip" ,
    "object": {
        "id": "urn:uuid:CF21A499-1BDD-4B59-984A-FC94CF6FBA86",
        "type": "Relationship",
        "subject": "http://acme.org/artifacts/alice/data-set-2022-01-19.zip",
        "relationship": "https://www.iana.org/memento",
        "object": "https://data.archive.xyz.net/data/memento/21daF1921"
     },
    "target": {     
       "id": "https://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute",
       "type": "Organization"
    }
  }

6.2.3. Service Node acknowledges a service request

Data node
Data node
Notification
Notification
Artifact
Artifact
context
context
Service
Node
Service...
previous
Notification
previous...
object
object
Text is not SVG - cannot display

Figure 7: A Service Node optionally acknowledges a previously sent Offer that was sent by a Data Node.

An Agent operating on behalf of a Service Node can send a notification to an Agent operating at the end of a Data Node to acknowledge the receipt of a service request and to indicate whether or not the service will actually be provided.

For such a notification:

Table 6: Request-response Service Node acknowledges a service request requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Recommended as:context, as:inReplyTo
Optional as:origin, as:target
The Data Archive XYZ (Service Node) notifies the ACME Research Institute (Data Node) in a request-response pattern that it accepts the offer ACME sent in a previous activity notification.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:9C0ED771-B7F3-4A50-8A92-72DF63215BCB",
    "type": "Accept",
    "actor": {
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "inReplyTo" : "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495" ,
    "context" : "http://acme.org/artifacts/alice/data-set-2022-01-19.zip" ,
    "object": {
        "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
        "type": "Offer",
        "actor": {
           "id": "https://acme.org/profile/card#us",
           "inbox": "https://acme.org/inbox/",
           "name": "ACME Research Institute",
           "type": "Organization"
        },
        "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": [ "Document" , "schema:Dataset" ]
        },
        "target": {     
           "id": "https://data.archive.xyz.net/",
           "inbox": "https://data.archive.xyz.net/inbox/",
           "name": "Data Archive XYZ",
           "type": "Organization"
        }
    },
    "target": {     
       "id": "https://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute",
       "type": "Organization"
    }
  }
The Data Archive XYZ (Service Node) notifies the ACME Research Institute (Data Node) in a request-response pattern that it rejects the offer ACME sent in a previous activity notification.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:ED4CB09E-F74C-44E8-AA0D-BA74CDE0CDC7",
    "type": "Reject",
    "actor": {
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "inReplyTo" : "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495" ,
    "context" : "http://acme.org/artifacts/alice/data-set-2022-01-19.zip" ,
    "object": {
        "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
        "type": "Offer",
        "actor": {
           "id": "https://acme.org/profile/card#us",
           "inbox": "https://acme.org/inbox/",
           "name": "ACME Research Institute",
           "type": "Organization"
        },
        "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": [ "Document" , "schema:Dataset" ]
        },
        "target": {     
           "id": "https://data.archive.xyz.net/",
           "inbox": "https://data.archive.xyz.net/inbox/",
           "name": "Data Archive XYZ",
           "type": "Organization"
        }
    },
    "target": {     
       "id": "https://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute",
       "type": "Organization"
    }
  }

6.2.4. Data Node cancels prior service request

Data node
Data node
Notification
Notification
Service
Node
Service...
previous
Notification
previous...
object
object
Text is not SVG - cannot display

Figure 8: Data Node sends a notification with activity type as:Undo to a Service Node canceling its previous Offer notification.

An Agent operating on behalf of a Data Node can send a notification to an Agent operating at the end of a Service Node requesting to cancel a previous request for the provision of a service for an Artifact that is made available by the Data Node.

For such a notification:

Table 7: Request-response Service Node cancels prior service request requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Optional as:origin, as:target
Not used as:context, as:inReplyTo
The ACME Research Institute (Data Node) sends a cancelation to Data Archive XYZ (Service Node) of the Offer that was sent in Example 12.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:70892B92-001E-40C8-B4E8-B70BBC334419",
    "type": "Undo",
    "actor": {
       "id": "https://acme.org/profile/card#us",
       "inbox": "https://acme.org/inbox/",
       "name": "ACME Research Institute",
       "type": "Organization"
    },
    "origin": {
       "id": "https://acme.org/system",
       "name": "ACME Research Institute System",
       "type": "Application"
    },
    "object": {
        "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
        "type": "Offer",
        "actor": {
            "id": "https://acme.org/profile/card#us",
            "inbox": "https://acme.org/inbox/",
            "name": "ACME Research Institute",
            "type": "Organization"
        },
        "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": [ "Document" , "schema:Dataset" ]
        },
        "target": {     
            "id": "https://data.archive.xyz.net/",
            "inbox": "https://data.archive.xyz.net/inbox/",
            "name": "Data Archive XYZ",
            "type": "Organization"
        }
    },
    "target": {     
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    }
  }

6.3. Request-response: Service Node to Service Node

Cases exist in which a Service Node needs the help of another Service Node to provide value-added services for an Artifact that is made available by a Data Node. In such cases, the former Service Node can forward a Service Result to the latter Service Node to request further services.

The request-response Service Node to Service Node pattern is used by an Agent operating on behalf of a Service Node to invoke a service from another Service Node. In this request-response communication, notifications can be exchanged between the Service Nodes over time spans that could be near immediate but could also span days, weeks, or even months. The manner in which the Service Node that receives the service request generates its Service Result is not in scope of this specification. The aspects that are considered are only whether that Service Node is willing to provide a requested service or not, and if so, what the Service Result is.

In general, this request-response pattern is transactional. The Service Node that initiates the communication, expects a reply from the Service Node that receives the service request. The overall information flow in this request-response communication is as follows:

6.3.1. Service Node requests service

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

Figure 9: Service Node A sends an Offer to Service Node B requesting a value-added service for a Service Result pertaining to an Artifact on a Data Node. The Offer could have been triggered by a Data Node requesting a value-added service from Service Node A that Service Node A forwards to Service Node B.

The request-response pattern between two Service Nodes starts when an Agent operating on behalf of a Service Node A sends a notification to an Agent operating at the end of a Service Node B asking for the provision of a service for a Service Result generated by Service Node A.

For such a notification:

Table 8: Request-response Service Node request service requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Optional as:origin, as:target
Not used as:context, as:inReplyTo
The Data Archive XYZ (Service Node A) received an Offer from ACME Research Institute (Data Node). Service Node A decides to delegate the offer to their Australian office Data Archive XYZ Australia (Service Node B).
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
    "type": "Offer",
    "actor": {
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "object": {
         "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
         "type": "Offer",
         "actor": {
            "id": "https://acme.org/profile/card#us",
            "inbox": "https://acme.org/inbox/",
            "name": "ACME Research Institute",
            "type": "Organization"
         },
         "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": [ "Document" , "schema:Dataset" ]
         },
         "target": {     
            "id": "https://data.archive.xyz.net/",
            "inbox": "https://data.archive.xyz.net/inbox/",
            "name": "Data Archive XYZ",
            "type": "Organization"
         }
    },
    "target": {     
       "id": "https://data.archive.xyz.au/",
       "inbox": "https://data.archive.xyz.au/inbox/",
       "name": "Data Archive XYZ (Australia Office)",
       "type": "Organization"
    }
  }

6.3.2. Service Node provides Service Result

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

Figure 10: Service Node B has a Service Result available pertaining to the Service Result on Service Node A. The Service Node B sends an Announce notification to Service Node A about this fact.

The request-response pattern between Service Node A and a Service Node B completes when an Agent operating on behalf of a Service Node B sends a notification to an Agent operating at the end of Service Node A conveying the Service Result generated by Service Node B in response to a request from Service Node A.

For such a notification:

Table 9: Request-response Service Node provides Service Result requirements.
Requirements Properties
Required @id, @type, as:actor, as:object, as:inReplyTo
Recommended as:context
Optional as:origin, as:target
Data Archive XYZ Australia (Service Node B) notifies Data Archive XYZ (Service Node A) in a request-response pattern that it announces a new Service Result pertaining to Service Node A Service Result urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:7222149D-F2A1-46C5-9E5C-32E1C27E6F93",
    "type": "Announce",
    "actor": {
       "id": "https://data.archive.xyz.au/",
       "inbox": "https://data.archive.xyz.au/inbox/",
       "name": "Data Archive XYZ (Australia Office)",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "context": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "inReplyTo": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
    "object": {
        "id": "urn:uuid:CF21A499-1BDD-4B59-984A-FC94CF6FBA86",
        "type": "Relationship",
        "subject": "http://acme.org/artifacts/alice/data-set-2022-01-19.zip",
        "relationship": "https://www.iana.org/memento",
        "object": "https://data.archive.xyz.net/data/memento/21daF1921"
    },
    "target": {     
        "id": "https://data.archive.xyz.net/",
        "inbox": "https://data.archive.xyz.net/inbox/",
        "name": "Data Archive XYZ",
        "type": "Organization"
    }
  }

6.3.3. Service Node acknowledges a service request

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

Figure 11: Service Node B optionally acknowledges an offer that was previously sent by Service Node A.

An Agent operating on behalf of Service Node A can send a notification to an Agent operating at the end of Service Node B to acknowledge the receipt of a service request and to indicate whether or not the service will actually be provided.

For such a notification:

Table 10: Request-response Service Node acknowledges a service request requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Recommended as:context, as:inReplyTo
Optional as:origin, as:target
Data Archive XYZ Australia (Service Node B) sends an Accept to Data Archive XYZ (Service Node A) of the Offer that was sent in Example 17.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:69694A28-5E69-469E-9273-D7E706BBAA91",
    "type": "Accept",
    "actor": {
       "id": "https://data.archive.xyz.au/",
       "inbox": "https://data.archive.xyz.au/inbox/",
       "name": "Data Archive XYZ (Australia Office)",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "context": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "inReplyTo": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
    "object": {
        "id": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
        "type": "Offer",
        "actor": {
           "id": "https://data.archive.xyz.net/",
           "inbox": "https://data.archive.xyz.net/inbox/",
           "name": "Data Archive XYZ",
           "type": "Organization"
        },
        "origin": {
           "id": "https://data.archive.xyz.net/system",
           "name": "XYZ Archiving Department",
           "type": "Application"
        },
        "object": {
             "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
             "type": "Offer",
             "actor": {
                "id": "https://acme.org/profile/card#us",
                "inbox": "https://acme.org/inbox/",
                "name": "ACME Research Institute",
                "type": "Organization"
             },
             "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": [ "Document" , "schema:Dataset" ]
             },
             "target": {     
                "id": "https://data.archive.xyz.net/",
                "inbox": "https://data.archive.xyz.net/inbox/",
                "name": "Data Archive XYZ",
                "type": "Organization"
             }
        },
        "target": {     
           "id": "https://data.archive.xyz.au/",
           "inbox": "https://data.archive.xyz.au/inbox/",
           "name": "Data Archive XYZ (Australia Office)",
           "type": "Organization"
        }
    },
    "target": {     
        "id": "https://data.archive.xyz.net/",
        "inbox": "https://data.archive.xyz.net/inbox/",
        "name": "Data Archive XYZ",
        "type": "Organization"
    }
  }
Data Archive XYZ Australia (Service Node B) notifies the Data Archive XYZ (Service Node A) in a request-response pattern that it rejects the offer sent in a previous activity notification.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:DB906BC3-09AA-4B6D-AA46-025E93BEA2E9",
    "type": "Reject",
    "actor": {
        "id": "https://data.archive.xyz.au/",
        "inbox": "https://data.archive.xyz.au/inbox/",
        "name": "Data Archive XYZ (Australia Office)",
        "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "context": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
    "inReplyTo": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
    "object": {
        "id": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
        "type": "Offer",
        "actor": {
           "id": "https://data.archive.xyz.net/",
           "inbox": "https://data.archive.xyz.net/inbox/",
           "name": "Data Archive XYZ",
           "type": "Organization"
        },
        "origin": {
           "id": "https://data.archive.xyz.net/system",
           "name": "XYZ Archiving Department",
           "type": "Application"
        },
        "object": {
             "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
             "type": "Offer",
             "actor": {
                "id": "https://acme.org/profile/card#us",
                "inbox": "https://acme.org/inbox/",
                "name": "ACME Research Institute",
                "type": "Organization"
             },
             "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": [ "Document" , "schema:Dataset" ]
             },
             "target": {     
                "id": "https://data.archive.xyz.net/",
                "inbox": "https://data.archive.xyz.net/inbox/",
                "name": "Data Archive XYZ",
                "type": "Organization"
             }
        },
        "target": {     
           "id": "https://data.archive.xyz.au/",
           "inbox": "https://data.archive.xyz.au/inbox/",
           "name": "Data Archive XYZ (Australia Office)",
           "type": "Organization"
        }
    },
    "target": {     
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    }
  }

6.3.4. Service Node cancels prior service request

Notification
Notification
Service
Node
Service...
Service
Node
Service...
A
A
B
B
previous
Notification
previous...
object
object
Data node
Data node
Artifact
Artifact
Text is not SVG - cannot display

Figure 12: Service Node A sends a notification of type as:Undo to Service Node B cancelling its previous Offer notification.

An Agent operating on behalf of Service Node A can send a notification to an Agent operating at the end of a Service Node B requesting to cancel a previous request for the provision of a service for a Service Result that was generated by the Data Node A.

For such a notification:

Table 11: Request-response Service Node cancels prior service request requirements.
Requirements Properties
Required @id, @type, as:actor, as:object
Optional as:origin, as:target
Not used as:context, as:inReplyTo
Data Archive XYZ (Service Node A) sends a cancelation to Data Archive XYZ Australia (Service Node B) of the Offer that was sent in Example 17.
{ 
    "@context": [ 
      "https://www.w3.org/ns/activitystreams" ,
      {"schema": "https://schema.org/"}
    ], 
    "id": "urn:uuid:8D9B8557-C9F2-4F65-9697-662B58F9FCDF",
    "type": "Undo",
    "actor": {
       "id": "https://data.archive.xyz.net/",
       "inbox": "https://data.archive.xyz.net/inbox/",
       "name": "Data Archive XYZ",
       "type": "Organization"
    },
    "origin": {
       "id": "https://data.archive.xyz.net/system",
       "name": "XYZ Archiving Department",
       "type": "Application"
    },
    "object": {
        "id": "urn:uuid:CBF81D23-E242-4B6E-9528-0EC6EAB3CA03",
        "type": "Offer",
        "actor": {
           "id": "https://data.archive.xyz.net/",
           "inbox": "https://data.archive.xyz.net/inbox/",
           "name": "Data Archive XYZ",
           "type": "Organization"
        },
        "origin": {
           "id": "https://data.archive.xyz.net/system",
           "name": "XYZ Archiving Department",
           "type": "Application"
        },
        "object": {
             "id": "urn:uuid:6E5FAF88-A7F1-47A4-B087-77345EBFF495",
             "type": "Offer",
             "actor": {
                "id": "https://acme.org/profile/card#us",
                "inbox": "https://acme.org/inbox/",
                "name": "ACME Research Institute",
                "type": "Organization"
             },
             "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": [ "Document" , "schema:Dataset" ]
             },
             "target": {     
                "id": "https://data.archive.xyz.net/",
                "inbox": "https://data.archive.xyz.net/inbox/",
                "name": "Data Archive XYZ",
                "type": "Organization"
             }
        },
        "target": {     
           "id": "https://data.archive.xyz.au/",
           "inbox": "https://data.archive.xyz.au/inbox/",
           "name": "Data Archive XYZ (Australia Office)",
           "type": "Organization"
        }
    },
    "target": {     
       "id": "https://data.archive.xyz.au/",
       "inbox": "https://data.archive.xyz.au/inbox/",
       "name": "Data Archive XYZ (Australia Office)",
       "type": "Organization"
    }
  }

7. Discovery and Description

7.1. LDN Inboxes of network entities

Discovery of an LDN Inbox for the Agent, Artifact, Data Node, and Service Node entities in a Value-Adding Network follows the approach specified in the Linked Data Notifications [LDN] specification. An LDN Sender or LDN Consumer does the following to discover an LDN for one of the aforementioned entities:

In case an Agent, Data Node, or Service Node is identified by a WebID [WebID], the LDN Inbox of the entity can be discovered by means of the WebID Profile Document [WebID] that is returned when issuing an HTTP GET on the WebID. In the RDF representation of that document, the URL of the LDN Inbox is the object of a triple that has the entity’s WebID as its subject and http://www.w3.org/ns/ldp#inbox as its predicate.

7.2. Entity information

Notification payloads in a Value-Adding Network contain only core information (in most cases [URL] identifiers) about an Agent, Artifact, Data Node, or Service Node. The assumption is that further information about these entities is available by using their identifiers in auto-discovery mechanisms. How exactly such information is provided by these entities depends on choices made when deploying a Value-Adding Network instantiation but the overall approaches as described above for the discovery of LDN Inboxes can be used as a guideline.

7.3. Community specific implementation details

Data Nodes and Service Nodes can advertise details regarding the specific application domain of the generic Value-Adding Network specification that they implement, including:

It is up to each application domain to agree upon the manner in which Data/Service Nodes should convey implementation details, but this information can uniformly be discovered, across application domains, as follows:

7.4. Service description of Service Nodes

Each Service Node can advertise the services they offer by means of a Service Description document. Both machine-readable and natural language Service Description documents are permitted and may, for example, include a description of the incoming and outgoing LDN+AS2 notifications that are supported by the LDN Inbox associated with the Service Node. To support discovery of Service Description documents, Service Nodes can make use of existing mechanisms such as the API-Catalog specification. The content of Service Node service descriptions resemble the information that can be provided for an application domain, including supported the AS2 Activity Type, specializations of the generic AS2 types and possible network communication patterns.

8. Serialization of LDN+AS2 notifications

The payload of Event Notifications can be serialized in different formats. In accordance with the [LDN] specification, both Sender and Receiver MUST at least support the JSON-LD 1.0. Other RDF syntaxes such as Turtle MAY be made available as well.

In case of JSON-LD, Senders MAY apply JSON-LD 1.1 frame during serialization in order to provide more predictable JSON-LD payloads. Predictable JSON-LD will ease the implementation of Event Notifications in environments where plain JSON processing is the norm.

The framing of the payloads will produce JSON documents with predictable property names, as long as the right @context is set for the community. JSON implementations should still be aware of the semantic equivalence between a string value and an array of size one with a string value. For instance, "foo" : "bar" and "foo" : [ "bar" ] will both contain for the foo property the same string value.

A JSON-LD 1.1 frame should beware of possible nesting of as:Activity types. For instance, the presence of an as:Offer as object of an as:Accept, as per Example 14, can lead to unexpected JSON documents. Therefore, any frame SHOULD include the activity identifier as top level @id, as illustrated below.

Possible frame that will generate the predictable JSON-LD playload from Example 14.
{
"@context": "https://www.w3.org/ns/activitystreams#",
"@id": "urn:uuid:9C0ED771-B7F3-4A50-8A92-72DF63215BCB"
}

Additionally, namespace prefixes can be passed in the context parameter of the frame to shorten the syntax. These will transform the output to a turtle-like syntax.

{  
   "@context": [
     "https://www.w3.org/ns/activitystreams" ,
     {
"schema": "https://schema.org/",
" ... ": " ... "
}
   ],
  "id": "urn:uuid:9C0ED771-B7F3-4A50-8A92-72DF63215BCB"
}

will result in

{  
   ...
   "type": "schema:Dataset" ,
   ...
}

The framing result of example 14 can be seen in following JSON-LD Playground example

To discover the activity identifier from any notification, while ignoring the nested activities, one can match the expected notification types from § 5.2 JSON-LD type, and then eliminate identifiers from nested activities by, for example, checking whether they occur as objects of as:object .

When sending a notification, Senders SHOULD include the HTTP header content-type in the request with the profile parameter set to https://www.eventnotifications.net, as described in the Content Negotiation by Profile specification. For example, for requests with payloads serialized to JSON-LD, the content-type header should be set to application/ld+json; profile="https://www.eventnotifications.net.

Some communities will use Event Notifications in conjunction with a community-specific profile, e.g., additional vocabularies introduced by the community to further specify activities described in the notification payload. In this case, it is RECOMMENDED to add the profile URI coined by that community to the profile parameter. For example, in the context of the COAR notify project, the content-type header could be set to application/ld+json; profile="https://www.eventnotifications.net https://notify.coar-repositories.org. Note that in case of JSON-LD payloads, the JSON-LD 1.1 specification [recommends to also add the JSON-LD document profile, which is identified by an URI starting with http://www.w3.org/ns/json-ld, to the profile parameter](https://www.w3.org/TR/json-ld11/#iana-considerations).

9. LDN Inbox error handling

The Linked Data Notifications [LDN] specification prescribes the nature of HTTP responses for cases when a notification is successfully received in an Inbox. But it also specifies that an Inbox can reject notifications when they violate constraints that are applicable to the Inbox. A constraint to an Inbox can be expressed by a constraint document; the URL of each applicable constraint document can be provided as the target of a link with the http://www.w3.org/ns/ldp#constrainedBy link relation type that is provided in any HTTP response of the Inbox, in the HTTP Link header and/or the response body. As per [LDP], both machine-readable and natural language constraint documents are permitted although the former are preferred because they facilitate better client interaction.

The following apply regarding constraints on Inboxes provided by Data/Service Nodes:

The below example shows the response to POSTing an event notification to the Inbox of a Data/Service Node for a case in which the notification violates a notification payload constraint expressed by the Inbox:
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
Content-Language: en
Link: <https://example.org/constraints/shacl1.jsonld>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Link: <https://example.org/constraints/constraint1.html>; rel="http://www.w3.org/ns/ldp#constrainedBy"

{
 "@context": { 
      "type" : "@type" ,
      "title": "http://purl.org/dc/terms/title",
      "status": "http://www.w3.org/2011/http#statusCodeNumber" 
 },
 "type": "https://example.org/constraints/shacl1.jsonld",
 "title": "This notification message is not a valid description: Needed an actor.inbox field but found none.",
 "status": 400
}
The below example shows a similar response to POSTing an event notification to the Inbox of a Data/Service Node for a case in which the notification violates the registration requirement constraint expressed by the Inbox:
HTTP/1.1 401 Unauthorized
Content-Type: application/problem+json
Content-Language: en
Link: <https://example.org/constraints/shacl1.jsonld>; rel="http://www.w3.org/ns/ldp#constrainedBy"
Link: <https://example.org/constraints/constraint1.html>; rel="http://www.w3.org/ns/ldp#constrainedBy"

{
 "@context": { 
      "type" : "@type" ,
      "title": "http://purl.org/dc/terms/title",
      "status": "http://www.w3.org/2011/http#statusCodeNumber" 
 },
 "type": "https://example.org/constraints/constraint1.html",
 "title": "Agents musty register prior to posting to this Inbox",
 "status": 401
}

10. Service description of LDN Targets

TODO

11. Acknowledgements

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

References

Normative References

[AS2]
James M Snell; Evan Prodromou. Activity Streams 2.0. W3C Recommendation 23 May 2017. URL: https://www.w3.org/TR/activitystreams-core/

Informative References

[DX-PROF-CONNEG]
Lars G. Svensson; Nicholas Car. Content Negotiation by Profile. URL: https://w3c.github.io/dxwg/connegp/
[JSON-LD]
Manu Sporny; Gregg Kellogg; Markus Lanthaler. JSON-LD 1.0. 3 November 2020. REC. URL: https://www.w3.org/TR/json-ld/
[JSON-LD11]
Gregg Kellogg; Pierre-Antoine Champin; Dave Longley. JSON-LD 1.1. URL: https://w3c.github.io/json-ld-syntax/
[JSON-LD11-FRAMING]
Dave Longley; Gregg Kellogg; Pierre-Antoine Champin. JSON-LD 1.1 Framing. URL: https://w3c.github.io/json-ld-framing/
[LDN]
Sarven Capadisli; Amy Guy. Linked Data Notifications. URL: https://linkedresearch.org/ldn/
[LDP]
Steve Speicher; John Arwe; Ashok Malhotra. Linked Data Platform 1.0. URL: https://www.w3.org/2012/ldp/hg/ldp.html
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://datatracker.ietf.org/doc/html/rfc2119
[SHACL]
Holger Knublauch; Dimitris Kontokostas. Shapes Constraint Language (SHACL). URL: https://w3c.github.io/data-shapes/shacl/
[URI]
T. Berners-Lee; R. Fielding; L. Masinter. Uniform Resource Identifier (URI): Generic Syntax. January 2005. Internet Standard. URL: https://www.rfc-editor.org/rfc/rfc3986
[URL]
Anne van Kesteren. URL Standard. Living Standard. URL: https://url.spec.whatwg.org/
[WebID]
Andrei Sambra; Henry Story; Tim Berners-Lee. WebID 1.0. Editor’s Draft. URL: https://dvcs.w3.org/hg/WebID/raw-file/tip/spec/identity-respec.html

Issues Index

TODO