Summary of PCI Endorsement workflow discussion

[paulwalk]

PCI Endorsement workflow discussion

These notes are from a call (2024-09-12) between: Olivier Fambon, Richard Jones, Stefano Maffei, Adan Roman, Raphaël Tournoy, Paul Walk & Sean Wiseman

Notes by Paul Walk

Preamble

It has become clear that there is some confusion regarding the COAR Notify workflow for PCI. This has been revised several times - the latest draft has come from discussion with Olivier and Raphael primarily.
However - as Stefano has pointed out - there is an existing DSpace implementation, together with the one which Adan has just finished implementing with CSIC.
Stefano has detailed some discrepancies¹
In addition, Cottage Labs are just about to start working on a Zenodo implementation of the PCI workflow.
So, there are a few questions that I think need some urgent attention:

1. What is the actual workflow being supported by PCI? Is there more than one?
2. What is the actual PCI workflow supported by DSpace? Are there different versions for DSpace 7 & 8?

Separately from this, Richard pointed out that "Accept notification does not specify object in docs or example, but object is a required field"²

Decisions

1. Versioning of the specification

The lack of versioning of the specification is a problem. This is understood but it has proven difficult to know how and what to version exactly. However, recent discussions have clarified this and an approach is being attempted now. This will be described and shared for comment very soon.
One thing we have decided is that it is necessary to version the patterns and the workflows separately.

We will reinstate older versions of the patterns and workflow as "version 1" - this is so that the existing implementations (notably the DSpace 8 codebase) can refer to the version of the Notify specification that they support.

2. Use of TentativeReject

The TentativeReject will be re-introduced to the specification. It was previously removed because it was thought to be unnecessary. This change will not affect any existing implementations. However, the refactored PCI Endorsement workflow (see below) will make use of this type. As this type is from the existing Activity Vocabulary³ used by Activity Streams 2.0,⁴ this can be used immediately.

3. The requirement of object in all notifications

The COAR Notify Editorial Board discussed this issue and concluded that all COAR Notify payload must contain an object.

4. Use of object in Accept, TentativeAccept, Reject or TentativeReject notifications

We noted that all notifications must contain an object. Currently, the Accept and Reject patterns do not have an object which is a mistake. In the case of Accept and Reject patterns, the object should contain the entire Offer notification that the Accept or Reject refers to. This means that the details of the original artefact that was being "offered" are included. Example:

{
    "@context": [
        "https://www.w3.org/ns/activitystreams",
        "https://purl.org/coar/notify"
    ],
    "id": "urn:uuid:4fb3af44-d4f8-4226-9475-2d09c2d8d9e0",
    "inReplyTo": "urn:uuid:0370c0fb-bb78-4a9b-87f5-bed307a509dd",
    "object": {
        "actor": {
            "id": "mailto:josiah.carberry@example.com",
            "name": "Josiah Carberry",
            "type": "Person"
        },
        "id": "urn:uuid:0370c0fb-bb78-4a9b-87f5-bed307a509dd",
        "object": {
            "id": "https://research-organisation.org/repository/preprint/201203/421/",
            "ietf:cite-as": "https://doi.org/10.5555/12345680",
            "ietf:item": {
                "id": "https://research-organisation.org/repository/preprint/201203/421/content.pdf",
                "mediaType": "application/pdf",
                "type": [
                    "Article",
                    "sorg:ScholarlyArticle"
                ]
            },
            "type": "sorg:AboutPage"
        },
        "origin": {
            "id": "https://research-organisation.org/repository",
            "inbox": "https://research-organisation.org/inbox/",
            "type": "Service"
        },
        "target": {
            "id": "https://https://peercommunityin.org",
            "inbox": "https://peercommunityin.org/inbox/",
            "type": "Service"
        },
        "type": [
            "Offer",
            "coar-notify:EndorsementAction"
        ]
    },
    "origin": {
        "id": "https://generic-service.com/system",
        "inbox": "https://generic-service.com/system/inbox/",
        "type": "Service"
    },
    "target": {
        "id": "https://some-organisation.org",
        "inbox": "https://some-organisation.org/inbox/",
        "type": "Organization"
    },
    "type": "Reject"
}

