> ## Documentation Index > Fetch the complete documentation index at: https://learn.nextedy.com/llms.txt > Use this file to discover all available pages before exploring further. # YAML Primer for Powersheet > Nextedy POWERSHEET configuration is built entirely on YAML files. export const LastReviewed = ({date}) => { if (!date) return null; const formatted = new Date(`${date}T00:00:00Z`).toLocaleDateString("en-US", { year: "numeric", month: "long", day: "numeric", timeZone: "UTC" }); return

Last reviewed on {formatted}

; }; ## 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: ```yaml theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} label: Risk Control Status ``` However, you must quote strings that contain special characters or could be misinterpreted: ```yaml theme={null} # 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: ```yaml theme={null} # Data 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. diagram ### Maps of Maps (Nested Objects) Data model entity types use deeply nested maps to describe properties and their metadata: ```yaml theme={null} 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: ```yaml theme={null} 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 data 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 data model, see [Navigation Properties](/powersheet/concepts/navigation-properties) and [Data Model vs Sheet Configuration](/powersheet/concepts/data-model-vs-sheet-config). ### Multi-Line Strings YAML supports multi-line strings using the pipe (`|`) or folded (`>`) syntax: ```yaml theme={null} 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: ```yaml theme={null} # 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: ```yaml theme={null} # 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](/powersheet/reference/sheet-config/index) and [Data Model Reference](/powersheet/reference/data-model/index). ## 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](/powersheet/reference/example-models/index) 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](/powersheet/concepts/yaml-configuration) explains how the two configuration files interact at runtime * [Data Model vs Sheet Configuration](/powersheet/concepts/data-model-vs-sheet-config) clarifies the boundary between what the data model defines and what the sheet configuration controls * [Entity Types and Relationships](/powersheet/concepts/entity-types-and-relationships) shows how `domainModelTypes` and `relationships` work together * [Sheet Configuration Guides](/powersheet/guides/sheet-configuration/index) provide step-by-step instructions for building and modifying configurations