Skip to main content

​
Why YAML?

YAML was chosen because it balances human readability with structural expressiveness. Unlike JSON, YAML supports comments, anchors, and multi-line strings, all of which are valuable when managing complex configuration files that multiple team members need to maintain. Unlike XML, YAML is concise enough that a complete sheet configuration remains scannable in a single screen. Think of YAML configuration in Powersheet like a blueprint: the domain model defines what types of rooms exist and how they connect, while the sheet configuration defines how each room looks and what furniture it contains.

​
The Two Configuration Layers

Powersheet relies on two distinct YAML files that serve complementary roles: diagram Domain model (domainModelTypes, relationships) — Defines the semantic layer: entity types — for example, UserNeed, SystemRequirement, and DesignRequirement in an RTM model — their properties, and how they relate to each other. Managed through Administration > Nextedy POWERSHEET > Domain Models. One domain model can be shared across many sheet configurations. Sheet configuration (columns, views, styles, sources) — Defines the presentation layer: which columns appear, how they are styled, what data sources to query, and what views are available. Stored as a YAML file associated with a specific powersheet document via the nextedySheetConfig custom field.

​
How Configuration Files Are Discovered

When a user opens a powersheet document, the system loads configuration through a two-step lookup:
  1. The document’s nextedySheetConfig custom field identifies which sheet configuration file to load
  2. The sheet configuration’s sources[].model property identifies which domain model to load
Configuration files can reside in two locations: global (available to all projects) or project-specific (scoped to a single project). Global configuration file identifiers start with / and display a (Global) suffix in the picker. Project-specific configurations use the filename directly without a path prefix.
Because the domain model and sheet configuration are separate files, you can reuse the same domain model across different sheet configurations. For example, one RTM model can power both a requirements traceability sheet and a risk analysis sheet — each with different columns and views.

​
Key YAML Patterns

​
Columns Use Dot-Notation Binding Paths

Column keys in the sheet configuration use dot-separated paths that trace the expansion path through entity relationships: 
columns:
  title:
    title: Title
    width: 200
  systemRequirements.systemRequirement.title:
    title: System Req Title
    width: 180
The binding path systemRequirements.systemRequirement.title means: follow the systemRequirements expansion, select the systemRequirement entity, and display its title property.

​
Styles and Anchors Reduce Repetition

YAML anchors (&) and aliases (*) allow you to define a style once and reuse it across multiple columns: 
styles:
  readOnlyStyle:
    backgroundColor: 'grey100'

columns:
  outlineNumber:
    title: "#"
    width: 80
    header:
      style: darkgrey
Powersheet provides predefined header styles such as red, blue, green, purple, and their variants (darkred, lightblue, etc.) that map to the built-in design token palette. The columnGroups section visually groups related columns under a shared header with optional collapse behavior: 
columnGroups:
  epic:
    groupName: Epics
    groupStyle: darkgreen
    headerStyle: green
    collapseTo: title

​
Configuration Scopes

Powersheet supports multiple configuration scopes. The configuration editor exposes three scope levels: instance (per-document override), template (template-level defaults), and default (global baseline). This layered approach means teams can share a base configuration while allowing individual documents to override specific settings.
Although some internal field names reference JSON for historical reasons, all user-facing configuration files use YAML syntax. The configuration editor supports both formats and can convert between them, with YAML as the preferred language.
KB ArticlesSource Code
  • prod-powersheet-src/com.nextedy.powersheet.client/src/modules/Powersheet/Powersheet.tsx
  • prod-powersheet-src/com.nextedy.powersheet/src/com/nextedy/powersheet/PowersheetDocumentConfigurationService.java
  • prod-powersheet-src/com.nextedy.powersheet/src/com/nextedy/powersheet/enumProvider/SheetConfigEnumProvider.java
  • QueryExecutorTest.java
  • MetadataTest.java