Work-in-progress documentation for DocMaps, a framework for describing the processes used to create a document in a machine-readable way.
DocMaps is a framework for describing the processes used to create a document in a machine-readable way. The framework is designed to be interpreted in multiple formats depending on the use-case of the consumer of the DocMap. It can extend to capture any amount of contextual data about any kind of 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 kind of document, but our initial focus is capturing evaluative processes surrounding research documents — primarily peer review processes conducted by journals or by services reviewing preprints. From June 2020 to February 2021, we worked with a technical committee of technologists, publishers, preprint server operators, aggregators, and advocates to develop the first use-cases for the framework.
Since then, an informal working group from Knowledge Futures, Cold Spring Harbor Laboratory, and eLife’s Sciety have been working on a pilot implementation to use DocMaps from two providers, Sciety and EMBO’s Early Evidence Base, to two consumers, CSHL’s bioRxiv and medRxiv preprint servers.
DocMaps are immutable assertions that describe the processes used to create a document (e.g. the peer review process used to evaluate a scientific article, or the process used to create an overlay review article).
DocMaps are asserted by the publisher of the document (e.g. PREReview).
DocMaps can describe a single event or a complex, multi-event process.
DocMaps may contain links to other documents, including other DocMaps.
DocMaps are not representations of the documents whose contexts they describe (though they could embed representations or link to representations of those documents).
DocMaps are not representations of a document’s current state (though aggregators can use them to produce views of these states).
DocMaps are not notifications that an event took place (though they can be used as the payload for such notifications).
DocMaps are not assertions of the subjective result of any given process (though they may contain the DocMap provider’s subjective result, which DocMap consumers can choose to use).
DocMaps are asserted by a provider and interpreted by a consumer. It is up to the provider to provide information about processes that they believe are meaningful to understand the process and context used to create the document. It is up to the consumer to decide how to interpret the provided DocMap. In this way, consumers from different perspectives can decide how to interpret provided DocMaps based on their needs and purpose. One consumer may decide that a provider’s DocMap qualifies as peer review for their purposes. Another consumer may decide that the same DocMap is only an evaluation, and must be combined with other DocMaps to qualify as a review. A third consumer may decide to ignore the provider’s DocMap entirely. All approaches are valid.
At its core, the DocMaps framework is a set of agreed-upon conventions for aligning editorial processes against the Publishing Status Ontology (PSO), Publishing Workflow Ontology (PWO) and for expressing these events in a domain-specific language that can be easily interpreted by machines and humans alike. When needed, we use other SPAR Ontologies to describe objects and relationships that fall outside the domains of PWO and PSO, particularly the FRBR-aligned Bibliographic Ontology (FaBiO).
By aligning against well-defined publishing Ontologies, DocMaps makes use of community endorsed, tested, and extensible models rather than trying to invent a new model, which would risk being too specific and less likely to succeed. This alignment also allows developers who are familiar with RDF and other Semantic Web technologies to model editorial events as graphs and serialize them in many formats.
By expressing this alignment using domain-specific language conventions, DocMaps makes it easy for users to reason about editorial events without needing to understand the underlying Ontologies or semantic web structures. This alignment also allows developers who are less familiar with semantic web technologies to create and consume DocMaps in simple formats like JSON using their existing technology stacks.
A Docmap is a pwo:Workflow
that describes a series of pwo:Step
s, which are executed in (taskex:isExecutedIn
) actions. Each action contains assertions (pso:ResultsInAcquiring
) that assert that a particular action resulted in (pwo:isStatusHeldBy
) an item (frbr:Work
) acquiring (pso:withStatus
) a pso:publishingStatus
such as “peer-reviewed”.
In addition to asserting status changes, each action describes the inputs (pwo:needs
) and outputs (pwo:produces
) of the action in the form of fabio:expressions
. Each action also describes participants (pro:isDocumentContextFor
), which are actors (pro:isHeldBy
) of a defined type (usually foaf:person
) holding pro:Role
s such as peer-reviewer
or editor
.
By using the convention, providers can express Docmaps in plain JSON. By enhancing the plain JSON using JSON-LD framing, it can be interpreted as JSON-LD, allowing RDF consumers to reason about them.
This example models this Review Commons evaluation process.
{
"first-step": "_:b-336d69dd-06d2-484b-8866-256ea5bbc384",
"provider": "https://sciety.org",
"created": "2021-06-21T15:59:56.000Z",
"generatedAt": "2021-08-04T15:57:24.347Z",
"publisher": {
"id": "https://www.reviewcommons.org/",
"logo": "https://sciety.org/static/groups/review-commons--316db7d9-88cc-4c26-b386-f067e0f56334.jpg",
"homepage": "https://www.reviewcommons.org/",
"account": {
"id": "https://sciety.org/groups/316db7d9-88cc-4c26-b386-f067e0f56334",
"service": "https://sciety.org"
}
},
"id": "https://sciety.org/docmaps/v1/articles/10.1101/2021.04.25.441302.docmap.json",
"type": "docmap",
"steps": {
"_:b-78200b4c-48b8-4d64-b0d0-bfc99453d5f0": {
"assertions": [],
"actions": [
{
"outputs": {
"published": "2021-06-18T23:16:27.418601+00:00",
"type": "author-response",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NRboUNCLEeusR-de0blrmA",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NRboUNCLEeusR-de0blrmA"
}
]
},
"participants": [
{
"actor": {
"firstName": "Magdalini",
"type": "person",
"familyName": "Polymenidou"
},
"role": "author"
},
{
"actor": {
"firstName": "Mathias",
"type": "person",
"familyName": "Jucker"
},
"role": "author"
},
{
"actor": {
"firstName": "Regina",
"type": "person",
"familyName": "Reimann"
},
"role": "author"
},
{
"actor": {
"firstName": "Kelvin",
"type": "person",
"familyName": "Luk"
},
"role": "author"
},
{
"actor": {
"firstName": "Melanie",
"type": "person",
"familyName": "Barth"
},
"role": "author"
},
{
"actor": {
"firstName": "Simone",
"type": "person",
"familyName": "Hornemann"
},
"role": "author"
},
{
"actor": {
"firstName": "Philipp J.",
"type": "person",
"familyName": "Kahle"
},
"role": "author"
},
{
"actor": {
"firstName": "Matthias M.",
"type": "person",
"familyName": "Schneider"
},
"role": "author"
},
{
"actor": {
"firstName": "Mehtap",
"type": "person",
"familyName": "Bacioglu"
},
"role": "author"
},
{
"actor": {
"firstName": "Therese W.",
"type": "person",
"familyName": "Herling"
},
"role": "author"
},
{
"actor": {
"firstName": "Nora",
"type": "person",
"familyName": "Bengoa-Vergniory"
},
"role": "author"
},
{
"actor": {
"firstName": "Ronald",
"type": "person",
"familyName": "Melki"
},
"role": "author"
},
{
"actor": {
"firstName": "Andrès",
"type": "person",
"familyName": "Gonzalez-Guerra"
},
"role": "author"
},
{
"actor": {
"firstName": "Natalie",
"type": "person",
"familyName": "Landeck"
},
"role": "author"
},
{
"actor": {
"firstName": "Merve",
"type": "person",
"familyName": "Avar"
},
"role": "author"
},
{
"actor": {
"firstName": "Marc",
"type": "person",
"familyName": "Emmenegger"
},
"role": "author"
},
{
"actor": {
"firstName": "Tuomas P. J.",
"type": "person",
"familyName": "Knowles"
},
"role": "author"
},
{
"actor": {
"firstName": "Pierre",
"type": "person",
"familyName": "de Rossi"
},
"role": "author"
},
{
"actor": {
"firstName": "Alice",
"type": "person",
"familyName": "Kaganovich"
},
"role": "author"
},
{
"actor": {
"firstName": "Adriano",
"type": "person",
"familyName": "Aguzzi"
},
"role": "author"
},
{
"actor": {
"firstName": "Lisa M.",
"type": "person",
"familyName": "Häsler"
},
"role": "author"
},
{
"actor": {
"firstName": "Rebekah G.",
"type": "person",
"familyName": "Langston"
},
"role": "author"
},
{
"actor": {
"firstName": "Elena",
"type": "person",
"familyName": "De Cecco"
},
"role": "author"
},
{
"actor": {
"firstName": "Elena",
"type": "person",
"familyName": "Tantardini"
},
"role": "author"
},
{
"actor": {
"firstName": "Naunehal S.",
"type": "person",
"familyName": "Matharu"
},
"role": "author"
},
{
"actor": {
"firstName": "Timo",
"type": "person",
"familyName": "Eninger"
},
"role": "author"
},
{
"actor": {
"firstName": "Daniel",
"type": "person",
"familyName": "Heinzer"
},
"role": "author"
},
{
"actor": {
"firstName": "Marian",
"type": "person",
"familyName": "Hruska-Plochan"
},
"role": "author"
},
{
"actor": {
"firstName": "Mark R.",
"type": "person",
"familyName": "Cookson"
},
"role": "author"
}
]
}
],
"inputs": [
{
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NLvJytCLEeu80AcUa4ddWQ"
},
{
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NHzJFNCLEeuVtHPfNKpeXA"
},
{
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NFUoPNCLEeun7-eddskxjg"
}
]
},
"_:b-336d69dd-06d2-484b-8866-256ea5bbc384": {
"next-step": "_:b-78200b4c-48b8-4d64-b0d0-bfc99453d5f0",
"assertions": [
{
"item": "https://doi.org/10.1101/2021.04.25.441302",
"status": "reviewed"
}
],
"actions": [
{
"outputs": [
{
"published": "2021-06-18T23:16:26.146515+00:00",
"type": "review",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NLvJytCLEeu80AcUa4ddWQ",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NLvJytCLEeu80AcUa4ddWQ"
}
]
}
],
"participants": [
{
"actor": {
"name": "anonymous",
"type": "person"
},
"role": "peer-reviewer"
}
]
},
{
"outputs": [
{
"published": "2021-06-18T23:16:26.845853+00:00",
"type": "review",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NHzJFNCLEeuVtHPfNKpeXA",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NHzJFNCLEeuVtHPfNKpeXA"
}
]
}
],
"participants": [
{
"actor": {
"name": "anonymous",
"type": "person"
},
"role": "peer-reviewer"
}
]
},
{
"outputs": [
{
"published": "2021-06-18T23:16:26.414609+00:00",
"type": "review",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NFUoPNCLEeun7-eddskxjg",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NFUoPNCLEeun7-eddskxjg"
}
]
}
],
"participants": [
{
"actor": {
"name": "anonymous",
"type": "person"
},
"role": "peer-reviewer"
}
]
}
],
"inputs": [
{
"published": "2021-04-26T00:00:00Z",
"uri": "https://doi.org/10.1101/2021.04.25.441302",
"doi": "10.1101/2021.04.25.441302"
}
]
}
}
}
By adding a JSON-LD frame and context, the document can be interpreted as JSON-LD.
{
"@context": {
"dcterms": "http://purl.org/dc/terms/",
"foaf": "http://xmlns.com/foaf/0.1/",
"cnt": "http://www.w3.org/2011/content#",
"fabio": "http://purl.org/spar/fabio/",
"frbr": "http://purl.org/vocab/frbr/core#",
"pso": "http://purl.org/spar/pso/",
"pwo": "http://purl.org/spar/pwo/",
"xsd": "http://www.w3.org/2001/XMLSchema#",
"prism": "http://prismstandard.org/namespaces/basic/2.0/",
"pro": "http://purl.org/spar/pro/",
"prov": "https://www.w3.org/TR/prov-o/",
"taskex": "http://www.ontologydesignpatterns.org/cp/owl/taskexecution.owl#",
"ti": "http://www.ontologydesignpatterns.org/cp/owl/timeinterval.owl#",
"id": "@id",
"type": "@type",
"docmap": "pwo:Workflow",
"created": {
"@id": "dcterms:created",
"@type": "xsd:date"
},
"description": "dcterms:description",
"title": {
"@id": "dcterms:title",
"@container": "@language"
},
"doi": "prism:doi",
"creator": {
"@id": "dcterms:creator",
"@container": "@set",
"@type": "@id"
},
"published": {
"@id": "prism:publicationDate",
"@type": "xsd:date"
},
"name": "foaf:name",
"person": "foaf:Person",
"publisher": {
"@id": "dcterms:publisher",
"@type": "foaf:Organization"
},
"logo": {
"@id": "foaf:logo",
"@type": "xsd:anyURI"
},
"homepage": {
"@id": "foaf:homepage",
"@type": "xsd:anyURI"
},
"account": {
"@id": "foaf:OnlineAccount",
"@type": "xsd:anyURI"
},
"service": {
"@id": "foaf:accountServiceHomepage",
"@type": "xsd:anyURI"
},
"provider": {
"@id": "foaf:Organization",
"@type": "@id"
},
"process": {
"@id": "prov:process",
"@type": "xsd:string"
},
"inputs": {
"@id": "pwo:needs",
"@container": "@set",
"@type": "@id"
},
"outputs": {
"@id": "pwo:produces",
"@container": "@set",
"@type": "@id"
},
"assertions": {
"@id": "pso:resultsInAcquiring",
"@container": "@set",
"@type": "@id",
"@context": {
"item": {
"@id": "pso:isStatusHeldBy",
"@type": "@id"
},
"status": {
"@id": "pso:withStatus",
"@type": "@vocab",
"@context": {
"@vocab": "http://purl.org/spar/pso/"
}
}
}
},
"steps": {
"@id": "pwo:hasStep",
"@container": [
"@id"
]
},
"first-step": {
"@id": "pwo:hasFirstStep",
"@type": "@id"
},
"next-step": {
"@id": "pwo:hasNextStep",
"@type": "@id"
},
"previous-step": {
"@id": "pwo:hasPreviousStep",
"@type": "@id"
},
"content": {
"@id": "fabio:hasManifestation",
"@type": "@id",
"@container": "@set"
},
"url": {
"@id": "fabio:hasURL",
"@type": "xsd:anyURI"
},
"review": "fabio:ProductReview",
"web-page": "fabio:WebPage",
"participants": {
"@id": "pro:isDocumentContextFor",
"@container": "@set",
"@type": "@id"
},
"role": {
"@id": "pro:withRole",
"@type": "@vocab",
"@context": {
"@vocab": "http://purl.org/spar/pro/"
}
},
"actor": {
"@id": "pro:isHeldBy",
"@type": "@id"
},
"email": "fabio:Email",
"file": {
"@id": "fabio:DigitalManifestation",
"@context": {
"text": "cnt:chars"
}
},
"letter": "fabio:Letter",
"manuscript": "fabio:Manuscript",
"format": {
"@id": "dcterms:format",
"@type": "@vocab",
"@context": {
"@vocab": "https://w3id.org/spar/mediatype/"
}
},
"includes": "frbr:part",
"actions": {
"@id": "taskex:isExecutedIn",
"@container": "@set",
"@type": "@id"
},
"happened": {
"@id": "pwo:happened",
"@type": "@id"
},
"at-date": {
"@id": "ti:hasIntervalDate",
"@type": "xsd:date"
},
"realization-of": {
"@id": "frbr:realizationOf",
"@type": "@id"
},
"author-response": "fabio:Reply",
"evaluation-summary": "fabio:ExecutiveSummary",
"decision-letter": "fabio:Letter"
},
"first-step": "_:b-336d69dd-06d2-484b-8866-256ea5bbc384",
"provider": "https://sciety.org",
"created": "2021-06-21T15:59:56.000Z",
"generatedAt": "2021-08-04T15:57:24.347Z",
"publisher": {
"id": "https://www.reviewcommons.org/",
"logo": "https://sciety.org/static/groups/review-commons--316db7d9-88cc-4c26-b386-f067e0f56334.jpg",
"homepage": "https://www.reviewcommons.org/",
"account": {
"id": "https://sciety.org/groups/316db7d9-88cc-4c26-b386-f067e0f56334",
"service": "https://sciety.org"
}
},
"id": "https://sciety.org/docmaps/v1/articles/10.1101/2021.04.25.441302.docmap.json",
"type": "docmap",
"steps": {
"_:b-78200b4c-48b8-4d64-b0d0-bfc99453d5f0": {
"assertions": [],
"actions": [
{
"outputs": {
"published": "2021-06-18T23:16:27.418601+00:00",
"type": "author-response",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NRboUNCLEeusR-de0blrmA",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NRboUNCLEeusR-de0blrmA"
}
]
},
"participants": [
{
"actor": {
"firstName": "Magdalini",
"type": "person",
"familyName": "Polymenidou"
},
"role": "author"
},
{
"actor": {
"firstName": "Mathias",
"type": "person",
"familyName": "Jucker"
},
"role": "author"
},
{
"actor": {
"firstName": "Regina",
"type": "person",
"familyName": "Reimann"
},
"role": "author"
},
{
"actor": {
"firstName": "Kelvin",
"type": "person",
"familyName": "Luk"
},
"role": "author"
},
{
"actor": {
"firstName": "Melanie",
"type": "person",
"familyName": "Barth"
},
"role": "author"
},
{
"actor": {
"firstName": "Simone",
"type": "person",
"familyName": "Hornemann"
},
"role": "author"
},
{
"actor": {
"firstName": "Philipp J.",
"type": "person",
"familyName": "Kahle"
},
"role": "author"
},
{
"actor": {
"firstName": "Matthias M.",
"type": "person",
"familyName": "Schneider"
},
"role": "author"
},
{
"actor": {
"firstName": "Mehtap",
"type": "person",
"familyName": "Bacioglu"
},
"role": "author"
},
{
"actor": {
"firstName": "Therese W.",
"type": "person",
"familyName": "Herling"
},
"role": "author"
},
{
"actor": {
"firstName": "Nora",
"type": "person",
"familyName": "Bengoa-Vergniory"
},
"role": "author"
},
{
"actor": {
"firstName": "Ronald",
"type": "person",
"familyName": "Melki"
},
"role": "author"
},
{
"actor": {
"firstName": "Andrès",
"type": "person",
"familyName": "Gonzalez-Guerra"
},
"role": "author"
},
{
"actor": {
"firstName": "Natalie",
"type": "person",
"familyName": "Landeck"
},
"role": "author"
},
{
"actor": {
"firstName": "Merve",
"type": "person",
"familyName": "Avar"
},
"role": "author"
},
{
"actor": {
"firstName": "Marc",
"type": "person",
"familyName": "Emmenegger"
},
"role": "author"
},
{
"actor": {
"firstName": "Tuomas P. J.",
"type": "person",
"familyName": "Knowles"
},
"role": "author"
},
{
"actor": {
"firstName": "Pierre",
"type": "person",
"familyName": "de Rossi"
},
"role": "author"
},
{
"actor": {
"firstName": "Alice",
"type": "person",
"familyName": "Kaganovich"
},
"role": "author"
},
{
"actor": {
"firstName": "Adriano",
"type": "person",
"familyName": "Aguzzi"
},
"role": "author"
},
{
"actor": {
"firstName": "Lisa M.",
"type": "person",
"familyName": "Häsler"
},
"role": "author"
},
{
"actor": {
"firstName": "Rebekah G.",
"type": "person",
"familyName": "Langston"
},
"role": "author"
},
{
"actor": {
"firstName": "Elena",
"type": "person",
"familyName": "De Cecco"
},
"role": "author"
},
{
"actor": {
"firstName": "Elena",
"type": "person",
"familyName": "Tantardini"
},
"role": "author"
},
{
"actor": {
"firstName": "Naunehal S.",
"type": "person",
"familyName": "Matharu"
},
"role": "author"
},
{
"actor": {
"firstName": "Timo",
"type": "person",
"familyName": "Eninger"
},
"role": "author"
},
{
"actor": {
"firstName": "Daniel",
"type": "person",
"familyName": "Heinzer"
},
"role": "author"
},
{
"actor": {
"firstName": "Marian",
"type": "person",
"familyName": "Hruska-Plochan"
},
"role": "author"
},
{
"actor": {
"firstName": "Mark R.",
"type": "person",
"familyName": "Cookson"
},
"role": "author"
}
]
}
],
"inputs": [
{
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NLvJytCLEeu80AcUa4ddWQ"
},
{
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NHzJFNCLEeuVtHPfNKpeXA"
},
{
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NFUoPNCLEeun7-eddskxjg"
}
]
},
"_:b-336d69dd-06d2-484b-8866-256ea5bbc384": {
"next-step": "_:b-78200b4c-48b8-4d64-b0d0-bfc99453d5f0",
"assertions": [
{
"item": "https://doi.org/10.1101/2021.04.25.441302",
"status": "reviewed"
}
],
"actions": [
{
"outputs": [
{
"published": "2021-06-18T23:16:26.146515+00:00",
"type": "review",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NLvJytCLEeu80AcUa4ddWQ",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NLvJytCLEeu80AcUa4ddWQ"
}
]
}
],
"participants": [
{
"actor": {
"name": "anonymous",
"type": "person"
},
"role": "peer-reviewer"
}
]
},
{
"outputs": [
{
"published": "2021-06-18T23:16:26.845853+00:00",
"type": "review",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NHzJFNCLEeuVtHPfNKpeXA",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NHzJFNCLEeuVtHPfNKpeXA"
}
]
}
],
"participants": [
{
"actor": {
"name": "anonymous",
"type": "person"
},
"role": "peer-reviewer"
}
]
},
{
"outputs": [
{
"published": "2021-06-18T23:16:26.414609+00:00",
"type": "review",
"uri": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NFUoPNCLEeun7-eddskxjg",
"content": [
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2021.04.25.441302#hypothesis:NFUoPNCLEeun7-eddskxjg"
}
]
}
],
"participants": [
{
"actor": {
"name": "anonymous",
"type": "person"
},
"role": "peer-reviewer"
}
]
}
],
"inputs": [
{
"published": "2021-04-26T00:00:00Z",
"uri": "https://doi.org/10.1101/2021.04.25.441302",
"doi": "10.1101/2021.04.25.441302"
}
]
}
}
}
Defining work and status types for different scholarly outputs is one of the more challenging aspects of this effort. The PSO and FaBiO ontologies, while comprehensive, were designed for a world without much transparent article evaluation. We are working with the ASAPBio Peer Review Taxonomy group to define terms, and will propose adding them to SPAR ontologies once that group has completed its work. In the meantime, we are using the following convention to describe different outputs of evaluation processes.
Description | Crossref Name | sciety Name | Docmap Term | Docmap Alias |
---|---|---|---|---|
An evaluation that results in a recommendation |
| evaluation |
| TBD. For now, use the PSO term. |
An evaluation that does not result in a recommendation |
| evaluation |
| TBD. For now, use the PSO term. |
Text of an individual evaluator’s evaluation |
| review |
| review |
An author’s response to evaluations |
| author response |
| author-response |
A summary of an entire round of evaluations |
| evaluation summary |
| evaluation-summary |
A letter sent to authors describing the results of the evaluation |
| decision letter |
| decision-letter |
It is best practice to provide dereferenceable IDs to inputs and outputs, but we expect that Docmap providers will commonly provide inline FaBiO object parts, such as:
{
"type": "review-article",
"published": "2021-04-23",
"content": [
{
"type": "web-page",
"url": "https://ncrc.jhsph.edu/research/evidence-for-increased-breakthrough-rates-of-sars-cov-2-variants-of-concern-in-bnt162b2-mrna-vaccinated-individuals/"
},
{
"type": "web-page",
"url": "https://sciety.org/articles/activity/10.1101/2020.11.09.374330#ncrc:c0e4f483-eb58-4c13-b475-66c3d86fb430"
}
]
}
People are commonly referenced both as actor
s within step
s and creator
s of output
s. In both cases, the best practice is to reference people using their ORCID in the ID field, which is a dereferenceable IRI, and to provide a givenName
and familyName
for consumers who are unable to dereference, like so:
{
"id": "https://orcid.org/0000-0003-3440-0259",
"type": "person"
"givenName": "Narayanan",
"familyName": "Shivakumar"
}
In the absence of an ORCID, the given and family names can be provided without an ID. In these cases, it is best practice to add a blank node identifier (e.g. _:p0
) to the first reference of the person so that they can be referenced later if mentioned more than once.
JSON-LD arrays do not guarantee an order. Thus, steps should be ordered by assigning each step a blank node identifier (e.g. _:b0
) and referencing them using first-step (pwo:hasFirstStep
) at the top of the Docmap, and next-step (pwo:nextStep
) and previous-step (pwo:previousStep
) in each step, as so:
{
"type": "docmap"
"first-step": "_:b0"
...
"actions": [
"_:b0": {
"next-step": "_:b1"
...
},
"_:b1": {
"previous-step": "_:b0",
"next-step": "_:b2"
...
}
"_:b2": {
"previous-step": "_:b1"
...
}
]
}
We have deliberately refrained from specifying how step
s should be grouped. In general, you should try to be as transparent as possible, using as many steps as needed to accurately describe the process. In practice, however, we expect that many people will not have granular access to data, and will describe processes in a single, or just a few, step
s.