Published

Repository Announces Relationship workflow

Key (colour coding): a repository another repository notification
flowchart LR
classDef left_node fill:#f7d878;
classDef right_node fill:#aec9d3;
classDef notify fill:#e6c5d4;
1@{shape: circle, label: "1 Initiate"}
1 --> 2
class 1 left_node;
style 2 stroke-width:3px,stroke: #555
2@{shape: doc, label: "2 Announce
Relationship
"}
2 --> 3
class 2 notify;
3@{shape: rect, label: "3 Process
Announcement
"}
class 3 right_node;

Step 2: Announce Relationship

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

The repository announces the relationship with the remote resource

Properties

@context

@context is REQUIRED. It takes an array of URIs which MUST include:

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

and MUST include ONE of the following:

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

actor

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

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

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

context

context is OPTIONAL. In this example, this identifies the resource on the target which is the object of the relationship expressed as a "triple" in the object. Note that, therefore, the value of the id in the context MUST be the same as the value of the as:object in the "triple". When present, it:

  • MUST have an id which MUST be the HTTP URI of the "landing page" for the resource.
  • MAY have a type describing the resource, which MUST include an Activity Streams 2.0 object type, and SHOULD include the value sorg:AboutPage.
  • MAY have an ietf:cite-as which contains the persistent HTTP URI (sometimes called the "PID") which is to be used to cite or link to the resource.
  • MAY have an ietf:item containing the details of the actual content resource. When present, the ietf:item:
    • MUST have an id containing the HTTP URI of the content file for the resource.
    • MUST have a type describing the resource, which MUST include an Activity Streams 2.0 object type, and SHOULD include a value from schema.org.
    • MUST have a mediaType which contains the MIME Type of the content file.

id

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

object

object is REQUIRED. This describes the relationship which is being announced. It:

  • MUST have an id which contains the URI for the relationship with the target-hosted resource
  • MUST have a type describing the relationship, which MUST include an Activity Streams 2.0 object type, and MAY include other values.
  • MUST have a 'triple' describing the relationship, in the form:
    • as:subject: containing the URI for the local resource
    • as:relationship: containing a relationship URI
    • as:object: containing the URI for the remote resource

origin

origin is REQUIRED. It describes the system which has sent the notification. It:

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

target

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

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

type

type is REQUIRED. The type of this activity MUST include the values:

  • Announce
  • coar-notify:RelationshipAction

Example JSON-LD Payload

{
  "@context": [
    "https://www.w3.org/ns/activitystreams",
    "https://coar-notify.net"
  ],
  "actor": {
    "id": "https://research-organisation.org",
    "name": "Research Organisation",
    "type": "Organization"
  },
  "context": {
    "id": "https://another-research-organisation.org/repository/datasets/item/201203421/",
    "ietf:cite-as": "https://doi.org/10.5555/999555666",
    "ietf:item": {
      "id": "https://another-research-organisation.org/repository/datasets/item/201203421/data_archive.zip",
      "mediaType": "application/zip",
      "type": [
        "Object",
        "sorg:Dataset"
      ]
    },
    "type": [
      "Page",
      "sorg:AboutPage"
    ]
  },
  "id": "urn:uuid:94ecae35-dcfd-4182-8550-22c7164fe23f",
  "object": {
    "as:object": "https://another-research-organisation.org/repository/datasets/item/201203421/",
    "as:relationship": "http://purl.org/vocab/frbr/core#supplement",
    "as:subject": "https://research-organisation.org/repository/item/201203/421/",
    "id": "urn:uuid:74FFB356-0632-44D9-B176-888DA85758DC",
    "type": "Relationship"
  },
  "origin": {
    "id": "https://research-organisation.org/repository",
    "inbox": "https://research-organisation.org/inbox/",
    "type": "Service"
  },
  "target": {
    "id": "https://another-research-organisation.org/repository",
    "inbox": "https://another-research-organisation.org/inbox/",
    "type": "Service"
  },
  "type": [
    "Announce",
    "coar-notify:RelationshipAction"
  ]
}