Configuration Validation Rules - Nextedy Documentation

Validation behavior may vary between Risksheet versions. The rules documented here are derived from available source code analysis. Test your configuration in a development environment before deploying to production.

Validation Process Overview

When Risksheet loads a sheet configuration, it performs validation and default application in the following order:

Configuration Syntax Validation

Rule	Behavior on Violation
Valid configuration syntax required	Grid fails to load entirely. No partial loading.
UTF-8 encoding required	Non-UTF-8 characters may cause parse failures.
Conform to the configuration format	Structural errors (such as trailing commas in the underlying file or unsupported comment markers) cause the parser to reject the configuration.

Use the built-in configuration editor (v25.5.0+), which supports YAML editing with syntax highlighting and error detection. A single syntax error prevents the entire grid from loading.

Top-Level Property Validation

The following are the real top-level sections recognized by Risksheet. Any other top-level keys are ignored.

Property	Type	Required	Default if Missing	Validation Rule
`global`	object	No	`{}`	Must be an object. Sub-properties validated individually.
`columns`	array	No	`[]`	Must be an array. Each element validated individually.
`dataTypes`	object	No	`{}`	Must be an object. Each entry validated for required `type` property.
`levels`	array	No	`[]`	Must be an array. Each element validated individually.
`formulas`	object	No	`{}`	Must be an object. Values must be valid JavaScript function strings.
`styles`	object	No	`{}`	Must be an object. Style values must be wrapped in `{}` braces.
`cellDecorators`	object	No	`{}`	Must be an object. Values must be valid JavaScript function strings.
`headers`	object	No	`{}`	Must be an object. Sub-properties validated individually.
`reviews`	object	No	`{}`	Must be an object.
`sortBy`	array	No	`[]`	Must be an array of column ID strings.
`views`	array	No	`[]`	Optional. Must be an array of saved view definitions.
`queryFactories`	object	No	`{}`	Optional. Named Lucene query factory functions for itemLink autocomplete filtering.

Risksheet does not define rating scales or enumerations in the sheet configuration. They are defined as Polarion enumerations (Administration > Enumerations) and referenced from columns via type: rating:<enumId>, type: enum:<enumId>, or type: multiEnum:<enumId>. The server loads enum values automatically from Polarion.

Column Validation Rules

Each element in the columns array is validated against the following rules.

Required Column Properties

Property	Behavior if Missing
`bindings` or `id`	At least one must be present. If only `id` is provided, it is used as the binding. If neither is present, the column may fail to render.

Column Default Application

Property	Default Value	Condition
`id`	Auto-generated from `header` or `bindings`	Applied when `id` is not explicitly set
`type`	Auto-detected from Polarion field type via `bindings`	Applied when `type` is not explicitly set. Falls back to `string` if detection fails.
`level`	`1`	Applied to risk item columns. Not set for task columns.
`canCreate`	`true`	Applied to `itemLink` and `multiItemLink` columns only
`filterable`	`true`	Applied to all columns
`readOnly`	`false`	Base default. May be overridden by automatic rules (see below).

Text wrapping and multi-line rendering are controlled through CSS classes defined in the styles section and applied via cellCss or cellDecorators — not via column-level properties.

Automatic Read-Only Enforcement

The readOnly property is automatically set to true regardless of the configured value in these scenarios:

Condition	Reason
`formula` property is set	Formula columns compute values; user edits would conflict
`serverRender` property is set	Server-rendered columns are populated by Velocity templates
Column is a reference column	Reference columns display linked item data, not editable fields
`bindings` is a system field: `id`, `status`, `type`, `project`, `outlineNumber`	System fields are always read-only in Risksheet
`bindings` is: `author`, `resolution`, `created`, `updated`	These Polarion fields cannot be modified through the grid
User lacks field-level modification permission	Polarion permissions override configuration

If a column appears read-only unexpectedly, check whether any of the automatic enforcement rules apply. The formula, serverRender, and system field rules take precedence over explicit readOnly: false settings.

Column Type Validation

When type is explicitly provided, it must be one of the recognized types:

