Schema property fields

Property Items represent individual values inside structured files, the Registry, Windows Runtime, and REST services. Their Schema fields tell Pinman how to interpret a value, compare it, present it to a user, and write it where supported.

This page covers fields shared across property itemtypes. Start with Schema items for locations, itemtypes, and parent-child structure.

Value fields#

Field	Values	Purpose
datatype	string, int, float, bool	Type-aware comparison and conversion.
default_value	scalar	Fallback used by itemtypes that define a value for missing source data.
units	string	Displayed unit such as Hz, ms, %, or pixels.
storage_format	format string	Spelling to use when writing a new value.
display_format	format string	Human-readable rendering in the UI and CLI.
io_mode	read-write, read-only, ephemeral	I/O policy inherited through the tree.
write_strategy	target, guided	Direct or guided write behavior where supported.
post_action	string	Follow-up hint such as restart service or reboot required.

Datatypes and comparison#

datatype gives comparison a type-aware value. For example, the text token "1" and the integer 1 compare as the same value when datatype is int.

The datatype also controls validation and conversion when Pinman writes a value. Declare it when the source format alone does not establish the intended type.

I/O modes#

The I/O mode distinguishes persistent settings from live readings:

io_mode	Meaning
read-write	Persistent, comparable, and writable.
read-only	Persistent and comparable, but not writable through Pinman.
ephemeral	A live reading that is neither writable nor compared as persistent state.

Descendants inherit the container's I/O policy. A child can narrow that policy, but it cannot make itself more writable than its parent.

Storage and display formats#

When writing text, Pinman follows the spelling already present in the file. An existing lowercase true remains lowercase, and a fixed-width float keeps at least its existing precision. storage_format supplies the spelling when Pinman creates a new value.

Boolean storage format names are:

true_false  True_False  yes_no  Yes_No  1_0  on_off  On_Off

Numeric display and storage formats use Python-style format specifications such as .2f, .6f, or .0%.

display_format changes presentation without changing the stored value. For example, .0% presents the stored float 0.8 as 80%.

UI control fields#

Writable properties can describe how the Pinman UI should present their controls.

Field	Meaning
widget	slider, toggle, stepper, select, text, color, duration, or button
min, max, step	Numeric control bounds in the stored unit.
choices	Mapping from stored values to user-facing labels.

This Windows volume property appears as a slider from 0 through 100 percent, while its stored value remains between 0 and 1:

- selector: Volume
  itemtype: winrt_property
  datatype: float
  units: "%"
  display_format: .0%
  widget: slider
  min: 0
  max: 1
  step: 0.01

Pinman's Windows Runtime catalog already supplies metadata for its known properties. A Schema can declare these fields when it needs to override the catalog values. File, Registry, and REST property itemtypes can declare the same shared fields directly in Schema YAML.

Realm-specific fields#

Each property itemtype can add fields required by its source. For example, a CSV file defines row identity on its file Item, while a REST property declares read and write blocks.

Continue with the relevant reference:

• Supported file formats
• Windows Registry
• Windows Runtime
• REST schema items