Significant Revision to the Specification

The COAR Notify team is pleased to announce a significant revision to the COAR Notify Protocol specification, and the documentation (this website) in general.

This is in response to feedback from those developers who have been implementing the specification. Some of these changes were agreed at the meeting for developers in Madrid, back in March of this year. Other feedback has been provided in GitHub issues and discussions

In particular I'd like to thank Patrick Hochstenbach, Olivier Fambon, Richard Jones and Stefano Maffei for their help with preparing this revised documentation.

Changed approach to documenting the specification

We have re-introduced the IETF's RFC2119 language ("MUST", "SHOULD" etc.) in order to make the specification clearer. This has not necessarily made the specification stricter, but it has made it more precise.

Introduction of version control

One of the most important new features is that the specification is now under version control, using semantic versioning. In the Madrid meeting, we agreed that we would create a notional pre-version 1 specification, because there has been a certain amount of development while the specification was evolving. This means that we now have two published versions:

• version 0.9.0 which is a "legacy" version
• version 1.0.0 which is now the current version.

Due to the nature of the changes, and of JSON-LD in general, systems which have implemented patterns in the 0.9.0 version should have little difficulty in converting to the 1.0.0 version. In the majority of cases, notifications in the older version should still be processable in any case.

Specification changes (version 1.0.0)

The syntactic changes to the patterns in version 1.0.0 are itemised in the release notes for this version.

New domain for this documentation, for the JSON-LD context and the vocabulary terms

For some time we have been reconsidering the need for PURLs (or any other so-called "PID" system for the JSON-LD context and for the vocabulary terms). In the last few days, the PURL system has been offline due to a DOS attack against the Internet Archive. This has accelerated our decision to deprecate our use of PURLs. The PURLs which we have minted for use in the @context property and in the vocabulary terms will continue to work, but we will no longer be minting new PURLs. This is made clear in version 1.0.0 of the specification, and in the vocabulary terms documentation - e.g. EndorsementAction.

New approach to documenting workflows

Workflows are no longer documented with the "swim lanes" diagram approach. Instead, a flowchart is automatically generated from the workflow documentation and presented using Mermaid. This is an example from the PCI Endorement workflow:

Feedback

As ever, please report any issues with the specification or the documentation in the GitHub issues for this website.

Asynchronously reporting 'un-processable' notifications

In the Madrid meeting we discussed how to notify a system that it has sent an "un-processable" notification. This was also discussed in the GitHub repository discussion forum.

The use case is that a system receives a notification which is "well-formed", and so the receiver sends a 202 Accepted response, queuing the notification for asynchronous processing. However, when the system attempts to process the notification, it discovers that it is "un-processable" for some reason. For example, a URL referenced in the notification might not be resolvable.

In this kind of use-case, HTTP error handling is not applicable, so the system needs a way to report the problem to the sender. The obvious approach is to send a notification explaining that a previously received notification is un-processable.

We have now published a new draft pattern for expressing this.

If you have comments or questions about this, please post them on this discussion forum thread.

Notify Developers Meeting

On the 7th and 8th March 2024 a core group of developers came together to compare their experiences with implementing COAR Notify in their systems.

We were generously hosted by Isabel Bernal of CSIC in Madrid. In keeping with all COAR activities, a range of nationalities and domains was represented.

We discussed a range of technical issues, comparing notes on what had worked well, and what needed improvement or clarification. It was also a chance for begin to establish a community of COAR Notify developers. Judging by the level of engagement, and the conversations over dinner, I think we were successful in this!

I will write here in more detail in future posts about some of the deeper technical issues, but in the meantime here is a summary of some of the decisions and outcomes:

1. Where COAR Notify implementation software is directly commissioned by the Notify project we will use the MIT license (a "permissive") license. However, we recognise that some platforms may require a different open-source license. We will not ordinarily work with software that is not open-source and licensed accordingly.
2. We will make one immediate change to the protocol (documented in the change-log)
3. After this immediate change to the protocol, we will use a more managed approach to versioning, deprecating etc. - however, we do not anticipate changing versions frequently.
4. We will develop an interim catalogue (on this website) to include the following:
   • Services implementing COAR Notify
   • Specific workflows supported by each service
   • Software platforms (e.g. repository platforms) which support each workflows
   • Open-source code-bases involved in implementing or supporting COAR Notify
5. Add more content to the Implementation Guide:
   • Document options for limiting access from remote systems, with some examples and the scenarios they address.
   • Extend the architecture section to include more options, and to add more detail to the pros, cons, affordances and consequences of each option.
   • Document the pros and cons of storing notifications versus not storing them
   • Document the recommended process for handling metadata with signposting.org - an end-to-end process
6. Increase communications support for the developer community:
   • Investigate using GitHub Discussions for forum
   • Create a mailing list to be used only for rare, important announcements (all the developers at the meeting agreed to be subscribed to this)
7. Define a new pattern for indicating that an activity was "un-processable”

The interim catalogue is already available (very much a "work-in-progress").

It was an excellent meeting - a really good group of developers doing important work. The COAR Notify team gained some invaluable insights into the challenges associated with implementing the COAR Notify protocol. I very much hope that we can do this again, perhaps in a year's time.

Attendees

Invited Developers:

• Yannis Barlas, Kotahi
• Jose Carvalho, University of Minho
• Olivier Fambon, Peer Community In (PCI)
• Emilio Lorenzo, Arvo
• Stefano Maffei, 4Science
• Hrafn Malmquist, Cottage Labs
• Lautaro Matas, La Referencia
• Will Fyson, CoSector
• Adán Román, Arvo
• Nicola Tarocco, CERN
• Raphaël Tournoy, CCSD
• Sean Wiseman, eLife

COAR Notify Team:

• Martin Klein, LANL
• Silvia Nakano, COAR
• Paul Walk, Antleaf

DARIAH overlay journal

The OPERAS Innovation Lab has published a post, DARIAH overlay journal as an alternative and transparent publishing model, about a new overlay-journal platform which will be enhanced by COAR Notify.

They include a succinct and useful definition of an overlay journal:

An overlay journal is an innovative type of scholarly publication that operates on top of pre-existing data repositories and preprint servers. Unlike traditional journals, overlay journals do not host content themselves. Instead, they select, peer review and formally publish links to content that is already hosted on other platforms, such as HAL or arXiv, or institutional repositories.

This approach, of services utilising and adding value to content from the distributed network of repositories, is very much aligned with the philosophy underpinning the COAR Notify initiative. Furthermore, the overlay journal concept embraces the pass by reference principle which is at the heart of the COAR Notify protocol.

I am very pleased to see that the DARIAH overlay journal will make use of the COAR Notify Protocol. This should not be surprising, as the DARIAH overlay journal will be based on the Episciences platform, which is another implementing partner in the COAR Notify initiative.