YAML Primer for Powersheet - Nextedy Documentation

What Is YAML?

YAML (YAML Ain’t Markup Language) is a human-readable data serialization format. Unlike JSON, which uses braces and brackets, or XML, which uses angle-bracket tags, YAML relies on indentation and simple punctuation to express structure. This makes it especially well suited for configuration files that engineers need to read, review, and modify by hand. Think of YAML like a well-organized outline. Each level of indentation represents a deeper level of nesting, just as sub-bullets sit beneath their parent bullet in a document outline. The result is configuration that reads almost like natural language.

YAML was chosen because it supports comments, multi-line strings, and anchors — features that are essential when managing complex sheet configurations shared across teams. A complete Powersheet sheet configuration typically fits on a single screen, which would not be practical in XML.

Core YAML Concepts

Key-Value Pairs

The most basic YAML structure is a key-value pair, separated by a colon and a space:

name: RTM Configuration
version: 2
enabled: true

The colon-space separator is mandatory. Omitting the space after the colon is the single most common YAML syntax error. In Powersheet configuration, keys like name, label, and width all follow this pattern.

Nesting with Indentation

YAML uses consistent indentation (spaces, never tabs) to express hierarchy. Each nested level adds the same number of spaces — typically two:

column:
  key: systemRequirement.title
  label: System Requirement
  width: 250

Here, key, label, and width are properties of column. This hierarchical nesting maps directly to how Powersheet organizes column definitions within a sheet configuration.

YAML does not allow tab characters for indentation. Always configure your editor to insert spaces. Mixed tabs and spaces produce parsing errors that can be difficult to diagnose because they are invisible in most editors.

Lists (Sequences)

Lists use a dash followed by a space at the same indentation level:

sources:
  - type: UserNeed
    model: rtm-model
  - type: SystemRequirement
    model: rtm-model

Each - introduces a new list item. In Powersheet, lists appear throughout configuration — the sources array defines which entity types a sheet queries, the columns array defines which columns appear, and the views array defines named column presets.

Strings and Quoting

Most strings in YAML do not need quotes:

label: Risk Control Status

However, you must quote strings that contain special characters or could be misinterpreted:

# These need quotes
description: "Status: active"
pattern: "true"
query: "type:systemRequirement AND status:approved"

The general rule: if your value contains a colon followed by a space, or if it looks like a boolean (true, false, yes, no) or a number but you intend it as text, wrap it in quotes. Powersheet Lucene query strings almost always need quoting because they contain colons and special operators.

Comments

Comments start with # and continue to the end of the line:

# Domain model for automotive safety RTM
domainModelTypes:
  - name: UserNeed          # Maps to Polarion 'userNeed' type
    polarionType: userNeed

Comments are invaluable in Powersheet configurations for documenting why a particular column is configured a certain way, or noting which Polarion work item type an entity maps to. Unlike JSON, which forbids comments entirely, YAML makes it easy to keep configuration self-documenting.

YAML Structures in Powersheet

Powersheet uses two primary YAML files. Understanding how standard YAML structures map to these files builds a mental model for reading and writing any configuration.

Maps of Maps (Nested Objects)

Domain model entity types use deeply nested maps to describe properties and their metadata:

domainModelTypes:
  - name: SystemRequirement
    polarionType: systemRequirement
    properties:
      - property: title
        type: string
      - property: severity
        type: enum

Each entity type is a map within a list. Each entity type contains a properties key whose value is itself a list of maps. This pattern — lists of maps containing lists of maps — is the most common structure in Powersheet YAML.

Dot-Separated Binding Paths

Powersheet uses a convention that extends standard YAML: binding paths expressed as dot-separated strings within the key field of column definitions:

columns:
  - key: systemRequirement.title
    label: Requirement Title
  - key: systemRequirement.designRequirements.designRequirement.status
    label: Design Status

These paths are not YAML syntax — they are Powersheet-specific conventions interpreted at runtime. The dots denote traversal through entity relationships defined in the domain model. Understanding that these are plain YAML strings (not nested YAML keys) avoids confusion when reading complex column configurations. For a deeper explanation of how binding paths relate to the domain model, see Navigation Properties and Data Model vs Sheet Configuration.

Multi-Line Strings

YAML supports multi-line strings using the pipe (|) or folded (>) syntax:

description: |
  This sheet configuration displays
  the full requirements traceability
  matrix for automotive safety projects.

The pipe preserves line breaks exactly as written. The folded style (>) joins lines with spaces, creating flowing paragraphs. In Powersheet, multi-line strings are most commonly used in description fields and in Lucene query strings that span multiple lines.

Common Pitfalls

Understanding these common mistakes saves significant debugging time when working with Powersheet YAML files.