Type Identifier	Category	Notes
`text` / `string`	Text	Default fallback for unrecognized types
`int`	Numeric	Integer values
`float`	Numeric	Floating-point values
`rating`	Numeric	Treated as integer internally
`currency`	Numeric	Uses BigDecimal precision
`boolean`	Boolean	Boolean values
`date`	Temporal	Date only (`yyyy-MM-dd`)
`datetime`	Temporal	Date and time
`time`	Temporal	Time only
`duration`	Temporal	Stored as string
`enum:<enumId>`	Enumeration	Colon-separated syntax. References a Polarion enumeration.
`multiEnum:<enumId>`	Enumeration	Colon-separated syntax. Multiple selection.
`rating:<enumId>`	Enumeration	Colon-separated syntax. References a Polarion rating enumeration.
`itemLink`	Link	Single linked item.
`multiItemLink`	Link	Multiple linked items.
`taskLink`	Link	Downstream task link.

Column types use a colon-separated syntax where the prefix before the first colon determines the base type and the remainder carries configuration parameters. For example, multiEnum:severity,priority has base type multiEnum with parameters severity,priority.

Unrecognized type identifiers default to string / text behavior.

Column Type with ServerRender

When serverRender is set on a column:

Automatic Adjustment	Value
`type`	Set to `text`
`readOnly`	Set to `true`

DataTypes Validation Rules

Risk DataType

Property	Default	Validation Rule
`type`	None (required)	Must be specified. Error `No type attribute is defined for dataType` if missing. Value is evaluated through expression evaluator for dynamic resolution.
`role`	None	Link role string. Evaluated through expression evaluator.
`removeStrategy`	`delete`	Must be a recognized strategy identifier (`delete`, `rejected`, `recycle_bin`, `hide`).
`rejectedAction`	`reject`	Must match a valid workflow action ID on the work item type.
`rejectedStatus`	`rejected`	Must match a valid workflow status ID.
`rejectedResolution`	`invalid`	Must match a valid resolution option ID.
`showInMenu`	`true`	Boolean. Controls toolbar menu visibility.
`document`	None	Optional. Restricts scope to items within a specific LiveDoc.
`createInDocument`	None	Optional. Uses `folder/documentId` path format. Specifies where new items are created.

Task DataType

Property	Default	Validation Rule
`type`	None (required for task creation)	Work item type for mitigation/task items. Since v25.3.1, comma-separated values allow multiple types. Evaluated through expression evaluator.
`role`	None	Link role for task relationships. Evaluated through expression evaluator.
`name`	None	Optional. Display name in toolbar/menus (e.g., “Task”, “Safety Requirement”).
`zoomColumn`	None	Optional. Column ID for zoom navigation after task creation.
`document`	None	Optional. Restricts task scope to a specific LiveDoc (e.g., `Risks/FHA-SYS-001`).
`project`	None	Optional. Single project ID for task items.
`projects`	None	Optional (v23.7.0+). Array of project IDs for multi-project task scopes.
`query`	None	Optional. Lucene query for additional task filtering.
`createInCurrentDocument`	`false`	Boolean. When true, new tasks are created in the current document.
`createInDocument`	None	Optional (v24.8.1+). Target document path for new task creation.
`canCreate`	`true`	Boolean. When false, users cannot create new task items (only link to existing).
`linkToRisksheet`	`false`	Boolean. When true, the task RC ID column becomes a clickable link to the downstream risksheet document.

The type and role properties in dataTypes support dynamic resolution through the expression evaluator. This means values can reference Polarion project properties using patterns like $config.getRisksheetProjectProperties().getProperties().getProperty('propertyName'). Validation of these expressions occurs at runtime.

Levels Validation Rules

Each element in the levels array MUST provide three properties:

Property	Required	Default	Validation Rule
`name`	Yes	None	String. Display name shown in the navigation/zoom menu (e.g., `Item`, `Failure mode`).
`controlColumn`	Yes	None	String. Column ID used as the grouping key for cell merging. Must reference a valid column `id` or binding.
`zoomColumn`	Yes	None	String. Column ID used as the target for zoom/drill-down navigation.
`showInMenu`	No	`true`	Boolean. Controls level visibility in the navigation menu.

Levels do not create new work item types. They define a visual hierarchy: when consecutive rows share the same value in a controlColumn, the cells in columns assigned to that level merge vertically. Columns reference a level through their level property (1-indexed: level: 1 maps to levels[0]).

Headers Validation Rules

