Last Updated: 23-June-2017

The FOLIO Project is a sustainable, community-driven collaboration around the creation of a modern technology ecosystem that empowers libraries through open source applications to manage library resources and expand library value. As a technology project, FOLIO is a Library Services Platform (LSP) designed to enable new forms of library services while supporting traditional resource management functionality.

FOLIO Architecture

The FOLIO platform consists of two components: Stripes and Okapi. Stripes is a modular user interface toolkit for building web applications for FOLIO UI modules. Stripes UI modules are made up of React components, some of which connect to back-end services mediated by Okapi. Okapi is an implementation of some software design patterns commonly used within the microservice architecture. The most central of them is the “API Gateway” pattern implemented by the core Okapi ‘proxy’ service. HTTP requests from Stripes UI modules, from external-to-FOLIO applications, and between Okapi business logic and storage modules are proxied through the Okapi Gateway. The Okapi Gateway load balances requests between instances of Okapi business logic and storage modules in a clustered environment, enforces tenant isolation, and checks user permissions.

RESTful APIs and the Okapi Platform

Requests and responses for data through the Okapi Gateway closely follow the RESTful paradigm. JSON documents are proxied through the Okapi Gateway using HTTP C-R-U-D requests. HTTP POST-GET-PUT-DELETE operations against endpoints registered in the Okapi Gateway are routed to the appropriate Okapi Modules. An Okapi Module may call upon other Okapi Modules (again through the Okapi Gateway) to retrieve and modify data. For instance, when a business logic module for maintaining user accounts receives an HTTP request to create a new user account (POST /bl-users), that module makes calls to several storage layer modules to create records in the underlying persistent data storage: the credentials data storage (POST /authn/credentials), the permissions data storage (POST /perms/users), and the user metadata data storage (POST /users). Okapi Modules respond to the Gateway with appropriate HTTP status codes and optional JSON documents, and the Okapi Gateway returns that status code and document to the calling service.

In this way, the FOLIO Platform is made up entirely of RESTful HTTP interface contracts (HTTP endpoints and request/response document formats). The web browser, executing the JavaScript of Stripes UI modules, makes HTTP requests to Okapi Module interfaces that are proxied by the Okapi Gateway. The result is a highly decoupled architecture:

  • Machine interfaces to the underlying business logic and storage modules can be written in JavaScript using the Stripes/React components for web browser access, or can be accessed using mobile-native apps or from applications entirely outside of the FOLIO platform. Since front-end tools like React tend to have a shorter lifespan, it is likely there will be redevelopment in the browser UI while the FOLIO services running behind Okapi retain largely the same HTTP interfaces.
  • In focusing on single-purpose apps (such as Users, Circulation, Catalog, Invoices, and Purchase Orders), independent development teams can work in parallel while agreeing on the HTTP endpoints and the document formats exchanged between apps.
  • The Okapi Modules that perform the business logic and persistently store data can be written in any programming language as long as they maintain the interface contract. Implementations of Okapi Modules can be modified or integrated with external systems to meet the needs of a particular library.

Metadata and the FOLIO Codex

As a platform for library-centric apps, FOLIO’s approach to descriptive metadata is to create a high-level subset of metadata elements that all FOLIO apps must understand while retaining the detailed descriptive metadata record for apps that can understand and make use of that detail. For instance, the app that checks in and checks out physical books does not need to understand the precise nature of the MARC 245 indicators and subfields; it just needs a title to display on the screen to confirm to the operator that the item at hand is the item being checked out. Likewise, an app that counts the usage of a particular thesis does not need to understand the metadata elements that distinguishes a thesis advisor from the degree candidate. This subset of metadata is being called the FOLIO Codex.

The concept of a subset of common metadata elements is similar to Dublin Core. At the time of writing, the exact contents of the FOLIO Codex have not been established, but (like Dublin Core) it is anticipated to be somewhere between 20 and 40 elements. The Codex record is most often derived from a source record in a native metadata format such as MARC or MODS or PBCore or FGDC. In creating this subset, apps can operate on library holdings no matter which description format is used. When the native metadata format is changed, the corresponding FOLIO Codex record is regenerated. (The FOLIO Codex concept acknowledges that there can be records for which the Codex metadata format could be the native metadata format.)

A FOLIO Codex record contains a pointer to its source record, and Codex records can come from any number of sources (‘knowledge bases’). A typical library could have a silo of bibliographic records representing the physically held collection, records from one or more commercial content providers (e-serial and e-book platforms), and records from digital object repositories hosted by the library. Options are in development for handling deduplication and merging of records from multiple knowledge bases. Also under discussion is the ability to provide a local “overlay” of information that modifies the knowledge base record as well as functionality that can automatically update the stored copy of the knowledge base record when the source changes.

Potential for FOLIO Integration with Repository Services

The FOLIO Project believes the combination of a platform with RESTful interface contracts along with the Codex made up of descriptive records from many sources and formats represents a new, unique paradigm for offering services to library users and staff. Developed as open source software with openly defined interface contracts (HTTP endpoint and request/response document definitions), integration with the FOLIO platform can occur in many phases of the workflow of a patron’s or staff member’s workflow. Given the introduction of the FOLIO Platform above, the remainder of this whitepaper describes ways that repository software and services can integrate with FOLIO. It is not an exhaustive exploration, and the FOLIO community invites dialog on these and other areas of integration.

Using digital object metadata in FOLIO apps

FOLIO’s platform nature allows for a variety of integration points for libraries that are looking for comprehensive tools to manage resources. One source of knowledge base records for the FOLIO Codex can be the institutional repository (IR), in which case FOLIO apps can use IR objects as part of their workflows. IR metadata records then appear in the same displays with other knowledge base record sources, such as commercially purchased and licensed materials.

Add a digital object storage layer to the FOLIO Platform

At this time FOLIO does not have an interface contract for storing and retrieving digital objects. Some members of the FOLIO community have expressed interest in providing an abstract digital object service that could be used by FOLIO apps. This would enable FOLIO apps for thesis/dissertation/report submission, metadata enrichment workflows for objects added to the repository, and dissemination of objects to discovery layers.

Consuming authority metadata stored in FOLIO

One of the apps envisioned for the FOLIO platform is the creation and maintenance of local name and subject authority metadata. These authority records would be used as part of the cataloging apps in FOLIO. The RESTful API for creating, retrieving and searching local authority records can also be made available to the user interfaces of the repository software. In this way, there can be a single source of local authority metadata used by FOLIO and non-FOLIO applications.