OSCR

Tracing maps

A tracing map is the record of the links between a paper and the code its authors published: where the code is, which version, under which licence, what it holds, how it was found, and which paragraphs match which lines. An author validates the map, and the map is the only part of a record that can receive a DOI.

What a map is

Every paper with its authors' code has one, shown in its page's Map section. The harvester builds it from what it verified; an author of the paper can confirm it. A map is small, a few kilobytes of links and metadata. It does not hold the text of the paper or the code; it links to them.

What it holds

  • The paper's DOI, title, journal, date and authors.
  • For each repository the paper cites as its authors' code: its address, its state at the last check, its licence, the commit recorded and its date, its type, whether Software Heritage archived it, the level of evidence reached, where in the paper it was found, and its files, each file's path, language and digest (a SHA-256 of its text), so that anyone can tell later whether a file is still the one that was there.
  • For each match: the paragraph's number (its position among the paragraphs of the paper's open-access XML), its section's title, the file, the lines, the function or block, the score, the evidence terms and the method.
  • Its provenance: the day the harvester proposed it and, once it is validated, who validated it.

Its four stages

  1. The harvester proposes the map. The paper's page shows it, marked "proposed by the machine", without a DOI.
  2. An author of the paper, signed in with the ORCID iD the paper lists, reads it and validates it, after correcting its links if needed (how).
  3. The validated map is deposited on Zenodo, in the registry's community, and receives a DOI, which the page and the author's account show. The record links it to the paper (IsSupplementTo) and to the code at the validated commit (References); its creators are the author and the platform (the DOI policy).
  4. A later correction, validated again, becomes a new version of the same Zenodo record, under the same concept DOI, and the first version stays citable.

While the platform is being built, maps are deposited on Zenodo's sandbox, whose DOIs are not real, and a validation made with ORCID's sandbox is recorded as a test and is not published. The pages say "no DOI" until real deposits begin.

The digest

The page carries the digest of the map it shows: the SHA-256 of its content, leaving out the day it was proposed and who validated it. A validation carries that digest back. If the harvester changed the map in the meantime (for example a new commit or a new match), the validation is not deposited and the author is asked to look again. This way, the map that receives a DOI is the one the author saw.

A map withheld

A map may be withheld at an accepted removal request. Its section then says so, and the site, the open data and the search show no digest, matches, validations or DOI for it. A DOI already given stays on Zenodo, because a DOI is permanent; the site stops showing it.

The format

A map is a JSON file, tracing-map.json, format tracing-map/0.1. Its fields and an example are on Labs. Deposited maps are released under CC0-1.0: anyone may reuse them.