YAML Configuration System - Nextedy Documentation

This page explains the architecture of the configuration system, how its layers interact, and why the design works the way it does. For practical setup instructions, see the Sheet Configuration Guides. For a primer on YAML syntax itself, see YAML Primer for Powersheet.

Two Configuration Files, Two Responsibilities

Every Powersheet deployment relies on two distinct YAML files that serve complementary purposes:

File	Responsibility	Analogy
Data model	Defines what exists — entity types, their properties, and how they relate to each other	A database schema
Sheet configuration	Defines what to show — which columns to display, how to format them, and where to get the data	A report template

This separation is intentional. A single data model can power many different sheet configurations, each offering a different perspective on the same underlying data. Think of it like a relational database: you define the schema once, then write as many queries and views as you need.

The data model defines the vocabulary; the sheet configuration uses that vocabulary to compose a specific view.

Anatomy of a Sheet Configuration

A sheet configuration file is organized into several top-level sections, each controlling a distinct aspect of the rendered sheet:

# Top-level sections of a sheet configuration
columnGroups:    # Visual grouping of related columns
sortBy:          # Default sort order
columns:         # Column definitions with binding paths
views:           # Named visibility presets
formatters:      # Conditional styling rules
styles:          # Reusable CSS class definitions
sources:         # Data retrieval and expansion paths

Columns: The Core Building Block

The columns section is where most configuration effort goes. Each entry maps a binding path — a dot-separated property reference from the data model — to display settings:

columns:
  title:
    title: "Title"
    width: 300
    hasFocus: true

  systemRequirements.systemRequirement.title:
    title: "System Requirement"
    width: 250
    columnGroup: sysReq
    multiItem: true
    display: title

The first column (title) references a simple property on the root entity. The second column (systemRequirements.systemRequirement.title) follows a navigation path through a relationship defined in the data model: from the root entity, through the systemRequirements relationship, to the systemRequirement entity type, and finally to its title property.

Every column key in the sheet configuration must correspond to a valid path through the data model. If a binding path references an entity type or relationship that does not exist in the data model, the column will fail to render. The data model acts as the contract that the sheet configuration relies on.

Column Groups: Visual Organization

Column groups cluster related columns under a shared header with consistent styling. They are purely visual — they do not affect data retrieval:

columnGroups:
  sysReq:
    groupName: "System Requirements"
    groupStyle: blue
    headerStyle: blue
    collapseTo: systemRequirements.systemRequirement.title

The collapseTo property specifies which column remains visible when the group is collapsed, giving users a compact summary view.

Views: Named Perspectives

Views let administrators define named column visibility presets. A single sheet configuration can offer multiple analysis perspectives — for example, a “Risk Focus” view that hides requirement columns and emphasizes risk-related fields, or a “Full Traceability” view that shows everything:

views:
  riskFocus:
    columns:
      hazards.hazard.severity:
        visible: true
      systemRequirements.systemRequirement.title:
        visible: false
  fullTraceability:
    columns:
      hazards.hazard.severity:
        visible: true
      systemRequirements.systemRequirement.title:
        visible: true

Views override the default visible property of columns. Users switch between views at runtime without modifying the underlying configuration. For more on how views shape analysis workflows, see Views as Analysis Perspectives.

Formatters and Styles: Conditional Presentation

Formatters apply conditional styling rules to cells based on their values. A formatter definition pairs an expression (the condition) with a style (the visual effect):

formatters:
  severityHighlight:
    expression: "value === 'Critical'"
    style: criticalStyle

styles:
  criticalStyle:
    backgroundColor: "#ffebee"
    color: "#c62828"

Setting a column’s isReadOnly property to true or applying a read-only formatter prevents user editing regardless of permissions. This is useful for computed or derived columns that should only be viewed, not modified.

Sources: Where Data Comes From

The sources section defines which entity types to load as root items, what query filters to apply, and how to expand related entities. Sources connect the sheet configuration to live Polarion data through the data model:

sources:
  - type: UserNeed
    query: "type:userneed AND NOT HAS_VALUE:resolution"
    expand:
      - systemRequirements.systemRequirement
      - systemRequirements.systemRequirement.designRequirements.designRequirement

Each expansion path follows relationships defined in the data model, loading related entities at successive levels of the hierarchy. For a deeper understanding of how sources drive data loading, see Source Configuration.

Configuration Storage and Discovery

Powersheet configurations are stored in the Polarion repository (SVN) and can exist at two scopes:

Global configurations are stored in a shared repository location, available to all projects. Their identifiers start with / and display with a “(Global)” suffix in the selection UI.
Project-specific configurations are stored within a project’s repository space. Their identifiers use the filename without a path prefix.

When an administrator assigns a sheet configuration to a Polarion document, a custom field (nextedySheetConfig) stores the configuration file reference. Powersheet dynamically discovers all available configuration files at both scopes and presents them as selectable options through the Administration > Nextedy Powersheet interface.

Users must explicitly select a configuration for each Powersheet document. There is no automatic default assignment — this is deliberate, because every document’s data model and column needs differ. The system does include a bundled powersheet.yaml as a starter template, accessible through the built-in configuration editor.

Configuration Scoping: Instance, Template, Default

