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: 

1. The backend action verb (e.g. execute, post) is omitted: circulation.internal.apply-rules , circulation.override-patron-block, okapi.env.list

2. The frontend action verb (e.g. edit, execute) is omitted: ui-users.loans.renew, ui-users.loans.renew

3. The general postfix ui-orders.third-party-services, ui-users.feefineactions, ui-users.accounts

4. Using non-standard action verbs: user-import.add, ui-users.loans.anonymize, mod-settings.global.read.ui-ldp.admin, ui-inventory.instance.createOrder

5. 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.