Skip to main content

DocMaps JATS4R Peer Review Materials Comparison

Published onDec 14, 2020
see published version
view latest release
DocMaps JATS4R Peer Review Materials Comparison
·

Summary

DocMaps is a framework for capturing valuable context about the processes used to create documents, in a machine-readable way that can be expressed and interpreted in multiple formats depending on the use-case of the reader of the DocMap. The framework is designed to capture any amount of contextual data about a document — from a minimum assertion that a process took place, to a detailed history of every edit to a document.

We intend DocMaps to be general enough to capture the process behind any document, but our initial focus is capturing evaluative processes surrounding research documents — primarily peer review processes conducted by journals or by services reviewing preprints. We are working with a technical committee of technologists, publishers, preprint server operators, aggregators, and advocates to develop the first use-cases for the framework.

Core Concepts

DocMaps

In addition to being the name of the framework, a DocMap is the name of the object used to capture information about a document. At its most basic, a DocMap consists of just a few pieces of information:

{
createdOn: timestamp // The time the DocMap was created 
contentType: string // The type of content (book, chapter, review)
content: uri | optional // A link to the content the DocMap refers to
provider: uri | optional // A link identifying the provider of the DocMap (e.g. the journal)
}

Using just these three pieces of information, a publisher could make a simple assertion that an article exists.

{
createdOn: 07-07-1999T00:00:00Z
contentType: "article"
content: https://doi.org/10.1109/5.771073
provider: https://ieee.org
}

Of course, this assertion leaves much to be desired. Most DocMaps will contain more information, e.g. the date an article was published; which version of an article the DocMap refers to; etc.

DocMaps accomplishes this by building and maintaining schemas for different Content Types.

Content Types

Content types extend the basic DocMaps structure to add information needed to describe a specific kind of content.

In the article example above, the publisher can provide more information about the article by looking at the schema for a DocMaps Article (see below) and providing as many of the fields as they feel necessary. For example:

{
createdOn: 07-07-1999T00:00:00Z
contentType: "article"
content: https://doi.org/10.1109/5.771073
provider: https://ieee.org
contributors: [{name: "N. Paskin", type: "author"}]
title: "Toward unique identifiers"
}

Although the initial set of content types will be limited, we imagine working with relevant communities to develop many different types that support their use cases. For example: reviews; versions; translations; and discussions.

For now, we’ve defined three different content types with the input of the Technical Committee and the DocMaps core team: Articles, Reviews, and Versions. For more details, see the draft content type schemas below.

Contexts

The real fun starts when you create relationships between DocMaps to describe a series of events. These relationships are called Contexts, and are defined by a context key that describes the type of relationship and the direction of the relationship. Like content types, we imagine that many different types of Contexts will eventually be available, such as:

// context key: [list of DocMaps]
reviews: [Docmap]
isReviewOf: [Docmap]
versions: [Docmap]
isVersionOf: [Docmap]
translations: [Docmap]
isTranslationOf: [Docmap] 
discussions: [Docmap]
isDiscussionOf: [Docmap]
...

Using Contexts and Content Types, you can describe almost any kind of editorial process. For example, let’s imagine that the publisher wanted to let you know that two versions of the article exist. They could add Version Contexts to the Article to show that they have published two versions of the article:

