Commentaries in Sefaria

Brett Lockspeiser edited this page Nov 15, 2017 · 4 revisions

A Bit of History

Changes in Commentary Refactor:

The Sefaria code and database generally treats commentaries the same as regular texts. This means that commentary texts have their own individual Index and Version records. Previously, Sefaria had treated commentaries as subordinates to their base text. For example, the text Rashi on Genesis did not have it's own records in the system. This was done to offer some benefits (automatic linking to base texts, ability to generate new Index records on the fly).

This design began to show its limitations, so we decided to support commentaries just like regular texts, while adding in the convenience features on an optional basis.

To this end, some new optional attributes on index records were introduced:

New attributes on Index records:

  • dependence - String. Generally "Commentary" or "Targum" - to denote commentaries and other potential non-standalone texts.
  • base_text_titles - List of strings - the base book(s) this one is dependent on.
  • base_text_mapping - String. Matches a key in sefaria.helper.link.AutoLinkerFactory._class_map. So far, two options exist: "one_to_one" and "many_to_one". (This helps maintain the autolinking feature once afforded commentaries by default. It also makes room to expand and have various algorithms for linking between a dependent text and it's base text/s)
  • collective_title - String. Value for a group of index records - Used to contain the former commentator name which was once the primary handle on a commentary. Now used to group many commentaries belonging to a larger corpus. Requires a matching Hebrew Term.
  • is_cited - Boolean. By default, only references to texts who's index record has this attribute set to True, will be picked up as a citation in another text referencing them.

Example:

"title": "Ramban on Genesis"
"base_text_titles": [
   "Genesis"
],
"base_text_mapping": "many_to_one",
"collective_title": "Ramban",
"dependence": "Commentary",
"categories": ["Tanakh", "Commentary", "Ramban", "Torah"]  

Terms:

Another change meant to streamline adding information was the larger use of terms throughout the data Sefaria uses. Terms are used to group titles, alternate titles and titles in other languages (i.e. Hebrew). Some objects, such as Index records store their own various titles. But for other system objects that is not currently a possibility.

To this end, we use terms to add titles to items that need them, such as categories, section names etc. When creating an Index record with a new English titled element (e.g. a new sub category in the Table of Contents) a corresponding Term must be added to supply, at the very least, a matching Hebrew title.

Example Terms API Payload:

term_obj = {
    "name": "Ramban",
    "scheme": "commentary_works",
    "titles": [
        {
            "lang": "en",
            "text": "Ramban",
            "primary": True
        },
        {
            "lang": "he",
            "text": u"רמבן",
            "primary": True
        }
    ]
}
full_url = "http://whatever.server.exmp/api/terms/{}".format(urllib.quote("Ramban"))

Alternatively, you can use the post_term method located in sources/functions.py in Sefaria-Data:


from sources.functions import post_term
term_obj = {
    "name": "Ramban",
    "scheme": "commentary_works",
    "titles": [
        {
            "lang": "en",
            "text": "Ramban",
            "primary": True
        },
        {
            "lang": "he",
            "text": u"רמבן",
            "primary": True
        }
    ]
}
post_term(term_obj)

Category

Another important thing that has changed is that the category "Commentary" never comes first in a category list, and there is no more "Commentary2" category used.

Remember: Each category also requires a matching Hebrew Term! So if you are creating a text with a heretofore unknown category, you must add a Hebrew term for it as described above.

The categories are to be used chiefly to denote where the book will show up in the Sefaria main Table of Contents. This means that in the above/following example the text "Ramban on Genesis" will show up inside the Torah category, inside the Ramban category which in turn is in the Commentary section of the Tanakh main table of contents section.

  • For a commentary, the category "Commentary" generally comes after one top level category . E.g. ["Tanakh", "Commentary", "Ramban", "Torah"]

  • In some cases, it comes after two categories, particularly for Talmud. E.g. ["Talmud","Bavli","Commentary","Rashi"]

You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.