All About Texts, Volunteering for Tests (June 2024, Issue 1)

Want to get this quarterly newsletter in your inbox? Sign up today for the Sefaria Developer's Digest.

Welcome to the Sefaria Developers’ Digest! We’re so grateful to have you with us. Since its founding, Sefaria has always been a project committed to open source technology and resources. We believe in the power of data free and reusable by all.

Since the launch of the Sefaria Developer Portal in early 2024, we’ve heard so many incredible reports from members of our developer community who are building important and interesting projects with our open data. I’m reminded of a verse from Kohelet 4:9, “Two are better off than one, in that they have greater benefit from their earnings.”

We engineers are one team hard at work innovating, digitizing our texts, and sustaining our library. However, we can’t usher the Torah into the digital age alone. Thanks to you — our partner developers, engineers and technologists — we’re able to build something so much bigger, for the “greater benefit” of us all. I look around and see a thriving, rich, and deep ecosystem of Torah technology that serves anyone and everyone looking to access Jewish texts and spirituality digitally.

In this spirit of collaboration, we hope this newsletter will help you in your building efforts. We’re excited to offer some tech tips, an insight into our engineering work behind the scenes, and a new opportunity to contribute directly to Sefaria’s codebase.

We can always build more when we build together.

Until next time,
Sarah Kreitman
Junior Software Engineer

P.S. Building something cool with our API? Have questions or feedback to share? We’d love to hear from you!

HOT OFF THE PRESSES: Playwright Tests

Want to contribute your technical abilities to Sefaria? We’ve opened up a public GitHub project to invite our community to help us write Playwright tests for our site. All of the information can be found here. Help make us more resilient!

QUICK TECH TIP: Just the Text

Ever wanted to retrieve the text of a book of Tanakh without any vowels (nikkud) or cantillation markings? Here’s a neat trick: we have a version for books of Tanakh called Tanach with Text Only. When querying the v3 texts API for your specific text, you can pass in the parameter version=hebrew|Tanach with Text Only which will tell the API to return the text, and only the text, without any vowels or cantillation markings.

Behind the Scenes

Since the launch of the Sefaria Developer Portal, our community of developers has been helping us improve our API. We’re always grateful to hear what’s working — as well as what’s not working! One issue that’s been brought to our attention multiple times is an inconsistency in the way we handle text requests when a user passes in a complete book as the reference. For some books (such as books of Tanakh) this works, but for others this process returns an error message. Above, you can see the inside of that error message when developing locally.

We look at the books in our library as (loosely) falling into two categories — simple texts and complex texts (for a more detailed discussion, see the linked documentation). Simple texts are represented by a straightforward nested array structure, whereas complex texts are represented using both arrays and nodes we call SchemaNodes to help represent the more complicated text structure. Currently, our texts API will return text for simple texts (such as books of Tanakh) but error when someone tries to retrieve the entirety of a complex text (such as Abarbanel on Torah, in the example above).

In the meantime, if you wish to retrieve the entirety of a text via the API (as opposed to any of our other download methods) you need to iterate through API calls to more specific chunks of text. Inside the JSON, a ‘next’ field is returned, which provides the subsequent text reference to query.

We are working through approaches to this functionality — and also working to improve our error messaging so it’s more helpful. Please continue to let us know when you run into trouble, what you’d like to see from our API, and other ways we can help support our foundational data as you build the future of Torah.

Spotlight: Powered By Sefaria

Shulkhan: A Touch Interface for the Printed Talmud

What if you could connect the powerful resources available in Sefaria’s library to a physical page of Talmud? This was the question that got Joseph Tepperman thinking one day during the pandemic shutdown. “To combine a reverence for the Vilna Shas with a general need for English translation, my idea was to access Sefaria directly from the Vilna Shas page itself,” wrote Tepperman when explaining the premise of the project, “What if, by pointing to a word or a line, I could highlight the section I was interested in, then project its translation directly onto the table in front of me, without ever having to open my computer or break out my phone?” This is exactly what he ended up building — a combination of an overhead projector, a webcam, and a lot of Sefaria’s open source data. He called the result Shulkhan (table), and it was this fantastic innovation that earned him an honorable mention in the inaugural 2020 Powered by Sefaria contest.

Want to get this quarterly newsletter in your inbox? Sign up today for the Sefaria Developer's Digest.

Your donation powers the future of Torah - for all.

Sefaria’s resources have always been free to use — and that will always be true.
Join the community of Sefaria supporters who are the force behind new resources, new tech, new tools, and more.