{
createdOn: 07-07-1999T00:00:00Z
contentType: "article"
content: https://doi.org/10.1109/5.771073
provider: https://ieee.org
contributors: [{name: N. Paskin, type: author}]
title: 'Toward unique identifiers'
versions: [
   {
    createdOn: 07-07-1999T00:00:Z
    contentType: "version"
    content: https://doi.org/10.1109/5.771073v1
   }
   {
    createdOn: 07-08-1999T00:00:Z
    contentType: "version"
    content: https://doi.org/10.1109/5.771073v2  
   }
}

But the flexibility of DocMaps means they don’t have to publish all this information at once. They could also publish a DocMap describing just the second version of the paper by creating a Version DocMap with an isVersionOf context containing an Article DocMap.

{
createdOn: 07-08-1999T00:00:00Z
contentType: "version"
content: https://doi.org/10.1109/5.771073v2
provider: https://ieee.org
isVersionOf: [
   {
    createdOn: 07-07-1999T00:00:Z
    contentType: "article"
    content: https://doi.org/10.1109/5.771073
   }
]

Because contexts can flexibly describe events in many different ways, we expect that conventions will arise relatively organically between providers and consumers of DocMaps for describing different editorial processes at different levels of complexity.

As you’ll see in the use cases below, we’ve used the Versions context to provide information about both published article versions and review revision rounds. If a provider didn’t need or want to report revision rounds, or if there was only one round, they could omit the Versions context. In all of these cases, the consumer of the DocMap can decide how much of the context they want to use depending on how they plan to use the DocMap.

Initial Use Cases

The Technical Committee specified two first use cases for DocMaps and further prioritized the data elements needed to capture relevant data for those cases. Below, we describe example DocMaps for these cases and explain how the elements requested by the Technical Committee can be imputed from the DocMaps.

1. A publisher captures context about a review of an article published in their journal

In this example, a journal is describing a double-masked peer review of an article with two rounds of revisions. They do this by nesting a Review context within an Article Context. They then further nest two Version Contexts within the Review Context to describe multiple rounds of feedback.

{
contentType: "article"
content: https://doi.org/article/123
createdOn: 2020-08-16T00:00:00Z
provider: https://myjournal.org
title: 'An article about something!'
contributors: [
    {
     name: "Liz Jones"
     id: https://orcid.org/0002-0002
     role: "author"
    }
    {
     name: "Eric Mays"
     id: https://orcid.org/0005-0001
     role: "data visualization"
    }
]
datePublished: 2020-01-01T:00:00Z
versions: [
   {
     contentType: "version"
     content: https://doi.org/article/123v1
     date_submitted: 2019-12-20T00:00:00Z
     date_online: 2020-08-15T00:00:00Z
     ethics_statements: "This was conducted ethically."
     competing_interests: "There were no conflicts of interest."
   }
]
reviews: [
  {
   contentType: "review"
   content: https://doi.org/review/abcd
   createdOn: 2020-06-01T00:00:00z
   provider: https://myjournal.org
   decision_date: 2020-07-20T00:00:00z
   decision: 'accept with revisions'
   contributors: 
   [
    {
     name: "John Doe"
     affiliation: "Wassamatta U"
     roles: [editor, author]
    }
    {
     id: 12345
     roles: [reviewer]
    }
    {
     id: 23456
     roles: [reviewer]
    }
   ]
   identity_transparency: 'double-anonymized'
   reviewer_interacts_with: [editor]
   review_information_published: [editor-identities]
   versions: [
    {
     contentType: "version"
     createdOn: 2020-06-15T00:00:00Z
     contributors: [
      {
       id: 12345
       roles: [reviewer]
      }
      {
       id: 23456
       roles: [reviewer]
      }
     ]
    }
    {
     contentType: "version"
     createdOn: 2020-07-10T00:00:00Z
     date_online: 2020-08-15T00:00:00Z
     contributors: [
      {
       id: 12345
       roles: [reviewer]
      }
     ]
    }
   ]
  }
 ]
}

JATS4R Peer Review Material Elements

JATS4R Element

Value

DocMaps Element

sub-article

n/a

article -> reviews

front-stub

n/a

article -> reviews -> {…}

article-id

https://doi.org/review/abcd

article -> reviews -> [content]

contrib / contrib-group

John Doe, 12345, 23456

article -> reviews -> [contributors]

contrib-type

John Doe (author)

mapped from article -> reviews -> [contributors -> role]

anonymous

12345, 23456

implied via article -> reviews -> [contributors (no name or orcid)]

role -> @specific-use

John Doe (editor), 12345 (referee <- referee), 23456 (referee <- referee)

mapped from mapped from article -> reviews -> [contributors -> role]

permissions

n/a

n/a (but we should add this)

pub-date

2020-08-15T00:00:00Z

article -> reviews -> version [1] -> date_online

related-object

2 versions

article -> reviews -> versions (or any nested DocMap)

related-object -> @document-type

potentially not enough info to map from DocMaps content types

article -> reviews -> versions (or any nested DocMap) -> contentType

OR

article -> reviews -> contentType when nested DocMaps exist

related-object -> @source-id

https://myjournal.org

article -> reviews -> provider

pub-history / event

2 referee-report-received, 1 editor-decision-sent

article -> reviews -> versions (or any nested DocMap)

pub history / event -> @event-type

round 1 referee-report-received: 2020-06-15T00:00:00Z

round 2 referee-report-received: 2020-07-10T00:00:00Z

editor_decision_sent: 2020-07-20T00:00:00z

round 1 mapped from article -> reviews -> versions[0] -> createdOn

round 2 mapped from article -> reviews -> versions[1] -> createdOn

editor decision mapped from article -> reviews -> decisionDate

institution

none

article -> reviews -> contributors -> affiliation

competing interests

none

article -> reviews -> competing_interests

referee_number

12345: 1

23456: 2

implied from order of array: article -> reviews -> contributors

peer_review_stage

pre-publication

implied from review date_online < article date_online

transfer

no

implied from provider being same value on both article and article -> reviews

revision_round

2

implied from number of elements in article -> reviews -> versions

recommendation

accept <- accept with revisions

mapped from article -> reviews[0] -> decision

peer_review_type

double-blind <- double-anonymized

mapped from article -> reviews[0] -> identity_transparency (uses STM taxonomy)

2. An independent review service notifies a preprint server about a review of an article on their platform.

In this example, a review service is describing a fully transparent review of a preprint article with links to the review report and author response. They do this by including a content field for the review object and filling out the author response and STM Association Taxonomy metadata to describe the process of the review.

{
contentType: "review"
content: https://doi.org/review/123
createdOn: 2020-08-01T00:00:00z
provider: https://myreviewservice.org
decision_date: 2020-07-20T00:00:00z
decision: "accept"
contributors: [
    {
     name: "Tricia McMillan"
     affiliation: "Maximegalon University"
     roles: [editor, author]
     id: https://orcid.org/0000-0000
     author_suggested: false
    },
    {
     name: "Zaphod Beeblebrox"
     affiliation: "Betelgeuse State College"
     roles: [reviewer]
     id: https://orcid.org/0001-0001
     author_suggested: true
    }
    {
     name: "Arthur Dent"
     affiliation: "BBC"
     roles: [reviewer]
     id: https://orcid.org/0002-0002
    }
    {
     name: "Ford Prefect"
     affiliation: "Pan Galactic Gargle Blaster Society"
     roles: [invited_reviewer]
     id: https://orcid.org/0002-0002
    }
]
author_responses: [{ 
    contentType: "version"
    content: https://doi.org/response/123
    date_online: 2020-07-31T00:00:00Z
    date_submitted: 2020-07-15T00:00:00Z
}]
identity_transparency: [all-identities-visible, opt-in]
reviewer_interacts_with: [editors, reviewers, authors]
review_information_published: [reviewer-identities, editor-identities, review-reports-author-opt-in]
versions: [
   {
    contentType: "version"
    date_submitted: 2020-06-15T00:00:00Z
    date_online: 2020-07-31T00:00:00Z
   }
]
isReviewOf: [
    {
     contentType: "article"
     content: https://doi.org/preprint/123
    }
]

JATS4R Peer Review Material Elements

JATS4R Element

Value

DocMaps Element

article

n/a

review

article-metadata

n/a

review -> {…}

article-id

https://doi.org/review/123

review -> content

contrib / contrib-group

reviews -> [contributors]

contrib-type

Tricia McMillan (author)

mapped from article -> reviews -> [contributors -> role]

anonymous

12345, 23456

implied via article -> reviews -> [contributors (no name or orcid)]

role -> @specific-use

Tricia McMillan (editor), Zaphod Beeblebrox (referee <- reviewer), Athur Dent (referee <- reviewer)

mapped from mapped from article -> reviews -> [contributors -> role]

permissions

n/a

n/a (but we should add this)

pub-date

2020-07-31T00:00:00Z

review -> versions [0] -> date_online

related-object

1 article

review -> isReviewOf [0]

related-object -> @document-type

peer-reviewed-article <- article

review -> isReviewOf [0] -> contentType

related-object -> @source-id

https://myreviewservice.org

article -> reviews -> provider

pub-history / event

1 referee-report-received, 1 editor-decision-sent, 1 author-comment-received

article -> reviews -> versions (or any nested DocMap)

pub history / event -> @event-type

1 referee-report-received: 2020-07-15T00:00:00Z

editor_decision_sent: 2020-07-20T00:00:00z

author-comment-received: 2020-07-15T00:00:00Z

review -> versions[0] -> date_submitted

review -> decisionDate

review -> author_comment -> date_submitted

institution

Tricia McMillan (University of Maximegallon)

Zaphod Beeblebrox (Beetelgeuse State College)

Arthur Dent (BBC)

article -> reviews -> contributors -> affiliation

competing interests

none

article -> reviews -> competing_interests

referee_number

Zaphod Beebelbrox: 1

Arthur Dent: 2

implied from order of array: article -> reviews -> contributors

peer_review_stage

n/a

unknown, as article being reviewed is only referenced by ID. Could maybe be implied as “post-publication” from lack of provider or date_online for isReviewOf docmap

transfer

n/a

unknown, as article being reviewed is only referenced by ID. could maybe be implied as “yes” from lack of provider for isReviewOf docmap

revision_round

1

implied from number of elements in review -> versions

recommendation

accept -> accept

mapped from review -> decision

peer_review_type

visible -> all_identities_visible, opt-in

mapped from review -> identity_transparency (uses STM taxonomy)

Draft Content Type Schemas

These are initial drafts of content type schemas, and will be somewhat incomplete by design. They are intended to capture the information necessary to make the two initial use cases listed above possible.

Article

{

// Common DocMap fields
contentType: "article"
content: uri // A canonical link or DOI to the article, if it exists
createdOn: timestamp
provider: uri

// Article specific metadata
title: string
abstract: string
contributors: [Contributors]
datePublished: date

// Contexts
versions: [Version]

}

Review

{

// Common DocMap fields
contentType: "review"
content: uri // A canonical link or DOI to the report publication, if it exists
createdOn: timestamp
provider: uri

// Review specific metadata fields
decision_date: timestamp
decision: string
contributors: [Contributor] // Includes reviewers, editors, asked reviewers
author_response: uri
identity_transparency: string // STM Assoc taxonomy
reviewer_interacts_with: [string] // STM Assoc taxonomy
review_information_published: [string] // STM Assoc taxonomy
post_publication_commenting: [string] // STM Assoc taxonomy

// Contexts
isReviewOf: [Article] // A list of DocMaps of reviewed objects

}

Version

{

// Common DocMap fields
contentType: "version"
content: uri // A canonical link or DOI to the version of the referenced object, if it exists
createdOn: timestamp
provider: uri

// Version specific metadata
date_submitted: timestamp
date_online: timestamp
ethics_statements: string
competing_interests: string
data_availability: string
contributors: [Contributor]

}

Implementation

Once we discuss and come to agreement on the initial schemas, we’ll turn to implementation. We’re using pseudocode in the examples above because we want DocMaps to support multiple formats, since publishers’ technological needs and capabilities are so varied.

Comments
0
comment
No comments here
Why not start the discussion?