OSCR

Block identifiers

Each match between a paragraph of a paper and lines of its authors' code has a block identifier, such as oscr:b:ZJPAX6KPXPETB-7. It names those lines, in that file, linked to that paper, and it is never reused nor deleted: you can cite it, and its address keeps answering.

What a block identifier is

A block is a run of lines of one file of the authors' code that the registry links to a paper: the lines that do what a paragraph of the paper describes. Its identifier is oscr:b:, then 13 letters and digits, a dash and one check character. Its page is /b/oscr:b:ZJPAX6KPXPETB-7.

How it is made

  • It is computed from three facts: the paper's DOI, the file's SWHID (the Software Heritage identifier of the file as its authors published it, the same fingerprint as git hash-object), and the lines. The same block always gets the same identifier, and anyone can compute it again.
  • The SWHID is computed from the exact bytes whose SHA-256 OSCR verified, before any email address is hidden for display. A file whose text here is not exactly those bytes (cut short, or a notebook kept as its cells) gets no SWHID, and its matches get no block identifier: only what was verified is named.
  • The 13 characters use Crockford's base32, without I, L, O or U, so it reads aloud and copies without confusion. The last character is a check (ISO 7064 MOD 37,36, the scheme ORCID uses): a mistyped identifier is reported as such, never sent to another block. Lower case, and an O written for a zero, are read correctly.

Where you find it

  • On a paper's page, in the list of matches of the Code ↔ Paper reader: each match shows its block identifier.
  • On a paper's page built on request, in the Code section, under "Code blocks with an identifier".
  • In the citation the reader's Cite button copies, when the lines you selected are a block (see below).
  • In the API and the bulk files: each match of alignments.jsonl, and each paper's record.

Citing a block

In the reader, select a match (or lines inside it) and press Cite: the button reads "Cite block oscr:b:…", and it copies the block's identifier and page first, then the file and lines, the paper's DOI, the SWHID with its context and the link to these lines on the paper's page. For example:

Code block oscr:b:ZJPAX6KPXPETB-7 (https://openscicode.org/b/oscr:b:ZJPAX6KPXPETB-7)
fig_mtnn/mtnn.py, lines 316 to 451, in int-brain-lab/paper-reproducible-ephys (https://github.com/int-brain-lab/paper-reproducible-ephys), commit 2397f2c….
Paper: https://doi.org/10.7554/elife.100840
SWHID: swh:1:cnt:e5e096d4…;origin=…;anchor=swh:1:rev:…;path=/fig_mtnn/mtnn.py;lines=316-451
https://openscicode.org/paper/doi_10.7554_elife.100840/?path=fig_mtnn/mtnn.py#L316-L451

Lines that are no block are cited by their SWHID alone (citing a piece of code).

A block's page

/b/<identifier> says what the block names: the paper and its page, the repository, the file, the lines and the function, the commit read, the SWHID, the paragraphs of the paper it was matched to, who linked it, and the day it was given. It links to these lines beside the paper. The same facts, for a program, are at /b/<identifier>.json.

Current, superseded, withdrawn

  • Current: the registry links these lines to the paper today.
  • Superseded: the code or the match changed, and these exact lines are no longer linked. The identifier stays and names what it named; its page links to the block of the same file that replaced it, if any.
  • Withdrawn: the paper left the registry, or a removal request withheld its code or its map. The page stays, and says so; it no longer shows the file, the lines or the code.

For programs

  • GET /b/<identifier>.json and GET /api/v1/blocks/<identifier>: one block (CORS open).
  • GET /api/v1/paper/<doi>: a paper's record, its blocks in blocks.
  • The bulk alignments.jsonl: each match with its block. See the API guide.

What it is not

  • It is not a DOI. A tracing map validated by an author gets a DOI on Zenodo, and its file lists the identifiers of its blocks (tracing maps).
  • Most blocks are linked by the registry's matching program, which can be wrong: the page says who linked each one. You can report a wrong match from the reader ("Report a mismatch").
  • The code stays its authors', under its own licence, at its source: the identifier names it and holds no copy.