> ## 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 Configuration System > Nextedy POWERSHEET uses a declarative YAML-based configuration system that separates *what you want to see* from *how the system retrieves it*. 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}

; }; 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](/powersheet/guides/sheet-configuration/index). For a primer on YAML syntax itself, see [YAML Primer for Powersheet](/powersheet/concepts/yaml-primer). ## 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. diagram 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: ```yaml theme={null} # 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: ```yaml theme={null} 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: ```yaml theme={null} 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: ```yaml theme={null} 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](/powersheet/concepts/views-as-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): ```yaml theme={null} 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: ```yaml theme={null} 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](/powersheet/concepts/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: 1. **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). 2. **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. 3. **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. 4. **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. 5. **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. diagram ## 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](/powersheet/concepts/model-driven-design) and [Entity Types and Relationships](/powersheet/concepts/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](/powersheet/concepts/core-components)** — explains the runtime subsystems that consume the configuration * **[Data Model vs Sheet Configuration](/powersheet/concepts/data-model-vs-sheet-config)** — dives deeper into the separation of concerns between the two file types * **[Navigation Properties](/powersheet/concepts/navigation-properties)** — details how dot-notation binding paths traverse relationships * **[Hierarchy and Traceability](/powersheet/concepts/hierarchy-and-traceability)** — shows how expansion paths in sources build multi-level views * **[Global vs Project-Specific Configuration](/powersheet/concepts/global-vs-project-specific)** — covers storage scopes and sharing strategies * **[Dynamic Value Expressions](/powersheet/concepts/dynamic-expressions)** — explains how `$context` expressions in sources are resolved at runtime For hands-on guidance, the [Data Model Guides](/powersheet/guides/data-model/index) and [Sheet Configuration Guides](/powersheet/guides/sheet-configuration/index) walk through practical setup scenarios step by step.