Text References

Avi Levin edited this page Jun 16, 2016 · 5 revisions

Text References (a.k.a Citations)

Sefaria depends on the ability to unambiguously refer to particular segments of text in the repository. The implementation of text references in Sefaria has the following goals:

  1. References should be human and machine readable.
  2. References should be environment agnostic (i.e., they should not dependent on database ids).
  3. References should flexibly accommodate human variation, such as alternate spellings.

The following are all valid refs:

  • Bereishit
  • Job 3
  • Mishna Berakhot 4.2
  • Sanhedrin 4b
  • Ex. 12:2-8
  • Song_of_Songs.2.4-3.3
  • Berakot.2a.10-13
  • Rashi on Genesis 1:2:1
  • M. Peah 3
  • Rambam Laws of Repentance 2:1
  • Masekhet Shabbat 7b:12-20
  • Pirkei_Avot_2.1

A valid ref consists of a title string followed optionally by a sections string. A title string is any one of the known text titles or title variants. It could also be a commentator name followed by the word "on" followed by another title string. A section string lists sections separated by either ., : or . A range can optionally be specified with -.

Notes

  • Talmud references use a special daf syntax, which allows a number plus either 'a' or 'b'.
  • Commentary text names inherit the structure (depth and section names) of their base text and add an additional level called 'Comment'. Thus Ramban on Genesis 4:5:2 refers to Ramban's 2nd comment on the 5th verse of Genesis Chapter 4.
  • Within a sections string, ., : and are all interchangeable.
  • The range separator - should appear 0 or 1 times and should never appear in the title string.
  • Spaces may be replaced with _ for better display in URLs, but not by - for the reason above.

Classes of references we don't yet support

  • Appearance location of reference informs target of the reference

    • "שם", "ibid", etc. (Note that partial references can include שם - like "שמות שם"
    • להלן, לקמן
    • בסימן ...
  • References by Dibbur Hamatchil

  • References by Perek Name
  • References in the discursive flow of the text