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. It is the thing an author validates, and the only thing 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 — and holds neither the text of the paper nor the code: it points to them.

What it holds

  • The paper: its DOI, title, journal, date and authors.
  • The code, 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.
  • The matches: for each, 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: proposed by the harvester on a given day; validated by whom, once validated.

Its life: proposed, validated, deposited, corrected

  1. Proposed. The harvester makes it, and the paper's page shows it, marked "proposed by the machine", without a DOI.
  2. Validated. 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. Deposited. 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. Corrected. A later correction, validated again, becomes a new version of the same Zenodo record, under the same concept DOI: 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 never 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 — a new commit, a new match — the validation is not deposited, and the author is asked to look again: the map that receives a DOI is always the one the author saw.

A map withheld

A map may be withheld at an accepted removal request: its section then says so, with neither digest, matches, validations nor DOI on the site, in the open data or in the search. A DOI already given stays on Zenodo — a DOI is permanent — but the site no longer shows 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.