Form fields and repeatables - KayanOS Documentation

A form is more reliable when every visible control has one job: collect a value, show a derived value, select a controlled record, or repeat a known unit of work. This guide explains the field catalogue used by the KayanOS form runtime and the repeatable containers that turn one field or one section into a controlled list. It also explains what is stored when a form is saved, so a builder can design for review instead of only for a tidy first screen. The examples use a Syrian public-service directorate receiving a citizen service request that may need one or more site inspections and supporting materials. The field keys in examples are illustrative. Replace them with the keys in the actual form before publishing; translated labels are not expression keys. The captured form-builder view below shows the Site Inspections section of the Citizen Service Intake form in user-controlled repeater mode. It starts with one inspection and allows the form user to add up to three, which is a bounded model for related inspection rows. KayanOS user-controlled Site Inspections section repeater for the Citizen Service Intake form.

KayanOS user-controlled Site Inspections section repeater for the Citizen Service Intake form.

When to use it

Use a regular field when one submission needs one value: a requester name, date, amount, file, choice, location, or selected record. Use a field repeater when the same individual value can occur several times but does not need its own group of related inputs. A useful example is several attachment reference numbers, several contact methods, or several short material names. Use a section repeater when each repeated item has several related values that must stay together. An inspection row may need a location, visit date, outcome, notes, and attachments; a materials row may need a material type, quantity, unit, and supporting file. Keeping those values in one repeated section makes the reviewer see the boundaries between inspection one and inspection two instead of trying to reconstruct them from independent lists. Do not make a field repeatable merely because a value might be long. Use Text area or Rich text for a longer single narrative. Do not use a repeater as an unbounded data-import channel, and do not put unrelated questions in a repeated section just to make the page shorter. A service owner should be able to state what one row represents, who may add it, and how many rows are reasonable. Choose a normal field instead of a calculated value when a person must provide or correct the value. A calculated_value field is a derived display/value configuration: the builder forces it to be invisible, not required, not editable, and not repeatable. It is not an editable answer box. Use an entity calculated field when the result belongs on the entity record beyond a form session; see Calculated fields for that separate capability.

Configuration

Choose the smallest correct field type

The form builder provides the following runtime field types. Start with the type that matches the stored value and add a description when a person could interpret it in more than one way.

Field type	Use it for	Design and quality guidance
Text	A short, single-line value such as a request reference supplied by the citizen	Use a stable label and a validation rule only when there is a clear, service-owned rule.
Number	A count, measurement, or numeric quantity	Define the unit in the title or description; do not encode a unit in an unexplained number.
Date	A calendar date	Use for a date without a time-of-day commitment, such as date of visit.
Date and time	A timestamp where time matters	State the service timezone and whether the value is an appointment, observation, or deadline.
Time	A time of day	Pair it with a date when the value must be interpreted on a specific day.
Boolean	A clear yes/no decision	Write the label so that both answers are understandable and avoid double negatives.
Money	A monetary amount	Set the applicable currency and keep approval or fee policy outside the field label.
Text area	A plain multi-line explanation	Ask one focused question and give a reviewable instruction, not an open-ended invitation to include sensitive data.
Rich text	A structured narrative that needs formatting	Use sparingly; formatting should not substitute for controlled fields needed in reporting.
Select	One controlled choice or several controlled choices	Choose single when the saved value is one string; choose multi when it is an array of strings. Keep stored option values stable, unambiguous, and reviewed when a downstream expression depends on them.
Entity selector	A record from a configured entity	The default entity-selector access level is `all`, which resolves options through an organization-wide system-level data path. Use `user_permissions` only after testing it with the submitting member’s real role and scope. Entity filters narrow a query; they do not grant authorization.
Form-session selector	A related form session	Use when the service must connect this submission to another captured form session rather than retyping a reference. Its options and selected-record retrieval use the organization-wide system-level data path, not the participant’s ordinary record or scope permissions.
File	One uploaded supporting item or several homogeneous attachments	Use the Multiple setting when each file follows the same evidence rule. Configure accepted file types and maximum size when the service has an approved policy; use a repeatable section instead when every attachment needs its own metadata or review context.
Location	A location value	Explain the precision required and do not collect a location when a service-area choice is enough.
Calculated value	A value derived by its field expression	It is not visible, required, editable, or repeatable in the builder. Test its expression and the input fields it depends on.

