Skip to content

Metadata Matrix field

The Matrix field renders structured data as an interactive table. Depending on the type, rows can be predefined or added dynamically at runtime, and columns can hold text inputs, checkboxes, or other supported field types.

Attribute Description Required
label The text shown as a label in the user interface. true
name Unique field identifier.
Two metadata fields can’t have the same name. The name must be unique.
The name must start with “okp:”.
Using the metadata group name as a basis for the metadata field name is good practice. For example, if “okg:contracts” has been used as the group name, use “okp:contracts.matrix” by changing “okg” to “okp”. That helps to find the metadata group based on the metadata field name.
Please use only letters, numbers, and underscores: “0-9a-zA-Z_”.		 true
type Defines the structure and interaction mode of the matrix table. Allowed values:
- dynamic (default): The table has fixed columns but no predefined rows. Users can add and remove rows freely at runtime.
- multi-select: The table has both fixed rows and fixed columns. Users can enter values in each cell using the configured column field types.
- single-select: The table has fixed rows and fixed columns. Each column is a checkbox, and the user must select exactly one checkbox per row. If a row has no checkbox selected, a validation warning is displayed.		 false
value Default value for the field. The value is stored internally as a JSON array of row objects. false
placeholder Placeholder text displayed in editable cells before the user enters a value. false
width The width of the matrix table element. Default: 100px.
In the KCenter UI, width values must be specified as percentages, for example:
- width=“100%” will work.
- width=“500px” will be ignored in the KCenter UI.		 false
height The height of the matrix table element. Accepts CSS size values (e.g. 200px). false
readonly When set to true, the matrix cannot be modified in the user interface. Default: false. false
description General description of the field. false
dbColumnSize Set the size of the database column where the matrix value is stored.
Matrix values are serialized as JSON and can be substantially larger than single-value fields. The default column size is 512 characters. Increase this value if the expected data volume exceeds that limit.
Take a look at the Metadata XML definition documentation section for a detailed explanation of how metadata is stored in the OpenKM database.
defaultAccess Default security access policy. By default, it is set to grant, so all users will see the field.
  • Child elements:

Dynamic matrix

Section titled “Dynamic matrix”

In dynamic mode, the table has no predefined rows. Columns are fixed, and users can add as many rows as needed at runtime. This is the default type when type is omitted.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.16//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.16.dtd">
<property-groups>
  <property-group label="Purchase Order" name="okg:purchase">
    <matrix label="Line Items" name="okp:purchase.line_items" type="dynamic" width="100%">
      <input label="Product Description" name="description" type="text"></input>
      <input label="Unit Price" name="unit_price" type="text"></input>
      <input label="Quantity" name="quantity" type="text"></input>
    </matrix>
  </property-group>
</property-groups>

Multi-select matrix

Section titled “Multi-select matrix”

In multi-select mode, both rows and columns are predefined. The table structure is fixed, and users fill in the cell values. Any supported column field type can be used.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.16//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.16.dtd">
<property-groups>
  <property-group label="Sales Planning" name="okg:sales">
    <matrix label="Quarterly Targets" name="okp:sales.quarterly_targets" type="multi-select" width="100%">
      <row label="Q1"/>
      <row label="Q2"/>
      <row label="Q3"/>
      <row label="Q4"/>
      <input label="Revenue Target" name="revenue_target" type="text"></input>
      <input label="New Clients" name="new_clients" type="text"></input>
      <input label="Region" name="region" type="text"></input>
    </matrix>
  </property-group>
</property-groups>

Single-select matrix

Section titled “Single-select matrix”

In single-select mode, the table has fixed rows and checkbox columns. The user must select exactly one checkbox per row. If any row is left without a selection, a validation warning is displayed.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE property-groups PUBLIC "-//OpenKM//DTD Property Groups 3.16//EN"
                                 "http://www.openkm.com/dtd/property-groups-3.16.dtd">
<property-groups>
  <property-group label="Risk Management" name="okg:risk">
    <matrix label="Risk Assessment" name="okp:risk.assessment" type="single-select" width="100%">
      <row label="Security Risk"/>
      <row label="Operational Risk"/>
      <row label="Compliance Risk"/>
      <checkbox label="Acceptable" name="acceptable"></checkbox>
      <checkbox label="Moderate" name="moderate"></checkbox>
      <checkbox label="Critical" name="critical"></checkbox>
    </matrix>
  </property-group>
</property-groups>