Custom Fields Support for Inventory Entities (Items, Holdings, Instances)

Overview

Custom fields in FOLIO allow libraries to define and manage additional data fields that are not part of the core schema. This is particularly useful for tailoring records to local workflows or tracking institution-specific data. The functionality is already supported in other domains such as Users and Orders, and has now been requested for the Inventory application as well.

Custom fields also play an important role during data migration when switching from legacy library systems to FOLIO, as they provide a flexible way to preserve institution-specific data that may not map cleanly into FOLIO's standard data model.

This effort will enable:

Library staff to define and manage custom fields in the UI
Storage of custom field values per entity (e.g., Item)
Search support for custom field values
Consistent API behavior via the shared folio-custom-fields backend library

Scope of Implementation

Custom fields will be added for all Inventory entities:
- Instance
- Holdings
- Item
The initial implementation will focus on the Item entity, providing the basis for definition, storage, and search of custom field values at the item level.
Once the work on Items is completed and tested, support for Instances and Holdings will follow in future phases.

The following modules are directly affected by the implementation:

Module	Responsibility

Module	Responsibility
`mod-inventory-storage`	Exposes custom field APIs and stores field definitions and values
`ui-inventory`	Provides the user interface to manage custom field definitions and input values
`mod-search`	Enables searching by custom field content via CQL and Elasticsearch indexing

Implementation Breakdown

https://folio-org.atlassian.net/browse/UXPROD-5370

The following tickets cover the foundational work for enabling custom fields on Items:

https://folio-org.atlassian.net/browse/MODINVSTOR-1445 Integrate folio-custom-fields library into mod-inventory-storage to expose API endpoints for managing field definitions.
https://folio-org.atlassian.net/browse/MODINVSTOR-1446 Extend the Item schema to store custom field values as part of the item record.
https://folio-org.atlassian.net/browse/UIIN-3335 Add a settings section in the UI to allow users to define and manage custom fields for Items.
https://folio-org.atlassian.net/browse/UIIN-3343 Update View/Create/Edit forms in the Item UI to display and persist custom field values.

https://folio-org.atlassian.net/browse/UXPROD-5372

To enable searching by Item custom fields it is planned to use the dynamic indexing feature of Elasticsearch/OpenSearch, as the exact field names and types are defined at runtime via folio-custom-fields APIs and are subject to change by users at any time.

See https://www.elastic.co/docs/manage-data/data-store/mapping/dynamic-mapping, https://docs.opensearch.org/docs/2.4/opensearch/mappings/#dynamic-mapping.

Index Mapping

A dynamic mapping for customFields on the item level can be defined in instance.json:

mod-search/src/main/resources/model/instance.json:

"items": {
  ...
  "customFields": {
    "type": "object",
    "dynamic": true,
    "properties": {}
  }
  ...
}

This setup allows to index any arbitrary field under items.customFields with type inference (e.g., boolean, text).

Current Limitation in `mod-search`

While Elasticsearch/OpenSearch itself supports dynamic indexing, mod-search does not currently support querying dynamic fields via CQL due to its validation logic:

CQL queries are strictly validated before execution
There is no support for wildcard search aliases like items.customFields.*
Adding a dynamic mapping in instance.json alone is not sufficient
Mapping is present in Elasticsearch/OpenSearch, but cannot be queried via mod-search unless fields are explicitly registered

Implications

Even with dynamic indexing enabled, custom field removals or type changes require a reindex to update the mapping
There's no mechanism in mod-search to dynamically register or unregister CQL search fields based on custom field definitions
Without changes to mod-search, users won’t be able to search on custom fields at the Item level

Request for Feedback & Next Steps

We are seeking feedback and guidance from the mod-search development team before moving forward:

Dynamic CQL Support:
Would it be possible to support dynamic CQL search fields like items.customFields.*, given that field names and types are user-defined and change at runtime?
Alternative Modeling:
Is there a recommended alternative approach for modeling or exposing custom fields in a way that is compatible with mod-search’s CQL validation?
Runtime Field Registration:
Are there plans or best practices for introducing runtime field registration (e.g., via API) to automatically support new custom fields as they are created?

Once the approach is validated and the search capability for custom fields on Items is stable, the same implementation pattern will be extended to Holdings and Instance records to ensure comprehensive custom field support across the entire Inventory domain.