Field-by-field builder views and service examples

The following real builder views show the control selected in the field-type picker. Use the stable key in the examples; the translated title is for people, while the key is what conditions and defaults read.

Text

Use applicant_name for one short name or reference that an applicant or staff member enters once. A validation rule can require a minimum meaningful length, but it should not attempt to infer an identity document number from a free-text name. KayanOS form Text field configuration for an applicant name.

Number

Use household_members for a count with a defined unit. Configure a validation such as a positive whole number when the service cannot proceed with zero; use Money instead when the value represents currency. KayanOS form Number field configuration for household members.

Date

Use requested_visit_date when the request needs a day but not a specific hour. A later appointment can use a separate Date and time field so a reviewer can distinguish a requested day from a confirmed time. KayanOS form Date field configuration for a requested visit date.

Date and time

Use appointment_time for a confirmed inspection or service appointment. State the office time zone in the description when a central team and local offices work in different locations. KayanOS form Date and Time field configuration for an appointment.

Time

Use preferred_contact_time for a recurring time-of-day preference. Do not use it as the only input for an appointment, because it does not carry a calendar date. KayanOS form Time field configuration for a preferred contact time.

Boolean

Use requires_site_visit for a single, unambiguous decision. A dependent section can safely use $.requires_site_visit.value == true when the Boolean has a documented default and each path has been tested. KayanOS form Boolean field configuration for a site-visit decision.

Money

Use estimated_service_fee for an amount that a person may enter or review. Keep the fee policy, approval authority, and currency decision in the service configuration and helper text rather than encoding them in a free-text answer. KayanOS form Money field configuration for an estimated service fee.

Text area

Use service_details for a plain multi-line explanation in the applicant’s own words. Split operational facts—such as address, category, and requested date—into their own fields so they remain searchable and reviewable. KayanOS form Textarea field configuration for service details.

Rich text

Use review_narrative for a staff-authored narrative that genuinely needs headings or lists. Do not rely on formatting to represent a controlled decision, status, owner, or amount. KayanOS form Rich Editor configuration for a review narrative.

KayanOS form Rich Editor configuration for a review narrative.

Single Select

Use service_category with stable option values such as civil_registration, municipal_service, and site_inspection. Conditions compare the stored value, for example $.service_category.value == "site_inspection", never a translated option label. KayanOS form Single Select configuration for a service category.

Entity Select

Use assigned_case only in a staff flow where the approved source entity and filter are known. Verify the selector’s organization-wide lookup behavior and avoid showing a browsable internal record picker in a public citizen form. KayanOS form Entity Select configuration for an assigned case.

Form Session Select

Use related_application when the reviewer must link this form to a previously captured form session. Restrict the source form and test no-result, search, and selected-session cases before publication. KayanOS form Form Session Select configuration for a related application.

File

Use supporting_evidence for a document or photo that follows one evidence rule. Turn on Multiple only when every file has the same purpose and policy; otherwise put the file and its metadata in a repeatable section. KayanOS form File field configuration for supporting evidence.

Location

Use service_location when an address or map position affects delivery, routing, or inspection. Explain the precision the service needs and do not request coordinates where a neighborhood or office choice is sufficient. KayanOS form Location field configuration for a service location.

Calculated value

Use visit_readiness_score for a value derived from the form, not entered by a person. It is intentionally invisible, not required, not editable, and not repeatable; use a short expression that can be tested with each input path. KayanOS form Calculated Value configuration for a visit-readiness score.

For most field types, the builder can store a default value and can evaluate the default as an expression. Text-like defaults are stored as text expressions; date and date-time defaults are represented as date values; Boolean starts with false unless configured otherwise. A default is a starting value, not evidence that the user has reviewed it. For an important confirmation, use a clear Boolean or action condition and test the resulting path.

Configure Select and File fields deliberately