Pitfall	Symptom	Fix
Tab characters in indentation	Parser error, configuration fails to load	Configure editor to use spaces only
Missing space after colon	Key-value pair treated as single string	Always use `key: value` with a space
Inconsistent indentation depth	Child properties attach to wrong parent	Use exactly 2 spaces per nesting level
Unquoted special characters	Colons, brackets, or booleans misinterpreted	Quote strings containing `:`, `{`, `[`, `true`, `false`
Trailing whitespace	Invisible characters cause diff noise	Enable “trim trailing whitespace” in editor

Before uploading a modified configuration to Polarion, validate the YAML syntax using an online YAML validator or your editor’s built-in linting. A single indentation error can prevent the entire sheet from loading, and Powersheet’s error messages may point to a downstream effect rather than the root cause.

YAML Anchors and Aliases

YAML provides a reuse mechanism through anchors (&) and aliases (*). An anchor marks a block of YAML for reuse, and an alias references it elsewhere:

# Define a reusable column style
_styles:
  highlight: &highlight-style
    backgroundColor: "#fff3e0"
    fontWeight: bold

columns:
  - key: hazard.severity
    label: Severity
    style: *highlight-style
  - key: hazard.probability
    label: Probability
    style: *highlight-style

This avoids duplicating the same style definition across multiple columns. When the style needs to change, you update it in one place. The leading underscore on _styles is a convention indicating the key exists only for anchor definitions and is not processed directly by Powersheet.

The extent of anchor and alias support may vary depending on the YAML parser version used by your Polarion installation. Test anchor-based configurations in a non-production project first.

Data Types in YAML

YAML automatically infers data types, which can occasionally produce surprises:

# Interpreted as boolean (not string)
enabled: true

# Interpreted as integer (not string)
width: 200

# Interpreted as float (not string)
ratio: 1.5

# Interpreted as string
label: System Requirement

# Careful: interpreted as boolean!
value: yes       # becomes true
value: "yes"     # stays as the string "yes"

In Powersheet configurations, the most frequent data-type issue involves boolean-like strings. If a column label, enum option, or description contains words like yes, no, true, false, on, or off, always wrap them in quotes to prevent YAML from converting them to booleans.

How YAML Maps to Powersheet Concepts

The following table connects YAML structures to the Powersheet concepts they represent:

YAML Structure	Powersheet Concept	Example Key
Top-level list of maps	Entity type definitions	`domainModelTypes`
Nested list of maps	Relationships between entities	`relationships`
List of maps with `key` field	Column definitions	`columns`
Map with named entries	Style definitions	`styles`
List of strings	View column visibility	`views[].columns`
Dot-separated string value	Binding path across entity relationships	`columns[].key`

For the complete structure of each YAML file, see the Sheet Configuration Reference and Data Model Reference.

Editor Setup Recommendations

Choosing the right editor configuration prevents the majority of YAML errors:

Indentation: Set tab width to 2 spaces and enable “insert spaces” mode
Syntax highlighting: Use a YAML-aware editor or install a YAML plugin for syntax coloring and bracket matching
Linting: Enable a YAML linter that flags tab characters, inconsistent indentation, and duplicate keys
Schema validation: Some editors support JSON Schema for YAML, which can validate Powersheet-specific keys and structures as you type

When learning Powersheet YAML, keep a working configuration file open alongside the one you are editing. Comparing structure side by side is the fastest way to spot indentation or nesting errors. The Example Models Reference provides several complete, validated configurations.

Next Steps

With a solid understanding of YAML fundamentals, you are ready to explore how Powersheet applies these concepts in practice:

YAML Configuration System explains how the two configuration files interact at runtime
Data Model vs Sheet Configuration clarifies the boundary between what the domain model defines and what the sheet configuration controls
Entity Types and Relationships shows how domainModelTypes and relationships work together
Sheet Configuration Guides provide step-by-step instructions for building and modifying configurations

​What Is YAML?

​Core YAML Concepts

​Key-Value Pairs

​Nesting with Indentation

​Lists (Sequences)

​Strings and Quoting

​Comments

​YAML Structures in Powersheet

​Maps of Maps (Nested Objects)

​Dot-Separated Binding Paths

​Multi-Line Strings

​Common Pitfalls

​YAML Anchors and Aliases

​Data Types in YAML

​How YAML Maps to Powersheet Concepts

​Editor Setup Recommendations

​Next Steps

What Is YAML?

Core YAML Concepts

Key-Value Pairs

Nesting with Indentation

Lists (Sequences)

Strings and Quoting

Comments

YAML Structures in Powersheet

Maps of Maps (Nested Objects)

Dot-Separated Binding Paths

Multi-Line Strings

Common Pitfalls

YAML Anchors and Aliases

Data Types in YAML

How YAML Maps to Powersheet Concepts

Editor Setup Recommendations

Next Steps