ODD-API: A REST Interface for Programmatic Use of ODD Schema Definitions

The ODD-API provides a REST interface that enables programmatic access to ODD schema definitions [Viglianti 2019]. In contrast to traditional approaches, where ODD documents must be manually processed with XML tools, this API offers a standardized method to query information about elements, attributes, classes, and modules of a schema via HTTP.

By using the JSON:API format [Yehuda et al. 2022], the API is particularly user-friendly and compatible with any programming language that supports HTTP requests. The API is documented according to the OpenAPI specification [OpenAPI Initiative 2024], allowing applications built on the API to be developed simply and efficiently without having to understand the complex ODD structure nor XML.

Originally, the API (in version 1) was developed as a backend for the MEI ProfileDrafter (a lightweight ODD editor for MEI customizations), but it had a generic approach from the beginning and also allowed the use of TEI ODD schemas. This generic approach will be further expanded with version 2 of the API, making the ODD-API usable as a central hub for ODD schema definitions in general, creating various new application possibilities. The API can thus serve as a foundation for developing tools to compare ODD schemas (or different versions of a schema), to edit ODD documents, to visualize dependencies between ODD schemas, for learning platforms to teach ODD knowledge, or dynamic documentation systems to complement existing static websites.

Implementation

As an initial implementation for the ODD-API scheme, we relied on the eXist database and XQuery. Various ODD schema definitions (e.g., teip5subset.xml) are stored in defined database collections by type and version (e.g., /db/apps/odd-api/data/tei/v4.9.0); additional ODD schema definitions may be loaded by dedicated endpoints. Currently, the following endpoints for GET requests are implemented:

●      /v2/schemas: returns a list of all available schemas in JSON:API format

●      /v2/{schema}: returns a list of all versions of a schema in JSON:API format

●      /v2/{schema}/{version}: returns the version of a schema as “Compiled TEI ODD” in XML format

●      /v2/{schema}/{version}/elements: returns a list of all elements in JSON:API format

●      /v2/{schema}/{version}/attributes: returns a list of all attributes in JSON: API format

●      /v2/{schema}/{version}/classes: returns a list of all classes in JSON:API format

●      /v2/{schema}/{version}/modules: returns a list of all modules in JSON:API format

The response for the endpoint /v2/tei (on a local test instance at http://localhost:8080) in JSON:API format looks like this:

{
  "data": [
    {
      "type": "versions",
      "id": "version_tei_4.6.0",
      "attributes": {
        "version": "4.6.0"
      },
      "links": {
        "self": "http://localhost:8080/v2/tei/4.6.0"
      }
    },
    {
      "type": "versions",
      "id": "version_tei_4.8.1",
      "attributes": {
        "version": "4.8.1"
      },
      "links": {
        "self": "http://localhost:8080/v2/tei/4.8.1"
      }
    }
  ],
  "links": {
    "self": "http://localhost:8080/v2/tei"
  }
}

According to the JSON:API specification, each object must contain a type attribute and an id attribute. The latter must be unique within the API, so in this example, the version number is prefixed with the type and the schema name. The pure version number is returned in the attributes object.

Application Scenarios and Outlook

A concrete current application scenario for the ODD-API is its use as an information resource for the ODD editor Roma. Roma is to be further developed to allow editing of non-TEI schemas and requires canonical addresses of ODD resources as starting points for customizations. Here, the ODD-API can serve as a central point to provide this information. To enable this in other contexts as well, only the URL of the ODD-API (analogous to the URL of the TEIGarage) would need to be specified as a parameter in the Roma code. Private Roma instances could then address any other ODD-APIs with any ODD schema definitions without having to adapt the source code of Roma or the ODD-API.

Beyond that, it would also be possible to open the ODD-API for PUT requests (and potentially also POST and PATCH) and thus also allow adding and editing ODD schemas. This would enable even stronger dynamization of the ODD-API and could be used, for example, in automated pipelines. However, this would then require appropriate authentication and authorization as well as guidelines for handling additions by third parties.

Finally, it would also be possible to develop an ODD package manager, i.e., an “npm for ODD schemas.” This package manager could have an integrating effect for the ODD community by highlighting the diversity and possibilities of ODD schemas on the one hand, while promoting standardization on the other. The API defined here would provide the underlying engine for such a hypothetical package manager.

Bibliography

●         Katz, Yehuda, Dan Gebhardt, Gabe Sullice, and Jeldrik Hanschke. 2022. “JSON:API Specification.” https://jsonapi.org/

●         OpenAPI Initiative. 2024. “OpenAPI Specification v3.1.1.” https://spec.openapis.org/oas/v3.1.1

●         Viglianti, Raffaele. 2019. “One Document Does-it-all (ODD): a language for documentation, schema generation, and customization from the Text Encoding Initiative.” Presented at Symposium on Markup Vocabulary Customization, Washington, DC, July 29, 2019. In Proceedings of the Symposium on Markup Vocabulary Customization. Balisage Series on Markup Technologies, vol. 24 (2019). https://doi.org/10.4242/BalisageVol24.Viglianti01.

Authors

Anne Ferger is a Research Associate at the University of Paderborn. Currently she works mainly on sustainable research tools and software development in the context of NFDI4Culture and FAIR research data management.

Johannes Kepper is Professor for Digital Music Philology at Paderborn University.

Peter Stadler is managing director of the Zentrum Musik—Editionen—Medien (ZenMEM) at Paderborn University. He is a long-time enthusiast of both MEI and TEI and has been a member of the TEI Council for several years.

Raffaele Viglianti is a Senior Research Software Developer at the Maryland Institute for Technology in the Humanities, University of Maryland. His research is grounded in digital humanities and textual scholarship, where “text” includes musical notation. Dr. Viglianti is currently an elected member of the Text Encoding Initiative technical council and the Technical Editor and Micro-Editions Co-Editor for the Scholarly Editing journal.