A Select field has two independent decisions: selection mode and option source. Choose single when the service accepts one stored option value, for example one request category. Choose multi when the service accepts a set of stored option values, for example several service needs; the runtime saves that result as a string array. Test no selection, one selection, and several selections for a multi-select field. In particular, test every condition that consumes a multi-select value with the saved array shape rather than assuming it is one string. Choose an option source that can remain understandable after a label is translated or edited. Manual options have localized titles and stable stored values. Entity-backed options are available only when that capability is enabled and read controlled options from the selected entity field. Code options must resolve to an array; they can be strings or objects that supply a value and title. Whichever source you use, do not make a downstream condition depend on a display title. Record and test the stored values, especially before renaming, removing, or merging options. A File field also has a built-in Multiple switch. Use one multi-file field when every uploaded item has the same purpose, accepted types, size rule, and review treatment—for example, several pages of the same supporting evidence. Use a repeatable section when each attachment requires separate data such as document category, issue date, source, reviewer outcome, or a different validation rule. A multi-file field keeps a simple homogeneous upload simple; a repeater gives each item its own accountable row.

Configure selector data access deliberately

An entity selector is a data lookup, not merely a convenient picker. The default entity-selector access level is all, so its options are read through the organization-wide system-level data path. Use user_permissions only when the form runs for an identified member and the service genuinely requires the selector to respect that member’s ordinary record access. Test the exact member, role, scope, no-result case, selected-value case, and search case. An entity filter can keep a list focused—for example, only open inspection cases for the current locality—but it does not turn a system-level lookup into a permission boundary. The form-session selector is stricter from a design perspective: its option and selected-record lookups use the organization-wide system-level data path. It does not offer a participant-permission mode. Restrict its source form, keep any filter narrow, and use it only where the service owner has approved the visibility of every selectable session. Do not use either selector to expose choices in a public form, an unreviewed participant flow, or a sensitive-service flow merely because a filter produces a short list. Use a purpose-built public lookup or an approved server-side boundary when the user must see only records they are independently allowed to access. For a citizen-service intake that needs staff to attach an internal inspection case, keep the selector out of the public intake version. Put it in the member-only review version, configure the smallest approved entity/filter, and test with a reviewer who has the intended scope. If the public form needs a citizen to quote a case, collect a controlled reference value and resolve it only through an approved service-side process; do not present a browsable record picker. Each input also has four behavior decisions. They can be set as a simple switch or as a validated expression in the builder context:

Setting	Meaning	Safe question before enabling it
Default value	The initial value before a user changes it	Is this a safe starting point for every eligible submission?
Required	The form must have a valid value when this condition applies	Is the value actually necessary for the next review or action?
Visible	The user can see the item when this condition applies	Could hiding it make a required task or explanation confusing?
Editable	The user can change the item when this condition applies	Who owns correction after the value is set?
Validation rules	One or more conditions that must evaluate successfully	Does the rule explain a real data-quality policy, and have both outcomes been tested?

The builder validates these expressions against its available context. Keep conditions narrow and name the dependent field in the label or helper text when it affects what a citizen sees. The following is an illustrative visibility condition: it shows the inspection section only when the actual form key requires_site_visit is true.

$.requires_site_visit.value == true

For a conditional fixed row count, the count setting can also be an expression. This example creates two material rows for a request type whose actual select value is multi_site, otherwise one. Verify the option value in the published form; do not copy a display label into the expression.

$.request_type.value == 'multi_site' ? 2 : 1

Build a repeatable field or section

Open the field or section settings and enable repeatability. Give the repeater a clear title, then choose one of the three modes below. Count, minimum, maximum, and loop items can use a literal value or an expression that resolves in the repeater context. Initial count must be a literal numeric value: the current runtime converts it with Number(...) rather than evaluating an expression, so do not put JEXL in that setting. For user-controlled rows, set an explicit, service-owned maximum instead of relying on the missing-value fallback of 9999. The builder exposes the row mode and its bounds in one place. This real table-section configuration shows the user-controlled setting for one to three inspection rows. KayanOS user-controlled repeatable table rows with minimum one, maximum three, and initial count one.

KayanOS user-controlled repeatable table rows with minimum one, maximum three, and initial count one.