Property	Default	Validation Rule
`headers.columnHeader.height`	`32`	Number (pixels). Must be a positive integer.
`headers.columnGroupHeader.height`	`32`	Number (pixels). Must be a positive integer.
`headers.rowHeader.renderer`	None	String. Must reference a named function in `cellDecorators`.

Global Settings Validation

Property	Default	Validation Rule
`global.culture`	`en`	String. Must be a valid culture/locale code (e.g., `en`, `de`, `fr`, `ja`). See Culture and Localization Codes.
`global.help`	`https://go.nextedy.com/risksheet-support-portal`	String. Must be a valid URL.

Reviews Validation

Property	Default	Validation Rule
`reviews.reviewManager`	`CommentBased`	String. Must be a recognized review manager type (`CommentBased`, `ApprovalBased`, `WorkItemBased`).

The ApprovalBased review manager creates approval-tagged comments but does NOT trigger Polarion’s formal approval state transitions (draft, reviewed, approved). It is a comment-tagging workflow, not a full Polarion approval integration.

Cross-Property Validation

Some validation rules involve interactions between multiple properties:

Interaction	Rule
`columns[].formula` + `columns[].readOnly`	If `formula` is set, `readOnly` is forced to `true` regardless of explicit setting
`columns[].serverRender` + `columns[].type` + `columns[].readOnly`	If `serverRender` is set, `type` is forced to `text` and `readOnly` is forced to `true`
`dataTypes` + `levels`	Task columns (bound to `task.*` fields) should not have a `level` property
`columns[].type` (colon syntax) + Polarion enumerations	Enum and rating column types must reference enumerations defined in Polarion Administration. Missing enumerations cause empty selection lists.
`views[].columnIds` + `columns[].id`	View column references must match configured column IDs. The special token `@all` includes all columns; a `-columnId` prefix excludes a specific column.
`cellDecorators` keys + `columns[].id`	Cell decorator function names referenced via `cellRenderer` must exist in the `cellDecorators` section
`headers.rowHeader.renderer` + `cellDecorators`	Row header renderer must reference a function defined in `cellDecorators`
`queryFactories` keys + `typeProperties.queryFactory`	Column queryFactory references must match a function name defined in the `queryFactories` section

Complete Validation Example

global:
  culture: en

columns:
  - id: severity
    bindings: severity
    header: Severity (S)
    type: rating:severityRating
    level: 1
    filterable: true
    readOnly: false
  - id: rpn
    bindings: rpn
    header: RPN
    formula: commonRpn
    level: 1

dataTypes:
  risk:
    type: failureMode
    role: relates_to
    removeStrategy: delete
    rejectedAction: reject
    rejectedStatus: rejected
    rejectedResolution: invalid
  task:
    type: mitigationTask
    role: mitigates
    name: Mitigation
    zoomColumn: taskTitle
    showInMenu: true

levels:
  - name: Item
    controlColumn: item
    zoomColumn: item
  - name: Failure mode
    controlColumn: failureMode
    zoomColumn: failureMode

formulas:
  commonRpn: "function(info){ var value = info.item['occ']*info.item['det']*info.item['sev']; return value?value:null;}"

In this example:

The rpn column has formula set, so readOnly is automatically forced to true.
The severity column has type: rating:severityRating, which references a Polarion rating enumeration named severityRating.
Both dataTypes entries have type specified, satisfying the required field rule.
Each levels entry provides the required name, controlColumn, and zoomColumn properties.

​Validation Process Overview

​Configuration Syntax Validation

​Top-Level Property Validation

​Column Validation Rules

​Required Column Properties

​Column Default Application

​Automatic Read-Only Enforcement

​Column Type Validation

​Column Type with ServerRender

​DataTypes Validation Rules

​Risk DataType

​Task DataType

​Levels Validation Rules

​Headers Validation Rules

​Global Settings Validation

​Reviews Validation

​Cross-Property Validation

​Complete Validation Example

​See Also

Validation Process Overview

Configuration Syntax Validation

Top-Level Property Validation

Column Validation Rules

Required Column Properties

Column Default Application

Automatic Read-Only Enforcement

Column Type Validation

Column Type with ServerRender

DataTypes Validation Rules

Risk DataType

Task DataType

Levels Validation Rules

Headers Validation Rules

Global Settings Validation

Reviews Validation

Cross-Property Validation

Complete Validation Example

See Also