A set of naming conventions for permissions

The components of the permission names should be used in a hierarchical manner, from the most general (module) to the most specific (action). The permission name should contain the following components separated by a dot.

1. Module-Specific Prefix

Convention: Start with a service-specific prefix indicating the Folio module. The mod- prefix should be excluded.
Example: finance-storage in finance-storage.budgets.item.post
Example: notes in notes.item.put

2. Resource Identifier

Convention: Follow with a resource identifier, specifying the particular resource is being accessed or modified.
Example: budgets in finance-storage.budgets.item.post.
Example: fiscal-years in finance-storage.fiscal-years.item.delete

3. Entity Scope

Convention: Indicate the scope of the operation: whether it's for a single entity (item) or multiple entities (collection).
Example: item in finance-storage.budgets.item.post signifies an operation on a single budget entity.
Example: collection in finance-storage.budgets.collection.get signifies an operation on a collection of budget entities. This is often used for for “get-by-query” or “delete-by-query” operations.

4. Procedural Permissions

Convention: Use a clear and descriptive name for procedural permissions, usually ending with an action verb.
Example: invoice-transaction-summaries.execute in finance.invoice-transaction-summaries.execute
Example: check-out-by-barcode.post in circulation.check-out-by-barcode.post

5. Action Verb

Convention:
- Backend permission action verbs: Use HTTP-like verbs to specify the action. The available action verbs are:
  - get for retrieval
  - post for creation and execution
  - put for updates
  - patch for partial updates
  - delete for delete
  - execute for execution
- Frontend permission action verbs are:
  - view for viewing of entities
  - edit for edit of entities
  - create for creation of entities
  - delete for deletion of entities
  - enabled - single permission for the module, that marked it “enabled“
  - execute - for actions' executions
  - manage - any kind of aggregators or when execute sounds weird
Example: post in finance-storage.budgets.item.post indicates a creation operation, create in "ui-inventory.item.create"

6. Settings Permissions

The settings permissions should not have action verb.

Example: ui-inventory.settings.call-number-types

7. General Permissions

Convention: For broad or general permissions that encompass multiple actions or resources, use a comprehensive term followed by all.
Example: funds.all in finance.funds.all indicates a permission that applies to all actions related to funds.

Use of punctuation

As described above, permission names are segmented, with segments delimited by dot/period .

Within each segment, there is sometimes a need for further segmentation. E.g. check-in-by-barcode or inventory-storage. These segments are usually delimited by dash/hyphen -. When translating these permissions to corresponding resource/action, these dashes/hyphens are carried forward. For instance:

Given permission ui-inventory.call-number-browse.view you end up with:
- resource: UI-Inventory Call-Number-Browse
- action: view
Given permission orders-storage.po-lines.item.get you end up with:
- resource: Orders-Storage Po-Lines Item
- action: view

As shown in the examples above, when forming the resource name, the hyphens/dashes are carried forward and the dots/periods are replaced by a single space when forming the resource name.

Underscores, while not commonly used in permission names, are technically valid. These, like dot/period are replaced by a single space when forming the resource name. For example:

Given the permission erm.sts_for_platform_id.collection.get you end up with:
- resource: Erm Sts For Platform Id Collection
- action: view

Current naming conventions violations

The wiki page Permissions violations lists permissions which do not align with the naming conventions described herein. Common convention violations include:

The backend action verb (e.g. execute, post) is omitted: circulation.internal.apply-rules , circulation.override-patron-block, okapi.env.list
The frontend action verb (e.g. edit, execute) is omitted: ui-users.loans.renew, ui-users.loans.renew
The general postfix ui-orders.third-party-services, ui-users.feefineactions, ui-users.accounts
Using non-standard action verbs: user-import.add, ui-users.loans.anonymize, mod-settings.global.read.ui-ldp.admin, ui-inventory.instance.createOrder
Adding additional details after the action verb: ui-bulk-edit.view.base,

Conclusion

These conventions should help in maintaining a structured and clear approach to defining permissions, making it easier for developers and administrators to understand and manage access controls within the Folio.

Permissions naming convention