Reference

Windows Runtime

Windows exposes important configuration through system APIs and utilities: display modes, audio endpoints, power settings, devices, and other system state. Pinman organizes this state under the winrt: realm so it can be tracked, captured, compared, and—where a safe write path exists—changed through a Profile.

The winrt: realm covers this whole Windows settings model. Pinman uses the appropriate Windows or vendor interface for each setting and presents the result through one consistent tree.

The `winrt:` tree#

A Windows Runtime location begins with a functional category:

winrt:/Sound/Master/Volume
winrt:/Display/Monitors/~DEL40A9.1/RefreshRate
winrt:/Power/USB/SelectiveSuspend

The first path level is one of Pinman's Windows categories:

Category	Examples of the state it contains
`About`	Windows and hardware information
`Accessibility`	Accessibility preferences
`Display`	Display configuration and monitors
`Gaming`	Windows gaming settings
`GPU`	Graphics adapters and driver settings
`Input`	Keyboard, mouse, and input preferences
`Monitoring`	Current resource and performance readings
`Network`	Network adapters and connection state
`Personalization`	Desktop and appearance settings
`Power`	Power plans and device power management
`Security`	Windows security settings
`Services`	Windows service configuration and status
`Sound`	Master audio and audio devices
`Startup`	Windows startup configuration

The settings available on a particular machine depend on its version of Windows, installed devices, drivers, and vendor software.

Itemtypes#

The winrt: tree uses five itemtypes:

Itemtype	Represents	May contain
`winrt_root`	The root of the Windows Runtime realm	Sections and tables
`winrt_section`	A named category or group	Sections, tables, and properties
`winrt_table`	A dynamic collection, such as monitors or audio devices	Rows
`winrt_row`	One member of a table	Properties
`winrt_property`	One Windows value	Nothing; it is a leaf Item

This Schema fragment tracks the master volume and the volume of every audio device Pinman discovers:

items:
  - itemtype: winrt_root
    items:
      - selector: Sound
        itemtype: winrt_section
        items:
          - selector: Master
            itemtype: winrt_section
            items:
              - selector: Volume
                itemtype: winrt_property
          - selector: Devices
            itemtype: winrt_table
            items:
              - selector: "{{DeviceId}}"
                itemtype: winrt_row
                items:
                  - selector: Volume
                    itemtype: winrt_property

The exact device IDs are filled in during a scan. Each resulting property has a stable location below winrt:/Sound/Devices/.

See Schema Items for the Item model and the general rules for locations, selectors, and dynamic children.

Reading Windows state#

When you Refresh or create a Capture, Pinman reads Windows through several system interfaces and normalizes the result into the winrt: tree. A single read can include ordinary scalar properties, nested sections, and rows found in dynamic tables.

Scope determines how much of that tree Pinman reads:

Scope	Windows Runtime work
Tracked-only	Reads the categories needed by the Schema, then keeps the tracked paths within them.
Discover untracked	Reads all Windows Runtime categories and makes the broader tree available to explore.

Tracked-only is usually faster. Discovery does more work and may take longer, especially for categories that enumerate devices, services, or vendor data.

Each category carries the time it was read. This lets Pinman report the freshness of one part of the Machine independently from another. Pinman also preserves a read failure from Windows, a driver, or a vendor API as its own result, distinct from an absent Item.

For the relationship between Scope, Capture coverage, and comparison detail, see Captures.

The property catalog#

The extracted Windows data supplies the values. The Windows Runtime property catalog supplies the metadata that gives those values their meaning in Pinman. It describes known properties and dynamic tables, including:

data type, units, label, and description;
read and write behavior;
presentation metadata for controls and values;
the source or write mechanism used by the Windows adapter;
stable row identities and reader-facing labels for tables; and
related software and optional guidance metadata.

When a winrt_property is imported or discovered, catalog metadata supplies each field left open by the Schema. Explicit Schema fields take precedence.

Catalog fields#

These are the principal fields used by a property entry in winrt_catalog.json:

