This document declares the naming conventions, which enable consistency.
Note that some early modules did not follow some aspects of these naming schemes.
Choose all names carefully, as there are various ramifications to later changing that.
In most cases (except when camelCase is required) use hyphenation to join words in a name, i.e. hyphen-separated strings (sometimes referred to as dash-separated).
The guide to commence a new module explains a typical directory layout and standard filenames.
Each module has its own git repository.
Take care to choose wisely for the module/repository name. It will be disruptive to change that.
Note that the repository name is normally the same as the module name. The module name can be different, but that can lead to trouble.
Back-end modules do have a limit of 31 bytes for the module name, and must be composed of only lowercase letters, digits, and hyphens. Other restrictions for back-end module names are specified at the Wiki Tenant ID and Module Name Restrictions.
The name uses the following scheme with a consistent prefix and hyphen-separated words:
mod-prefix for back-end modules (e.g. mod-users, mod-inventory-storage).
edge-prefix for back-end modules that connect to systems external to FOLIO (in particular, endpoints for standard protocols like NCIP)
stripes-prefix for Stripes modules (e.g. stripes-core).
ui-prefix for front-end UI modules (e.g. ui-users).
ui-plugin-prefix for front-end UI plugin modules (e.g. ui-plugin-find-instance).
ui-handler-prefix for front-end UI handler modules (e.g. ui-handler-stripes-registry) that consume, i.e. handle, events such as LOGIN and LOGOUT published by stripes-core.
folio-prefix for utility library modules (e.g. folio-isbn-util).
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 are defined in each module’s ModuleDescriptor.
The naming scheme is a faceted dot-separated string, with the delimited terms as hyphen-separated words.
The first portion is the exact name of the responsible module (back-end modules drop the
- mod-users declares
- mod-inventory-storage declares
- ui-users declares
JSON key names use camelCase.
- mod-inventory-storage defines
- All modules use
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 hyphen-separated strings.
It is normally the same as the set of
pathPatterns for which it provides handlers.
- mod-inventory-storage provides various interfaces including
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
These Okapi interface names start with underscore, e.g. the Tenant Interface
JSON API is de facto standard for defining REST JSON interfaces.
The back-end modules define their routes and API endpoints in their API descriptions, and declare the endpoints as the pathPatterns in the interfaces defined by their ModuleDescriptor.
Endpoints use hyphen-separated strings, with URI parameters as camelCase. There is no trailing slash.
- mod-inventory-storage declares
All backend modules are required to provide the module health check
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.
Release branches and tags
Each release is tagged in git, with a name beginning with
v and followed by the version number (e.g.
There are long-lived release branches, with a name beginning with
b and followed by the major and minor version number (e.g.