Settings UI v1
Behavior and constraints
Root settings references a pack-relative JSON document. Omitted settings with zero options yields Empty; with options it yields AutoGenerated. A valid path yields Authored. Invalid paths/documents reject the whole candidate without fallback to AutoGenerated. UI source/canonical hash is recorded separately from manifest identity.
Root schemaVersion=1, defaultLocale and pages are required; translations defaults to an empty dictionary and hiddenOptions to an empty array. Page requires id/title/groups. Group requires id/controls and may omit title. Both default order to 0 and visibleWhen to an empty array. A nonempty page needs a group, and a group needs a control. Preserve authored array order; order ranges from −1000000 to 1000000.
Control requires id/option. widget defaults to auto and also accepts toggle/choice/slider. label/description/unit/format is presentation; advanced/developerOnly defaults false and conditions default empty. Slider step is positive and matches option type; min/max appear together and may only narrow hard bounds. Choice values is required and exactly covers allowed, with display order preserved; entries permit value/label, requiring label. Toggle binds boolean, choice string/integer and slider bounded integer/number. auto rejects widget-specific fields.
Every canonical option appears exactly once in a control or hiddenOptions. Hidden entries permit only required option/reason. Missing, duplicate or simultaneously hidden/visible options fail with P9UI201. UI cannot redefine option type/default/allowed/hard bounds/impact.
A UI condition is option plus exactly one of equals/notEquals/in. Arrays combine with AND; in is nonempty and unique, with type/range-valid values. Page/group conditions affect descendants; controls separate visibility and enablement. The controlled-option → dependency-option DAG rejects self-dependencies and cycles (P9UI203). Manifest oneOf conditions use a different contract.
translations maps locale → key:text. Locale comparison ignores case; keys are case-sensitive. Any translation table requires defaultLocale. Resolve current locale → defaultLocale → caller fallback → key. A missing individual key falls back normally.
Paths are pack-relative .json, at most 256 characters; documents at most 1 MiB. Limits: 32 pages, 64 groups/page, 512 controls/document, 256 choices/control, 16 conditions/owner, 256 condition values, 4096 conditions/document, 512 hidden options, 32 locales, 2048 translations/locale and 8192/document. Local IDs allow 64 characters, short text 256, description/translation/reason 4096 and locale IDs 1–35. Reject duplicate keys and unknown properties at every level. The following fields are an actual Loader-whitelist projection, not an upstream official UI JSON Schema.
root
| Field | Ownership |
|---|---|
schemaVersion | Reviewed Loader whitelist; behavior above |
defaultLocale | Reviewed Loader whitelist; behavior above |
translations | Reviewed Loader whitelist; behavior above |
pages | Reviewed Loader whitelist; behavior above |
hiddenOptions | Reviewed Loader whitelist; behavior above |
page
| Field | Ownership |
|---|---|
id | Reviewed Loader whitelist; behavior above |
title | Reviewed Loader whitelist; behavior above |
order | Reviewed Loader whitelist; behavior above |
groups | Reviewed Loader whitelist; behavior above |
visibleWhen | Reviewed Loader whitelist; behavior above |
group
| Field | Ownership |
|---|---|
id | Reviewed Loader whitelist; behavior above |
title | Reviewed Loader whitelist; behavior above |
order | Reviewed Loader whitelist; behavior above |
controls | Reviewed Loader whitelist; behavior above |
visibleWhen | Reviewed Loader whitelist; behavior above |
control
| Field | Ownership |
|---|---|
id | Reviewed Loader whitelist; behavior above |
option | Reviewed Loader whitelist; behavior above |
widget | Reviewed Loader whitelist; behavior above |
label | Reviewed Loader whitelist; behavior above |
description | Reviewed Loader whitelist; behavior above |
unit | Reviewed Loader whitelist; behavior above |
format | Reviewed Loader whitelist; behavior above |
step | Reviewed Loader whitelist; behavior above |
min | Reviewed Loader whitelist; behavior above |
max | Reviewed Loader whitelist; behavior above |
advanced | Reviewed Loader whitelist; behavior above |
developerOnly | Reviewed Loader whitelist; behavior above |
values | Reviewed Loader whitelist; behavior above |
visibleWhen | Reviewed Loader whitelist; behavior above |
enabledWhen | Reviewed Loader whitelist; behavior above |
choice
| Field | Ownership |
|---|---|
value | Reviewed Loader whitelist; behavior above |
label | Reviewed Loader whitelist; behavior above |
condition
| Field | Ownership |
|---|---|
option | Reviewed Loader whitelist; behavior above |
equals | Reviewed Loader whitelist; behavior above |
notEquals | Reviewed Loader whitelist; behavior above |
in | Reviewed Loader whitelist; behavior above |
hiddenOption
| Field | Ownership |
|---|---|
option | Reviewed Loader whitelist; behavior above |
reason | Reviewed Loader whitelist; behavior above |
Complete examples
Sources and machine records
Coverage inventory · Schema v5 · Catalog v2 · Completion v2
schema-v3 · schema-v4 · schema-v5 · completion-v1 · completion-v2 · temporal · settings-guide ·