Mode	Runtime behavior	Choose it when	Avoid it when
`fixedCount`	The configured count becomes both the minimum and maximum. The user cannot add or remove instances.	Every request must show exactly the same number of rows, such as two required verification contacts.	The number depends on user choice or source data.
`userControlled`	The user can add and remove instances within configured minimum and maximum. The initial count controls the opening number of rows.	The citizen or staff member knows how many items to provide, such as one to five supporting materials.	The list must exactly mirror another list or controlled source.
`loop`	Instances are driven directly by the array returned by the loop-items expression; the actual row count is that array’s length. The implementation also carries zero/`9999` minimum/maximum fallback values, but they do not cap a loop array.	The rows must mirror known array data, such as approved material lines prepared elsewhere in the form.	The person must freely add or remove rows.

For a fixed set of rows, the same panel replaces the bounds with one count. This is appropriate for exactly two mandatory material checks, not for a variable number of inspections. KayanOS fixed-count repeatable table configuration with a count of two.

KayanOS fixed-count repeatable table configuration with a count of two.

Use a field repeater for a single repeated field. Use a section repeater when every row contains a group of fields, text blocks, or actions. The same repeat controls are available, but a section keeps its child values in each row. A field inside a table-layout section cannot remain an independent repeater; model the rows at the section level instead. For loop mode, the loop-items expression must resolve to the array that drives the rows. The next example is illustrative: it assumes a prior field stores an array under approved_materials. Each loop row is tied to an item in that array rather than being a manually chosen number of rows.

$.approved_materials.value

The loop mode opens a dedicated expression editor. The expression must return an array, not a single text value or a manually entered count. KayanOS loop repeatable configuration showing the items expression editor.

KayanOS loop repeatable configuration showing the items expression editor.

At database-save time, repeaters are stored as an array of instance values. A saved field or section repeater also has a session-facing requestedRepeat count and an instances collection. For loop-driven rows, the runtime writes the source item under @loop_item on each persisted instance alongside that row’s values. Treat that source value as a trace of the item that created the row, not as a user-entered field to edit by hand.

Read, display, and export repeatable values

There are two related shapes to understand. While the form is running, a normal field is an exposed field object, so its answer is read through .value. A repeater is also exposed as an object: use its .instances collection, then use .value for a repeated field or .children.<field_key>.value for a child of a repeated section. The table layout changes presentation, not the saved value shape. Use a field repeater named attachment_references when the submission needs several values of exactly the same kind. Read a known row by its zero-based index:

$.attachment_references.instances[0].value

To display every entered reference in one calculated text field, text block, or action label, project each row’s value and join it. The result is one readable string, such as EVD-001, EVD-002.

$.attachment_references.instances | getByPath("value") | join(", ")

Use a section repeater named inspection_rows when each row has related answers. Read a field in the first inspection as follows:

$.inspection_rows.instances[0].children.inspection_outcome.value

You can collect only rows with a controlled outcome, then show all outcomes or dates as a list. These expressions operate on the form-runtime instances, so the child field still needs .value.

$.inspection_rows.instances[.children.inspection_outcome.value == "unsafe"]

$.inspection_rows.instances | getByPath("children.inspection_outcome.value") | join(", ")

$.inspection_rows.instances | getByPath("children.visit_date.value") | join(", ")

Do not use the display string as the system of record. At save time, saved_state stores the business values as direct arrays and objects; it does not store the runtime-only .instances or .children wrappers. A field repeater saves a simple array, while a section/table repeater saves one object per row. A loop-driven row also retains its source item under @loop_item so a reviewer can trace how the row was created.

{
  "attachment_references": ["EVD-001", "EVD-002"],
  "inspection_rows": [
    {
      "visit_date": "2026-07-20",
      "inspection_outcome": "unsafe",
      "inspection_notes": "Repair the entrance ramp before approval."
    },
    {
      "visit_date": "2026-07-23",
      "inspection_outcome": "safe",
      "inspection_notes": "Corrective work verified."
    }
  ],
  "material_rows": [
    {
      "material": "Accessibility ramp",
      "quantity": 1,
      "@loop_item": { "material_code": "RAMP-01" }
    }
  ]
}

