Skip to main content

Related Objects Spec

Published onJun 02, 2020
Related Objects Spec


What is it, who’s it for, what is the core need of those people that this addresses, and how does it address their needs in a way that improved upon competitors and our current feature-set?

This feature allows authors to specify that a particular Pub in some way references a different object (or, in some cases, multiple objects). This is a key feature for properly representing editorial commentary for HDSR, supplemental material, and gives PubPub a new browsing mode and way to aggregate and display related works to users. In particular, it will make new proposed forking functionality more fully complete by specifying the type of the fork, setting the stage for eventually publishing reviews as external forks that reference the original pub. It allows us to properly deposit linked Pubs in Crossref. Finally, it will allow us to stop hard-coding editorial commentary for HDSR, saving significant staff time.

This is also a key feature for overlay journals — that is, journals which want to publish reviews of preprints as first-class editorial objects.

Most of our competitors offer metadata for supplemental material and linked data, which is a current limitation of PubPub. But it also introduces a new range of possibilities that will set PubPub apart.

Supporting Links/Research

Links to research, interviews, designs, competitors, etc.

What is it?

List all of the main features, hopefully in rough priority order. Typically these are broken down into descriptions of screens/interface components and their purpose.

  1. Pub relationship settings — ability to select that the Pub is referencing another document or documents (another Pub, a link, or a DOI) plus the ability to set a custom name for the relationship (ie “Rejoinder” for a reply).

  2. Pub crossref metadata depositing/settings — augments the existing DOI infrastructure to deposit articles with a relationship type if it exists. Updates the settings UI to display more info about how we are submitting the article, if there is a Crossref relationship type to describe it. At minimum, we should support the following crossref types, here:

    • Basis

    • Comment

    • Continuation

    • Derivation

    • Peer review

    • Preprint

    • Related material

    • Reply

    • Supplement

    • Translation

  3. Pub header linked pub display — display some sort of preview of referenced pub/article, to show that this is primarily meant to be in reference to another article. If the current Pub is linked to another Pub, we should display a nicely formatted card. If it’s a DOI, we should parse it and grab more info about the article. If it’s a link, we should crawl it and display some kind of information about it.

  4. Pub footer linked pubs section — display a list of all Pubs referencing the current one in the footer, grouped by the type of reference, with the ability for managers to set featured linked pubs that rise to the top of the section. Ultimately, it would be good to pull further relations from crossref events, but that’s out of scope.

  5. Page Pub Block relations — automatically display any featured linked pubs, organized by type, in the Pub block. We may also want the ability to turn this on or off on a per-block basis.

What is success?

  1. Decreased staff time setting up manual linked pubs

  2. Increased clicks on linked pubs

  3. Implementation of linked concept in reviews and forks

Design Process

Feature 1



  1. As an author/admin/editor/reader/review … I want …. so I can…


Implementation Checklists

  • How do people do this now and how does this change that?

We have some manual kludges to do this for HDSR, including modifying HTML source. Otherwise, people just link to other articles. There’s no structured way to do this.

  • What other parts of the system are impacted?

    • Crossref depositing

    • Page builder

    • Exports

  • Who has permissions to do what?

    • Pub managers can set the pub reference type on their pub

    • Pub managers can decide to “feature” linked pubs that reference their pub

  • Mobile support?

  • Active states?

  • Error states?

Tech Implementation Checklist

  • Performance


  • Pub (Research paper)

    • Review Thread 1

    • Review Thread 2 -> Thread, Structured Questions

    • Linked Review A (linked pub Pub) -> Document

    • Linked Review B (linked pub URL)

    • Translation 1 (linked pub)

No comments here
Why not start the discussion?