Skip FOLIO Project Navigation

GitHub and Twitter:

This document declares the naming conventions, which enable consistency.

Introduction

Note that some early modules did not follow some aspects of these naming schemes.

Choose names carefully, as there are various ramifications to later changing that.

The guide to commence a new module explains a typical directory layout and standard filenames.

Module names

Each module has its own git repository. The name uses the following scheme with a consistent prefix and dash-separated words:

  • mod- prefix for back-end modules (e.g. mod-users, mod-inventory-storage).
  • ui- prefix for front-end UI modules (e.g. ui-users).
  • stripes- prefix for Stripes modules (e.g. stripes-core).

Most module names will be in the plural sense, e.g. mod-notes, especially when responsible for collections of items.

Some back-end modules are paired. For example mod-inventory is the business logic module, while mod-inventory-storage is the associated storage module. Having such a stem name, enables dividing a module into more layers.

The version number of a module uses semantic versioning.

Permissions

These are explained at Permissions in Stripes and FOLIO (with some further links via this FAQ).

Permissions are defined in each module’s ModuleDescriptor.

The naming scheme is a faceted dot-separated string, with the delimited terms as dash-separated words. The first portion is the exact name of the responsible module (back-end modules drop the mod- prefix).

Some examples:

  • mod-users declares users.collection.get
  • mod-inventory-storage declares inventory-storage.loan-types.collection.get
  • ui-users declares ui-users.view

Schema

JSON key names use camelCase.

Some examples:

  • mod-inventory-storage defines contributorNameTypes
  • All modules use totalRecords and id and metadata

Interfaces

The back-end modules define each interface that they provide, in their ModuleDescriptor. Each module can define more than one interface. Normally an interface is defined by only one module, but Okapi does allow different modules to provide the same interface by using multiple interfaces.

The name of an interface (its id) uses dash-separated strings. It is normally the same as the set of pathPatterns for which it provides handlers.

Some examples:

  • mod-inventory-storage provides various interfaces including item-storage and loan-types and others.

The version number of an interface uses the first two portions of semantic versioning. There does not need to be any correlation between the module version and the version of the interfaces it implements.

The back-end modules can also provide system interfaces. These Okapi interface names start with underscore, e.g. the Tenant Interface _tenant

JSON API is de facto standard for defining REST JSON interfaces.

API endpoints

The back-end modules define their routes and API endpoints in their RAML files, and declare the endpoints as the pathPatterns in the interfaces defined by their ModuleDescriptor.

Endpoints use dash-separated strings, with URI parameters as camelCase. There is no trailing slash.

Some examples:

  • mod-inventory-storage declares /contributor-name-types/{contributorNameTypeId}

The special prefix /_ is used to to distinguish the routing for the core endpoints of Okapi internal web services from the extension points provided by modules, e.g. /_/proxy

Release branches and tags

Each release is tagged in git, with a name beginning with v and followed by the version number – for example, v2.3.5.

There are long-lived release branches, with a name beginning with b and followed by the major and minor version number – for example, b2.17.

See further information for front-end and back-end modules.