This distinction is useful when designing a document template, an automation payload, or an entity update after submission: use the direct saved arrays and row objects there. Use .instances, .children, and .value only inside the live form expression context. If a subsequent process needs a display-ready list, use the registered getByPath("path") transform deliberately rather than flattening the submitted data and losing row boundaries.

Table layout and nested rows

A repeatable section can use section layout or table layout. Section layout gives every instance its own grouped block and is easier for longer narratives, files, or conditional content. Table layout presents configured child fields, actions, and text blocks as columns; it is better for compact, comparable rows such as material, quantity, unit, and verification result. The table-section settings let the builder choose the mobile behavior next to the row configuration. Add only compact cells as columns; large evidence and narrative fields remain easier to review in a normal section layout. KayanOS table layout settings for comparable inspection rows.

KayanOS table layout settings for comparable inspection rows.

For a table section, choose the mobile behavior deliberately. hybrid is the default and presents table rows in a compact responsive-card style on small screens. scroll keeps the table form and lets the user scroll horizontally. Test both with representative titles and values. A table with long narratives, file details, or several conditional controls usually remains more understandable as a normal section. Nested repeaters are technically possible in form structure, but should be rare. Each outer row multiplies the number of controls and saved values below it, making mobile review, validation, and correction harder. Put an explicit maximum on every user-controlled level, keep the depth shallow, and use a related form or entity when the data has an independent lifecycle.

Worked example

A Syrian public-service directorate accepts requests for a local service. An intake officer records the service category, then records site inspections where needed. The service owner wants staff to compare inspection results quickly, while preserving exactly which notes and materials belong to each visit. Create these non-repeatable fields first: request_type (Select), requires_site_visit (Boolean), citizen_contact_reference (Text), and requested_service_date (Date). Use controlled Select values rather than free text for request_type, because later conditions rely on that value. Add an inspection_rows section with a clear title such as “Site inspections.” Its visibility condition is the first example in this guide. Put visit_date (Date), visit_location (Location), inspection_outcome (Select), inspection_notes (Text area), and evidence_file (File) inside the section. If every inspection file follows the same rule, enable Multiple on evidence_file; if staff must classify or assess each file separately, add a bounded repeatable evidence section with file metadata instead. Choose userControlled for inspection_rows. Set a service-approved minimum of 1 only when a visit is always required, an initial count of 1 so the expected first row is visible, and a modest maximum such as 3 when policy permits no more than three recorded visits per request. The user may add the second or third visit only within that range. Do not use fixed count if the number of visits varies, and do not use loop mode if the officer must decide whether an additional visit is needed. Create a second section called material_rows for material verification. If the service must always show the same two required material checks, use fixedCount with count 2. If the office receives an already-approved array of material requirements, use loop and point repeatable_loop_items to that array. For a loop row, explain in the row title that it is derived from the approved material list; the stored @loop_item makes the relationship reviewable after save. Use table layout only for material_rows if its children are compact: material type, quantity, unit, and verification status. Select hybrid mobile behavior first and test on a narrow screen. Keep inspection_rows as a section layout because notes and evidence files need room and context. Before publication, ask a reviewer to submit one request with one inspection and another with two. Review the saved session data by row: the first inspection’s date, location, result, notes, and file should remain together in instance zero; the second values should be in instance one. Then test the policy boundary by trying to add a fourth visit. A clear limit is safer than a form that appears to accept unlimited evidence.

Testing

Test in a non-production form with recognizable test values, not live citizen data. Record expected row counts and expected visibility before each test.

