Introduction to TextAPI
The TextAPI specification defines a standardized, machine‑readable format for representing digital scholarly editions. It provides a unified data model that enables digital scholarly editions to be stored, exchanged, validated, and processed consistently across tools and platforms. At its core, the specification structures an edition into clearly defined components—metadata, textual content and serializations, and optional scholarly apparatus — ensuring both human interpretability and computational reliability.
Purpose and Conceptual Model
The specification establishes a JSON‑based framework for encoding digital scholarly editions and defines a corresponding REST interface. It models an edition as a structured object containing descriptive metadata, one or more text bodies, and optional layers such as annotations or references, for example to facsimiles. This approach supports both simple editions and complex scholarly projects with multiple text parts, contributors, and publication contexts. By defining explicit types, required fields, and relationships, the schema ensures that editions remain interoperable and can be validated automatically.
Core Structural Components
The TextAPI schema organizes an edition into several key components:
- Metadata — Describes the edition’s identity, contributors, licensing, and publication details.
- Text content — Represents the actual textual material, structured into blocks such as paragraphs, headings, lists, or quotations.
- Annotations — Optional scholarly layers that link commentary, references, or semantic information to specific text segments.
Each component is defined with clear constraints, enabling consistent parsing and rendering across different systems.
Interoperability and Extensibility
The specification is designed to integrate with digital‑humanities workflows. Its JSON‑based structure makes it compatible with modern web technologies, while its modular design allows projects to extend or customize components without breaking core compatibility. This balance of strict validation and flexible extension ensures that TextAPI can serve as a long‑term foundation for sustainable, interoperable scholarly editions.
What to Explore Next
Showcases
Seeing the specification in action is the fastest way to understand its strengths. Our showcases highlight a range of digital scholarly editions built with TextAPI — from minimal, clean reading editions to complex scholarly projects with annotations, facsimiles, and multi‑layered structures. These examples demonstrate how the schema supports different editorial philosophies and technical setups, helping potential adopters imagine how their own material could be represented. They are powered by TIDO, the viewer application built for TextAPI.
Starting with TEI documents
Many institutions already maintain extensive TEI‑encoded corpora. TextAPI is designed to complement — not replace — these investments. If you already work with TEI, you can explore TEI integration pathways such as:
- Transforming TEI to TextAPI for lightweight web delivery or API‑driven applications
- Using TextAPI as an interchange format between TEI repositories and modern frontend frameworks
- Combining TEI richness with TextAPI simplicity, keeping TEI as the archival source while generating TextAPI for publication layers
This hybrid approach allows projects to retain TEI’s expressive depth while benefiting from TextAPI’s clarity, interoperability, and ease of use.