The configuration editor supports three levels of scope that allow fine-grained override control:

Scope	Purpose	Precedence
Instance	Per-document overrides for a specific Powersheet	Highest
Template	Shared configuration template used across multiple documents	Middle
Default	Global fallback defaults	Lowest

This layered approach means you can define a standard configuration template that multiple documents share, while still allowing individual documents to override specific settings. The scope control can be enabled, disabled, or disallowed at the administrator level, preventing end users from making scope changes when organizational consistency is required.

How Configuration Becomes a Sheet

Understanding the runtime flow helps clarify why the configuration is structured the way it is:

Load — Powersheet reads the YAML configuration from the repository location stored in the document’s custom field. If the file cannot be read or parsed, an error is surfaced (YAML parse errors are logged but do not crash the application).
Validate against data model — Column binding paths are resolved against the data model. Each dot-separated segment must match a known property or navigation path. Unresolvable paths produce rendering failures for those specific columns.
Fetch metadata — The metadata system translates entity types and relationships from the data model into a queryable schema that the client uses for data retrieval.
Execute sources — Source definitions trigger queries against Polarion, filtered by the specified query expressions. Expansion paths are followed to load related entities at each hierarchy level.
Render — Columns are laid out according to their defined widths, groups, and visibility settings. Formatters evaluate their expressions against cell values and apply styles. Views determine which columns are visible in the current perspective.

The Data Model as Contract

The data model is not just a separate file — it is the contract that all sheet configurations must honor. It defines:

Entity types via domainModelTypes — each mapping a logical name (like UserNeed or SystemRequirement) to a Polarion work item type through the polarionType property
Properties — the fields available on each entity type, which become valid column binding targets
Relationships — the navigation paths between entity types, including cardinality (one-to-one vs. one-to-many) and direction (direct vs. back)

When a sheet configuration references systemRequirements.systemRequirement.title, the data model must define: (1) a relationship called systemRequirements on the root entity, (2) that relationship’s target entity type SystemRequirement, and (3) a title property on that entity type. For deeper coverage of data model concepts, see Model-Driven Design and Entity Types and Relationships.

Common Misconceptions

A frequent source of support issues is attempting to build a complex multi-entity configuration from scratch. The recommended approach is to start with a minimal single-entity setup — one source, a few columns — verify it renders correctly, and then add complexity incrementally. Each addition (a new relationship path, a column group, a formatter) can be validated independently before moving on.

“Changing the data model automatically updates sheet configurations.” It does not. The data model defines what is possible; sheet configurations define what is shown. If you add a new entity type to the data model, no existing sheet configuration will display it until you explicitly add columns and sources that reference it. “Column keys are display labels.” Column keys are binding paths — they follow the data model’s property and relationship structure. The title property within each column definition controls the display label. Two columns can have the same display title but different binding paths. “Global configurations override project configurations.” They coexist as separate options in the selection list. A global configuration is simply one that is available to all projects. There is no inheritance or override relationship between global and project-specific configurations — a document uses exactly one configuration file.

Configuration Editor

Powersheet includes a built-in YAML editor accessible through the Polarion interface. The editor provides:

Syntax-aware editing with support for both YAML and JSON content languages
JSON Schema validation that checks your configuration against the expected structure
Language conversion — content can be switched between JSON and YAML representations
Scope awareness — the editor shows which scope level (instance, template, or default) you are editing
History — links to revision history for tracking configuration changes over time

The editor supports optional Vim keybinding mode and line wrapping toggles, with preferences persisted in the browser. Theme styling adapts to match the Powersheet product branding.

Relationship to Other Concepts

The YAML configuration system is the foundation that connects most other Powersheet concepts:

Core Components — explains the runtime subsystems that consume the configuration
Data Model vs Sheet Configuration — dives deeper into the separation of concerns between the two file types
Navigation Properties — details how dot-notation binding paths traverse relationships
Hierarchy and Traceability — shows how expansion paths in sources build multi-level views
Global vs Project-Specific Configuration — covers storage scopes and sharing strategies
Dynamic Value Expressions — explains how $context expressions in sources are resolved at runtime

For hands-on guidance, the Data Model Guides and Sheet Configuration Guides walk through practical setup scenarios step by step.

​Two Configuration Files, Two Responsibilities

​Anatomy of a Sheet Configuration

​Columns: The Core Building Block

​Column Groups: Visual Organization

​Views: Named Perspectives

​Formatters and Styles: Conditional Presentation

​Sources: Where Data Comes From

​Configuration Storage and Discovery

​Configuration Scoping: Instance, Template, Default

​How Configuration Becomes a Sheet

​The Data Model as Contract

​Common Misconceptions

​Configuration Editor

​Relationship to Other Concepts

Two Configuration Files, Two Responsibilities

Anatomy of a Sheet Configuration

Columns: The Core Building Block

Column Groups: Visual Organization

Views: Named Perspectives

Formatters and Styles: Conditional Presentation

Sources: Where Data Comes From

Configuration Storage and Discovery

Configuration Scoping: Instance, Template, Default

How Configuration Becomes a Sheet

The Data Model as Contract

Common Misconceptions

Configuration Editor

Relationship to Other Concepts