Test	Setup	Expected result
Field type	Enter a value appropriate to each configured type	The control accepts its intended value and the saved result is understandable to a reviewer.
Default	Open a new session without touching the field	The configured default appears; it changes only when the user edits an editable field.
Required/visible/editable condition	Exercise both sides of each expression	The field is required, shown, or editable only where the configured condition applies.
Validation	Enter one allowed and one disallowed value	The disallowed value blocks valid completion with an actionable message or correction path.
Select mode/source	Test single and multi values, then manual, entity-backed where enabled, or code-driven options that the service uses	Stored option values remain stable; multi-select saves an array and conditions are tested with no, one, and several values.
File multiple	Upload one and several homogeneous files through a Multiple-enabled File field	Each file follows the configured type/size rule without requiring an unnecessary repeated row.
Fixed count	Configure count `2`	Exactly two instances render; no add/remove route changes the count.
User-controlled	Configure min `1`, max `3`, initial `1`	A user can add and remove rows only within the configured bounds.
Loop	Return an array with two known items	Exactly two driven instances render and each saved row retains its corresponding `@loop_item`.
Table mobile layout	Test `hybrid` and `scroll` on a narrow viewport	Labels, cells, and actions remain usable without hiding essential information.
Nested review	Use the largest permitted outer and inner counts	The reviewer can identify each row and the form remains responsive enough for its approved use.

For an expression-based maximum, test the smallest and largest expected values and a missing input. The following illustrative expression assumes the form key risk_level is a Select value. Replace it with the service’s real field key and option values.

$.risk_level.value == 'high' ? 3 : 1

Troubleshooting

Symptom	Check first	Safe response
A condition shows an error	Does every referenced key exist in the current form context, and do Select values match their stored values?	Start with a simple literal condition, validate it, then add one dependency at a time.
A calculated value looks like an input	Is the field type `calculated_value`?	Treat it as a derived configuration. It is intentionally invisible, non-required, non-editable, and non-repeatable.
Rows cannot be added	Is the mode `fixedCount` or `loop`, or has the user-controlled maximum been reached?	Use user-controlled mode only when manual additions are policy, and set a clear maximum.
Too many rows appear	In loop mode, does loop-items resolve to more items than expected? In user-controlled mode, is the literal initial count or requested count too high?	Inspect the source array or the bounded user-controlled settings; do not delete rows to conceal an upstream data problem.
A loop row no longer matches its source	Was the source array changed after the session started?	Review the saved `@loop_item` and source data, then reopen or correct through the approved session workflow.
A table is hard to use on a phone	Are columns too numerous or values too long for a row?	Use section layout, simplify columns, or choose the tested `hybrid` or `scroll` behavior.
Repeated answers are ambiguous in review	Did independent fields repeat instead of one section?	Move related inputs into a section repeater so each instance has an explicit boundary.

Permissions and data-quality limits

Building, editing, and publishing a form require the appropriate application access. A user who fills out a form receives only the fields and actions the published form renders for that session; visibility does not grant access to unrelated entity records. Selector configuration is a separate data-access decision: the default entity-selector access level is all, while user_permissions must be selected and tested deliberately; form-session selector lookups use the organization-wide system-level data path. Filters and short option lists are not authorization. Do not use either selector to expose choices in a public form unless an explicit data-access review proves that every offered choice is appropriate for that participant. Data quality comes from clear field types, narrow conditions, controlled option values, reviewed validation rules, and explicit repeater bounds. Do not depend on a hidden field as a secret store: visibility is a presentation condition, not a substitute for access control or a data-retention policy. Avoid putting national identifiers, contact data, or private evidence into an expression, option label, or repeater title. Collect only data the service needs, describe why an upload or location is required, and use an approved retention and review process for files. When a repeatable section represents an accountable real-world unit, retain enough context to review it: the row title, date, responsible role where applicable, controlled outcome, and supporting evidence policy. A compact form is valuable, but it must still let a later reviewer understand who supplied each row and what it means.

Plan the full intake and publication sequence in Forms.
Configure conditional actions, completion gates, and signature evidence in Form actions, logic, and signatures.
Learn the expression syntax used by conditions and defaults in Expression language syntax.
Review saved sessions and follow-up work in Form submissions.

​When to use it

​Configuration

​Choose the smallest correct field type

​Field-by-field builder views and service examples

​Text

​Number

​Date

​Date and time

​Time

​Boolean

​Money

​Text area

​Rich text

​Single Select

​Entity Select

​Form Session Select

​File

​Location

​Calculated value

​Configure Select and File fields deliberately

​Configure selector data access deliberately

​Build a repeatable field or section

​Read, display, and export repeatable values

​Table layout and nested rows

​Worked example

​Testing

​Troubleshooting

​Permissions and data-quality limits

​Related guides