5. Refactored PCI Endorsement Workflow

The current draft of this workflow is on the Notify website⁵
We have agreed the following:

1. For "rejections" we will differentiate using the following two Activity Streams types:
   1. Reject: this is used to completely & finally reject the offer. No further activities related to the Offer that has been rejected will be welcomed by either party.
   2. TentativeReject: this is used by PCI to indicate that no endorsement is forthcoming, but that PCI will consider a "re-submission" following revisions of the artefact being offered for endorsement. The communication about what revisions are required happens via email outside of the COAR Notify exchange. In either case, the object contains the full Offer being rejected (as in example above).
2. The Request Endorsement notification (2) may optionally include an inReplyTo which will reference a previous notification with type TentativeReject. This facilitates the re-submission of a revised offer. It is not permitted to make a Request Endorsement Offer inReplyTo a previous rejection with type Reject .
3. The possible iterations (loops) in this workflow will be indicated in the flow-diagram which has already been added to the documentation, and will be described in text in the "swim lanes".

6. Use of RFC 2119

An earlier version of the documentation made use of the IETF's RFC 2119⁶ convention for indicating requirement levels in standards and specifications. The COAR Notify Editorial Board previously decided to remove this level of specificity. However, the recent experience of implementors of COAR Notify has strongly suggested this approach would be beneficial.⁷

Github issues addressed by these decisions

• Figure out if/how to apply versioning to the Notify Protocol
• Document PCI workflow
• Uncertainty as to the "required" status of some top-level fields
• "Required" status of sub fields in object and context fields
• Accept notification does not specify object in docs or example, but object is a required field
• Changes in Notify protocol after DSpace implementation

Next steps

I propose the following steps to reconcile all of the above:

1. Introduce versioning for the COAR Notify documentation (patterns and workflows)
2. Document the previous versions of the patterns & workflows that were implemented in DSpace 8.
3. Add a new pattern for TentativeReject (although this may be actually a case of re-introducing something that was previously removed from the specification)
4. Update the documentation to use more precise RFC 2119 language.
5. Update the PCI Endorsement workflow.
6. Review all of the above, including checking that existing implementations of the PCI workflow conform to the revised specification
7. Consider what changes (if any) need t be made to the DSpace 8 codebase

---

Footnotes

1. https://github.com/coar-notify/notify.coar-repositories.org/issues/25 ↩

2. https://github.com/coar-notify/notify.coar-repositories.org/issues/27 ↩

3. https://www.w3.org/TR/activitystreams-vocabulary/#dfn-tentativereject ↩

4. https://www.w3.org/TR/activitystreams-core ↩

5. https://notify.coar-repositories.org/catalogue/workflows/repository-pci-1/ ↩

6. https://www.ietf.org/rfc/rfc2119.txt ↩

7. https://github.com/coar-notify/notify.coar-repositories.org/issues/30 ↩

[amgciadev]

Hi, just to let you know that Olivier and I have been working on fixing the workflow for DSpace >= 8.x - fixes are both ends were required. I'll be working on a PR (DSpace) in the upcoming weeks (likely in the New Year).

[fambon]

Specifically on the PCI side, we added:

• support for DataCite metadata ingestion, when advertised via sign-posting on the ressource URL. This metadata format is the default for DSpace, so worth supporting on our side in addition to DublinCore.
• a context section (an optional item in COAR Notifiy payloads) on our "ack" notifications to the repositories. This makes DSpace's life easier when handling TentativeAccept/Reject and Reject notifications.

pci-dev/pci#799 + pci-dev/pci#800

[fambon]

adding in the ref to the PR by @amgciadev
DSpace/DSpace#10053

[paulwalk]

Thanks @amgciadev & @fambon for the updates - good to know 👍🏻