Field	Meaning
`category`	Top-level functional group, such as `Display` or `Power`
`subcategory`	Nested path below the category, when needed
`property`	Property name within that category and subcategory
`data_type`	Type used while extracting the Windows value
`io_mode`	Whether the property is `read-write`, `read-only`, or `ephemeral`
`persistent`	Whether the setting normally survives a restart
`units`	Units such as `%`, `Hz`, `pixels`, or `ms`
`label`, `description`	Reader-facing name and explanation
`display_format`	Presentation rule for the value
`source`	Windows interface used to read the value
`writable_via`	Direct-write mechanism, when one is available
`software_refs`	Software associated with the property
`instructions_template`	Optional source material for an authored guided action
`widget`, `min`, `max`, `step`, `choices`	UI control metadata

The catalog may use extraction-specific data_type values. When Pinman adds the property to the Schema, it maps that type to the Schema's datatype: string, int, float, or bool.

Catalog priority#

Pinman searches for winrt_catalog.json in this order:

the active Project's reference/ directory;
the reference/ directories of adopted Kits, in Project order; and
the Windows platform baseline shipped with Pinman.

The first file found supplies the entire catalog. Project and Kit files are complete alternatives to the platform file, so an override needs to contain every baseline entry it still requires.

Most Kits should declare Windows Runtime Items and their authoring metadata in Schema YAML. Replacing the platform catalog is intended for a complete catalog override.

Property behavior#

Reading, comparing, and writing are separate capabilities. The catalog's io_mode gives each property one of these behaviors:

`io_mode`	Compare in Captures	Change directly	Persists as configuration
`read-write`	Yes	Yes	Yes
`read-only`	Yes	No	Yes
`ephemeral`	No	No	No

A read-write property has a supported write route, such as a Windows system API, audio interface, display interface, or vendor API. Profile Preview and Apply use the same write gates and verification flow as other Pinman realms.

A read-only property records persistent state for tracking and comparison. Pinman leaves changes to that property outside direct Profile Apply.

An ephemeral property is a live reading rather than saved configuration—for example, a current utilization or status value. A Profile Script can inspect it with p.read(); Captures leave it out of persistent comparisons.

Guided changes are authored explicitly in a Profile Script with p.guided(). Catalog fields such as software_refs and instructions_template can supply context for that action. The p.guided() declaration creates the guided workflow.

Dynamic tables#

Windows frequently reports a collection rather than one fixed setting: monitors, audio endpoints, graphics adapters, services, or USB devices. Pinman represents each collection as a winrt_table containing winrt_row Items.

The catalog defines how a table derives its row ID and which property supplies its display label. For example, a monitor may have a location based on its device identity while the UI shows its familiar monitor name.

Stable IDs keep a row's Pinman location consistent when a friendly name changes or two devices share the same label. Schema and Profile declarations should use the location shown by Pinman rather than constructing one from a display label.

Registry-backed Windows settings#

Some Windows settings are ultimately read from or written to the Registry. They still belong under winrt: when Pinman presents them as part of a functional Windows model, such as Display, Input, or Personalization. This keeps the setting's location stable and lets its adapter supply the right type, behavior, and UI metadata.

Use winreg: when the Registry key or value is itself the thing you need to track, particularly for application-specific configuration. See Windows Registry for that realm.

Authoring Windows Runtime Items#

When adding winrt: Items to a Schema:

Start with a winrt_root and the canonical category name.
Follow the extracted tree with winrt_section, winrt_table, and winrt_row Items as needed.
End each tracked value with a winrt_property.
Use the table's stable row binding for dynamic devices or services.
Declare property metadata only when the Schema should override or supplement the platform catalog.

Validate the YAML before importing it:

pinman schema validate schema.yaml

Then import the Schema and scan the affected branch to confirm that the locations and dynamic rows match the target machine. Schema format and Schema property fields document the shared authoring syntax.

Diagnostic commands#

Capture and Refresh perform Windows Runtime extraction as part of their normal work. The pinman winrt commands expose the same lower-level data for catalog development and troubleshooting.

Extract every category:

pinman winrt extract

Limit the extraction to Schema-tracked paths or to one category:

pinman winrt extract --tracked-only
pinman winrt extract --category Display

Compare two extracted JSON files, or compare one with a fresh read of the Machine:

pinman winrt diff older.json newer.json
pinman winrt diff saved.json --live

These commands work with the extraction files directly. Use Captures and the Explore page for Pinman's normal Source-and-Reference comparison workflow.