Presenting a field
Load this card when a task declares or changes how one field or type is
documented, edited and shown: its label and description text, Hidden,
ReadOnly, Size, RangeMin/RangeMax, an EnumSource chooser, a Nullable
or Boolean answer, a Foldable, InlineChoices, SuppressLabel or
UIIncludeDescription marker, a media field, or a Link on a row. Its rules
are generated from the presentation contract,
which owns them; arranging the page in display.json is the
Display Template card, and typed value formats
(Format, Money, PhysicalUnit, Bitflags, dates, FormattedText) are the
formatted output card. The
source documentation card owns the complete source
documentation contract, and the annotation inventory
gives each attribute's Rust and TypeScript spelling.
Order of work
- Document the node: a natural label line, a complete description, and the
List divider and property placement (
doc.*). - Choose its metadata: visibility and editability (
field.hidden-subtree,field.readonly-*), bounds (field.size-bounds,field.range-bounds-typed), data-backed choices (field.enumsource.*,field.picker-no-implicit-default). - Decide how an answer is asked: unanswered and null (ordinary initialization,
nullable.*), Booleans (boolean.answer-controls). - Add presentation markers where the default drawing is wrong: folding
(
fold.*), inline choices (inline.*), label suppression (suppress.*), inline descriptions (field.include-description), inline media (media.*). - When a row opens a Request, declare the
Linkand check its rendering (link.*); the Link contract itself is in protocols/runtime. - Compile with the Studio MCP
compile_schematool and fix every reported rule.
Rules to apply
Studio does not check these rules. Each is quoted from its owner.
Standard properties
Owner: documentation.md#standard-properties
doc.boolean.unanswered: Without a schema Default, a required Boolean starts unanswered. Both choices are unselected; the editor holds an undefined value and refuses submission until one is chosen. It never encodes undefined as false or null.
Unanswered fields
Owner: presentation.md#unanswered-fields
field.unanswered: Unanswered fields. A field the person answers that noDefault,Fixedor copy initializes starts undefined (unanswered), and a non-Nullable field never holds null. When an editor opens, an undefined field shows only its neutral empty state: its placeholder, such as an unselected choice or "Choose date…", never an error look; an undefined Nullable's text uses the secondary text color. When Next or Submit is blocked, the client marks the first field that blocks it: below that field, an error icon and the missing-answer or validation message, in the platform's error color role and announced politely to assistive technology. It opens any fold or summary page holding the field and scrolls it into view; it does not move focus. The mark clears once that field passes, and it does not move to another field until the next blocked Next or Submit. An undefined field is reported as a missing answer, never as a null value.
Presentation locks
Owner: presentation.md#presentation-locks
tpl.lock.meaning:lockkeeps the person from changing a value the App's business logic already set. Its most common use is withAskOnAdd: the person gives a member's defining value at Add, and the lock keeps it fixed afterwards. It is presentation only and restricts the person alone: initialization,CopyFrom,EditRequestvalues, calculation and link-returnCopyToresults, AI Import, draft restoration, and the App write a locked value exactly as an unlocked one, and its validation and save-path handling are unchanged.
Template validation
Owner: presentation.md#template-validation
inline.lint.over-twelve(judgment): It warns when anInlineChoicesfield or type declares more than 12 choices, which always use the selector.
Common field metadata
Owner: presentation.md#common-field-metadata
field.size-bounds:SizeMin/SizeMaxfollow the shared size contract: List element count, String UTF-8 byte count, and Bytes byte count. Both TypeScript@LibertasSize(min=..., max=...)and Rust#[libertas_size(min=..., max=...)]emit these same attributes. The bounds are inclusive; size zero is valid unless excluded by the minimum. Nullable null remains separate from an empty value.field.picker-no-implicit-default: User and group pickers do not implicitly select the current user or a singleton candidate. Declare an explicit default using the User and group default contract.field.hidden-subtree:Hiddensuppresses the complete value subtree, including list elements and controls, nested fields, summaries, and promoted values. Hidden data remains part of the typed value for validation and protocol encoding.flattendoes not expose hidden descendants.field.readonly-user-only:ReadOnlyrestricts the user only: clients present the value and offer no ordinary editing control for it. It never restricts the platform or the application. Schema initialization (Fixed, Default, localized defaults),CopyFromfrom a Response or the reference context,EditRequestvalues, calculation and link-returnCopyToresults, draft restoration and the application's own handling of the submitted value all write a ReadOnly field exactly as they write an editable one. A value that must not change after initialization isFixed, not ReadOnly. Hidden fields are ReadOnly in effect, since no editor shows them, and are written the same way.field.readonly-list-membership:ReadOnlyon an Array/List prevents changing its membership or order: no Add, Remove, or reorder action may mutate that list. It does not recursively make member values read-only; members and their fields keep their own editability. To prohibit member edits, mark the applicable member type or fields as well. Context menus, swipe actions, pickers, and deferred actions must enforce the same list-owner rule at both presentation and execution. A promoted row does not change which list owns a removal or reorder operation.
Add time values
Owner: presentation.md#add-time-values
field.ask-on-add.meaning: Add-time values.AskOnAddmarks a value the person gives before a List member exists: a field of a List's member Table, reached from the member through struct fields, never through another List; or a List field whose member has a value of its own, which asks the member itself. A field's marker applies wherever its Table is such a member. Any number of a member's fields may carry it, of any type that has a value of its own: a scalar (String, Number, Boolean, DateOnly, DateTime, Bytes), an Enumeration, Bitflags, or a Union. When the person chooses Add on the List, the client first asks for every marked value; confirming creates the member with those values and every other field at its normal initialization, then shows the new member as the List's layout shows any new member: a summary opens its item page, and inline rows, a table, or an accordion show it in place. Without every value, no member is added, and Cancel adds nothing.
Common field metadata
Owner: presentation.md#common-field-metadata
field.ask-on-add.person-only: The person's Add only: a member that AI Import, CopyTo, an EditRequest, or the App adds is unaffected, and after Add each value is an ordinary field; whether the person may change it is a templatelock's, a separate concept.field.ask-on-add.with-lock(judgment): Commonly paired withlock. The usual purpose ofAskOnAddis a value that decides what the member is, such as a document's form: the person gives it once at Add, and a templatelock(on a Union,lock: "variant") then keeps the person from changing it, so the item editor shows the chosen form and never offers to switch it.field.enumsource.picker-entry-display(judgment): A picker entry draws its source member as the source List draws it. When the source List has asummaryortablerule, each entry shows that rule's paths or columns for its member, with the text above as the entry's first line, and the filter matches that text too. The rule applies to the picker even when the List itself is Hidden and never drawn. Without such a rule the entry is the text alone. A host's chosen value, drawn outside the picker, shows only that text; a hosting item that needs the fuller display carries it as its own ReadOnly, OutputOnly field, normally of the same display-only type the source member uses, so the item and the picker entry read the same.field.enumsource.index-not-identity(judgment): A saved index remains a position, not a persistent record identity. Apps that need record identity must resolve the selection against the appropriate accepted-data revision.
MIME-aware Bytes presentation
Owner: presentation.md#mime-aware-bytes-presentation
media.inline.pdf.authoring: Choose media and size with the platform preview limits in mind: PDF previews vary by client and video uses an icon.
Inline media size
Owner: presentation.md#inline-media-size
media.inline.images(judgment): Images. The raster formats the thumbnail decodes draw inline. SVG and every other vector or markup format are never rendered, at any size.
SuppressLabel: label-free value rows
Owner: presentation.md#suppresslabel-label-free-value-rows
suppress.source-and-hint:@LibertasSuppressLabelin TypeScript and#[libertas_suppress_label]in Rust suppress the visual label contributed by the selected node. The parser result carries{"Name":"SuppressLabel","Value":"true"}; Studio compiles it into the Display Template as the Booleansuppress_labelhint and removes it from the final schema. A template rule can setfalseto restore the ordinary label under the cascade. The rule does not propagate to children.suppress.label-only: The hint suppresses a visual label, never a value or subtree. It does not change folding, editing, links, menus, membership permissions, help, or the semantic name used for accessibility and editor dialogs. A control without a visible label still has its localized accessible name. On a promoted row, only its displayed label is omitted; the promoted value and its declaring link remain available under the action rule.Hiddencontinues to suppress the entire presentation subtree and wins before every template rule.
Boolean answer controls
Owner: presentation.md#boolean-answer-controls
boolean.answer-controls: Required Booleans without a default are explicit, initially unselected choices. A non-nullable Boolean with an explicit Default permits a switch only when no custom labels exist. In an editor, nullable Booleans use one inline radio group for true, false, and explicit null. All three choices remain visible when null is selected; choosing the null option stores actual null. Use localized TrueText, FalseText, and NullText document properties for their captions, with localized Yes, No, and None when omitted. Display labels never change wire values. Every client arranges the choices by rungs 1 to 3 of the inline-choice ladder: beside the title, on one line below it, or one per line. ReadOnly and Fixed keep the current selection visible and disable editing.
Inline choices
Owner: presentation.md#inline-choices
inline.union-one-per-line(judgment): For a Union, the selected branch's fields render directly below its chosen radio control, before the next choice and indented to the choice's caption, only while the branch has exactly one visible field whose type is Number (aDateOnlydate included), String, Boolean,DateTimeorTimeOnly, where a Number or String carrying Bitflags or EnumSource counts as an Enumeration; a branch whose payload is itself such a scalar is that one field. Otherwise its fields render after the whole choice group: with no visible field, with two or more, or with one field of any other type, such as an Enumeration (Bitflags and EnumSource included), Union, struct, List, or Bytes (FormattedText included). A field is visible when its row is shown, under the same rules that show or withhold that row (Hidden, and template withholding such aswhen_single_choice), and the count is taken again whenever that visibility changes. Promotion of the Union or of its owner never changes this placement. Selecting another choice replaces the applicable fields. A Union with any declared branch that carries data, every branch but aNilone, stands one per line, as the ladder below states. Authors who want the choices on one line with the selected content below use thetabslayout instead.inline.false-and-forward-tolerance: A template rule withinline: falsestill turns inline choices off. The marker changes presentation only, never data, encoding, or paths. A client without inline support keeps the choice selector.
Link rendering
Owner: presentation.md#link-rendering
link.formatted-text-block: On a FormattedText field the whole block is the tap target; links inside FormattedText markup are not supported.
Folding structs and unions
Owner: presentation.md#folding-structs-and-unions
fold.presence-enables: Presence enables folding;falsedoes not disable it. Studio compiles it into the Display Template as thefoldhint and removes it from the final schema; clients read folding only from the template, where a rule may also change it per device.fold.nondefault: Withinitially_open"nondefault", the value starts expanded when anything under it differs from its default and collapsed otherwise, so rarely used fields stay out of the way until they hold something. Its default is the value the App's default document gives that node; for a List member, or a node the default document does not reach, it is the default value of its type. Values are compared decoded, at every depth, including a selected Union variant and a List's member count, never by their displayed text, so the result is independent of locale. Values the platform generates rather than the person, such as a virtual device identity, are left out of the comparison, and working out the default registers nothing (no identity, name or icon). Like every initial state, it is decided when the page is displayed and does not close or open the value while the person edits.fold.per-value-permission: Each nested value owns its folding permission; a marker does not grant permission to its descendants. Lists follow the same explicit-permission rule. Changing a union variant reveals its new fields. Union selectors remain editable independently of folding.fold.promoted-union-row: For a promoted union, the shared owning row may fold when either the owning Table or the promoted union has Foldable on its type or field. Promotion andflattenremain independent of folding.
Unanswered fields and null
Owner: presentation.md#unanswered-fields-and-null
nullable.empty-string-is-value: An empty String is a present value, distinct from null; incomplete native input remains invalid.
Nullable choices
Owner: presentation.md#nullable-choices
nullable.blank-value.unanswered: The null answer always comes first. While unanswered, no choice is selected and a picker shows “Select…”. A value answer chosen with its value still blank stays unanswered; null is never inferred from a blank editor. Read-only display keeps the caption described above.nullable.initialization: Initialization follows the Union (type initialization): with no Default the question starts with neither answer selected, shows “Select…”, and blocks submission until the person chooses; the reserved Default$nullstarts it on the null answer; any other Default starts it on the value answer with that value. The stored value, its encoding, CopyFrom, CopyTo, validation rules, AI Import, and calculations still seenullor the value: the unanswered state exists only in the editor and is never encoded.
Undefined and its sources
Owner: schema.md#undefined-and-its-sources
init.undefined-relationships(judgment): A node is undefined until it is initialized byFixed, aDefault, a copy, a supplied value, or type initialization (an empty List, a null non-editable Nullable); otherwise it stays undefined until answered, which is how a must-answer question is asked (EditRequest or WorkflowRequest). Undefined cannot be encoded, so no protocol message carries it; only an editor holds it, showing its neutral empty state (unanswered fields) and blocking submission while required.
Rules Studio enforces
Studio checks these rules and reports errors or warnings as their owners specify. The owner holds the full rule.
Link rendering
Owner: presentation.md#link-rendering
link.hidden-rows-rejected: Hidden rows have no link; Studio rejects that placement
Folding structs and unions
Owner: presentation.md#folding-structs-and-unions
fold.placement:Foldable(optionalinitially_opentrue, false or nondefault) is permitted only on an effective Table, Union or List