> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kayanos.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Entity fields and layouts

> Design reliable KayanOS records: every supported field type, when to use it, and how to arrange it for real work.

## Start with the decision, not the field picker

An entity is the record type your team manages: a request, permit, inspection, asset, employee assignment, project, or payment adjustment. A field answers one question about that record. A layout decides when and where that question is shown.

Before adding a field, write down:

1. What decision will this value support?
2. Who enters it, and at what point in the process?
3. Is it free narrative, a controlled choice, a relationship, a time value, or a calculated result?
4. Must it be searched, filtered, reported on, signed, exported, or kept private?

If a field does not change a decision, a hand-off, or a report, do not add it yet. Small records with clear purpose are easier to complete and easier to trust.

## A practical model: service licensing and inspections

A city service team can use one app to receive a business-license request, assign an inspection, record the decision, and notify the responsible team. The same design pattern works for municipal permits, maintenance tickets, social-service cases, procurement requests, HR onboarding, and project change requests.

| Record          | Purpose                                 | Typical fields                                                                       |
| --------------- | --------------------------------------- | ------------------------------------------------------------------------------------ |
| License request | Captures what was requested and by whom | reference number, applicant, service category, narrative, attachments, received date |
| Site inspection | Records a visit and its evidence        | scheduled window, location, inspector, findings, photos, result                      |
| Decision        | Captures the accountable outcome        | status, decision date, reviewer, conditions, signed document                         |
| Follow-up task  | Makes the next action owned and visible | action, owner, due date, priority, completion status                                 |

The request should not contain every inspection detail. Use relations so each record has a clear owner and lifecycle while the team can still navigate between them.

## Field type reference

Every field below is supported by KayanOS entities. Choose the type for the meaning of the value, not for the visual control that happens to look convenient.

### Dedicated guides for governed fields

Two capabilities need a decision beyond choosing a field type. Read [Serial IDs](/build/serial-ids) before issuing a public reference: it explains namespaces, generation modes, manual-assignment limits, audit history, and collision-safe testing. Read [Calculated fields](/build/calculated-fields) before deriving values: it explains expression context, direct and inverse relations, persistence, background refresh, and data-quality limits.

### `text`

Use **Text** for a short, single-line value: a request title, external reference, neighborhood name, vehicle plate, or short contact name.

![KayanOS Text entity field configuration for a request title.](https://kayanos.app/docs-images/en/build/entity-fields/text-settings.png)

* Choose it when the value is primarily read as text and is usually short.
* Do not use it for long narratives, controlled states, dates, or numeric calculations.
* Use a stable field key such as `external_reference`; a readable title can change later without breaking integrations.
* For identifiers where leading zeroes matter, use Text rather than Number.

### `long_text`

Use **Long text** for an unformatted narrative: an issue description, inspection observation, justification, or hand-over note.

![KayanOS Long Text entity field configuration for a service summary.](https://kayanos.app/docs-images/en/build/entity-fields/long-text-settings.png)

* It preserves a clear paragraph-style answer without turning it into a document editor.
* Ask one focused question per field. Separate “problem observed” from “recommended action” so both can be reviewed and reported independently.
* Do not use it as a substitute for controlled fields that you need to filter or count.
* Set the field as required only when the process cannot proceed without a meaningful explanation.

### `rich_text`

Use **Rich text** when the author needs formatting such as headings, lists, emphasis, or structured instructions.

![KayanOS Rich Text entity field configuration for an inspection narrative.](https://kayanos.app/docs-images/en/build/entity-fields/rich-text-settings.png)

* Good uses include an inspection report, service guidance, decision rationale, or internal knowledge article.
* Keep the title, status, owner, and dates in separate fields; rich text is not a reliable source for reporting.
* Use it carefully in public-facing flows. Structured fields are better for searchable or auditable facts.
* Decide which roles may edit rich text, because formatting can make a change appear more significant than a simple note.

### `phone`

Use **Phone** for a contact telephone number that should be entered and displayed as a phone value.

![KayanOS Phone entity field configuration for an applicant contact number.](https://kayanos.app/docs-images/en/build/entity-fields/phone-settings.png)

* Use it for a preferred contact number, emergency line, or service desk number.
* Keep a separate Text field for extensions or a reference number that only looks like a phone number.
* Do not use Phone for a national identifier or a value that may contain leading zeroes but is never dialed.
* Consider who is allowed to view or export it; phone data is often personal data.

### `serial_id`

Use **Serial ID** for a human-readable, traceable record number generated by the system.

![KayanOS Serial ID entity field configuration for a request reference.](https://kayanos.app/docs-images/en/build/entity-fields/serial-id-settings.png)

* Good examples are `LIC-2026-0142`, an inspection number, a payroll cycle code, or a maintenance ticket number.
* Use it as the reference shown in conversations, documents, and dashboards; do not ask staff to invent it manually.
* Keep the generated identifier separate from the database record ID and from an external reference supplied by another system.
* Design the prefix and numbering rule before publishing. Changing a numbering convention after external use creates avoidable confusion.
* Use the full [Serial IDs](/build/serial-ids) guide to configure allocation mode, namespace, date format, prefill, correction history, and test cases.

### `number`

Use **Number** for values you need to calculate, compare, aggregate, or chart.

![KayanOS Number entity field configuration for a public-service quantity.](https://kayanos.app/docs-images/en/build/entity-fields/number-settings.png)

* Use it for quantity, area, number of attendees, score, amount, percentage, or workload hours.
* Do not use it for telephone numbers, postal codes, national IDs, or any identifier where formatting and leading zeroes matter.
* Decide the unit in the field title or description: `area_m2`, `estimated_hours`, or `requested_amount_syp` is clearer than `value`.
* Pair it with validation or a calculated field when a range, maximum, or derived result matters.
* For a stored derived result, use [Calculated fields](/build/calculated-fields) to choose a safe expression, relation context, refresh path, and test plan.

### `duration`

Use **Duration** for an amount of time, not a point in time.

![KayanOS Duration entity field configuration for estimated service time.](https://kayanos.app/docs-images/en/build/entity-fields/duration-settings.png)

* Use it for expected inspection time, service-level allowance, travel duration, or training hours.
* Use Date, Time, or Date-time when you need to know *when* something occurs.
* State the business unit in the label and use consistent units across reports.
* A duration can drive workload planning; it should not be used to infer attendance without a separate time record.

### `boolean`

Use **Boolean** for a clear yes/no fact.

![KayanOS Boolean entity field configuration for a site-visit decision.](https://kayanos.app/docs-images/en/build/entity-fields/boolean-settings.png)

* Use it for “site accessible”, “consent received”, “requires supervisor review”, or “documents complete”.
* Make the meaning of both states explicit. A label such as “Documents complete” is less ambiguous than “Documents status”.
* Do not use Boolean when the real answer has more than two states; use Select or Status instead.
* Avoid making an optional Boolean carry three meanings such as yes/no/not assessed. Model “not assessed” explicitly if it matters.

### `date`

Use **Date** for a calendar day with no time-of-day meaning.

![KayanOS Date entity field configuration for a requested visit date.](https://kayanos.app/docs-images/en/build/entity-fields/date-settings.png)

* Good uses include request date, expiry date, date of birth, leave date, or planned completion date.
* Use Date-time for appointments and events where the time zone or hour matters.
* Do not store a date in Text merely because it arrived from a spreadsheet that way.
* Use calculated expressions for deadline rules rather than asking users to calculate dates manually.

### `datetime`

Use **Date-time** for an event that happens at a precise moment.

![KayanOS Date and Time entity field configuration for an appointment.](https://kayanos.app/docs-images/en/build/entity-fields/date-time-settings.png)

* Use it for submission timestamp, appointment start, approval time, incident occurrence, or message delivery time.
* Make the time-zone expectation clear for teams operating across locations.
* Use a Date range or Date-time range when the event has both a start and an end.
* Separate a system audit timestamp from a business timestamp such as “inspection completed at”.

### `time`

Use **Time** for a recurring clock time without a specific day.

![KayanOS Time entity field configuration for a preferred contact time.](https://kayanos.app/docs-images/en/build/entity-fields/time-settings.png)

* Use it for opening time, shift start, daily cutoff, or a recurring service window.
* Do not use it for a one-off appointment; use Date-time instead.
* Combine Time with a Date only when the business process requires both values independently.
* Write the time-zone or local-office rule in the field description if people in several regions use the app.

### `date_range`

Use **Date range** when a calendar period has a start and end date.

![KayanOS Date Range entity field configuration for a service period.](https://kayanos.app/docs-images/en/build/entity-fields/date-range-settings.png)

* Good uses include leave period, project phase, service suspension period, or funding window.
* Use it instead of two unrelated Date fields when the range is one business concept.
* Validate that the end does not precede the start.
* Use Date-time range for booked windows or any period where hours and minutes matter.

### `datetime_range`

Use **Date-time range** for a precise window with a start and end moment.

![KayanOS Date and Time Range entity field configuration for an inspection window.](https://kayanos.app/docs-images/en/build/entity-fields/date-time-range-settings.png)

* Use it for an inspection appointment, maintenance outage, event slot, or staffed service window.
* It makes overlap checks and calendar views more reliable than storing a free-text schedule.
* Set a clear expectation for rescheduling and cancelled appointments; a range alone is not a workflow state.
* Use a separate Status field to distinguish proposed, confirmed, completed, and cancelled windows.

### `time_range`

Use **Time range** for a recurring daily interval without a specific date.

![KayanOS Time Range entity field configuration for reception hours.](https://kayanos.app/docs-images/en/build/entity-fields/time-range-settings.png)

* Use it for counter opening hours, normal shift hours, or a daily call-centre window.
* It is not a substitute for staff attendance or a dated appointment.
* Name the field by purpose, for example “public service window”, not simply “time range”.
* Model exceptions such as holidays or special closures in their own records.

### `select`

Use **Select** for a controlled list of values that staff must choose consistently.

![KayanOS Select entity field configuration for a controlled service category.](https://kayanos.app/docs-images/en/build/entity-fields/select-settings.png)

* Good uses include service category, priority, language, permit class, risk level, or reason code.
* Give every option a stable machine value and a clear, translated display label.
* Use a multi-value configuration only when selecting several values is truly meaningful; otherwise a relation is often clearer.
* Do not put a process lifecycle in a general Select when you need transitions, responsibilities, or reporting by stage. Use Status.

### `file`

Use **File** for documents, photos, scans, or other attachments.

![KayanOS File entity field configuration for a supporting document.](https://kayanos.app/docs-images/en/build/entity-fields/file-settings.png)

* Use it for identity evidence, inspection photos, a signed letter, a site plan, or a supporting spreadsheet.
* Keep the file purpose explicit: a separate “site photo” field is more useful than one unstructured “attachments” field when evidence types matter.
* Do not rely on a file name as a workflow state. Store approval, reviewer, and decision in their own fields.
* Confirm access and retention rules before exposing files through a public form or external integration.

### `relation`

Use **Relation** to connect this record to another KayanOS entity.

![KayanOS Relation entity field configuration for an assigned inspector.](https://kayanos.app/docs-images/en/build/entity-fields/relation-settings.png)

* Use it for request-to-case, case-to-inspection, inspection-to-location, project-to-budget, or employee-to-assignment links.
* Relations preserve one source of truth. Do not copy a related record’s name, status, and owner into multiple text fields unless you have a clear historical-reporting reason.
* Decide whether the relation is one-to-one, one-to-many, or many-to-many before building forms and dashboards.
* Review the deletion behavior and access model. A user who can see a request may not automatically be allowed to see every related record.

### `form_session`

Use **Form session** when the entity must retain the originating form submission context.

![KayanOS Form Session entity field configuration for a linked application.](https://kayanos.app/docs-images/en/build/entity-fields/form-session-settings.png)

* It is useful for tracing a public or staff form submission back to the session that created or updated the record.
* Use Relation for a normal business relationship between two entities; Form session is specific to the form lifecycle.
* Keep the entity’s business fields readable on their own. A reviewer should not have to open a form session to understand the record’s status.
* Do not treat the form session as a substitute for an accountable owner or workflow status.

### `json`

Use **JSON** for advanced, structured data whose shape is defined by an integration or a carefully controlled technical design.

![KayanOS JSON entity field configuration for structured external reference data.](https://kayanos.app/docs-images/en/build/entity-fields/json-settings.png)

* Use it for a bounded external payload, a configuration object, or a dynamic structure that cannot be represented safely with normal fields.
* Do not use JSON for ordinary staff-entered business data. It is harder to validate, search, translate, and report on.
* Document the expected keys, value types, and versioning rule before any integration writes to it.
* Expose a calculated or normal field for values that people need to filter, review, or export routinely.

### `member_selector`

Use **Member selector** for an accountable KayanOS member or members.

![KayanOS Member Selector entity field configuration for a case owner.](https://kayanos.app/docs-images/en/build/entity-fields/member-selector-settings.png)

* Use it for case owner, approving manager, inspector, project lead, or follow-up assignee.
* Use Text or Relation for a person who is not a KayanOS member, such as an applicant or supplier contact.
* Keep responsibility distinct from hierarchy: a manager is not automatically the owner of every record in their unit.
* Pair an owner with a Status and due date when the record represents work that must move forward.

### `avatar`

Use **Avatar** when the record needs a compact visual identity.

![KayanOS Avatar entity field configuration for an applicant photo.](https://kayanos.app/docs-images/en/build/entity-fields/avatar-settings.png)

* It can support member, team, service, or location presentation where a small image improves recognition.
* Do not use it as the only evidence of identity; keep a text name and stable identifier as well.
* Use File for formal images or evidence that must be retained, reviewed, or downloaded.
* Confirm privacy expectations before storing a person’s photograph.

### `location`

Use **Location** for a geographic place that may be displayed on a map or used for service routing.

![KayanOS Location entity field configuration for a service location.](https://kayanos.app/docs-images/en/build/entity-fields/location-settings.png)

* Use it for an inspection site, facility, branch, project area, or service centre.
* Use Text for a simple descriptive place name when no geographic behavior is required.
* Keep address, coordinates, and service-area logic consistent with the organization’s mapping and privacy rules.
* Link recurring sites through a Relation rather than retyping the same location on every record.

### `action`

Use **Action** for a controlled record-level operation that a user deliberately invokes.

![KayanOS Action entity field configuration for scheduling an inspection.](https://kayanos.app/docs-images/en/build/entity-fields/action-settings.png)

* Use it for a carefully designed next step such as creating a follow-up, producing a document, or starting an approved review action.
* The action label must explain its outcome; “Submit for review” is clearer than “Run”.
* Do not use Action to hide a workflow decision. Store the decision, actor, and resulting status in fields that can be reviewed later.
* Test with a non-production record and confirm permissions before making an action available to a wider role.

### `status`

Use **Status** for the lifecycle state of a record.

![KayanOS Status entity field configuration for controlled review status.](https://kayanos.app/docs-images/en/build/entity-fields/status-settings.png)

* Use it for draft, received, under review, awaiting evidence, approved, rejected, completed, or cancelled.
* Status is more than a label: it should reflect the point in the process and make the next responsible action understandable.
* Keep the state list small and mutually clear. If two statuses lead to the same work, combine them.
* Use a Select for a classification such as service category; use Status when the value changes how work progresses.

## Build layouts that match the work

The same record is read differently by an intake officer, reviewer, manager, and auditor. A layout should reduce noise without hiding the facts needed for the next decision.

### Recommended structure for a service record

| Section or tab         | What belongs there                               | Why                                                          |
| ---------------------- | ------------------------------------------------ | ------------------------------------------------------------ |
| Identity               | serial ID, title, category, requester relation   | Lets anyone recognize the record quickly                     |
| Intake                 | received date, channel, description, attachments | Preserves what arrived and how                               |
| Assessment             | owner, priority, location, inspection relation   | Supports triage and assignment                               |
| Decision               | status, reviewer, decision date, rationale       | Makes accountability explicit                                |
| Follow-up              | tasks, due dates, completion evidence            | Keeps work moving after the decision                         |
| Audit and integrations | form session, source payload, system metadata    | Keeps technical detail available without crowding daily work |

Use tabs when a record has distinct phases or a large amount of evidence. Use a single field layout when the record is small and staff must complete it quickly. Put the most important next decision near the top; do not make a reviewer scroll through historical detail to find the current status and owner.

## Configure the record detail experience

### Choose the entity primary photo

In the entity settings, **Primary photo field** can point to an eligible `avatar` field on that entity. Select it when a stable photo or logo helps people distinguish records in entity lists and record headers; choose no field when the entity has no approved visual identity. The configured field controls presentation only. It does not make a private image public, replace the record name, or grant file/record access.

Test creation, update, removal, and a missing-image record. Confirm that the list falls back to a non-image identity without a broken URL, and that changing or deleting an avatar updates the displayed photo through the normal field lifecycle. Do not use a sensitive evidence attachment or an unrelated file field as the primary photo.

Open the entity settings to choose how saved records are presented. The **Standard** layout keeps the familiar field-and-section view. The **Refined** layout adds a stronger identity area, an overview, insight summaries, responsive tab navigation, and optional related-record and activity areas. Choose the presentation after the record model and access rules are stable; a refined layout cannot repair unclear fields or missing permissions.

Configure the detail view deliberately:

* choose compact, default, or comfortable density for the amount of information and the devices staff use;
* select and order tabs, then choose a valid default tab;
* choose primary and secondary hero fields that identify the record without exposing restricted data;
* decide whether to show the overview preview and section rail;
* enable activity or related-record presentation only when the intended role may access that information; and
* test the configured layout with empty, ordinary, and exception records in both interface directions.

The refined view can derive completeness or expiry context from fields already available to the page, group identifier text for readability, and show a copy control for suitable identifiers. These are presentation affordances: they do not change the stored value, make a calculated result authoritative, or grant access to a hidden field. Auto-selected hero values are a fallback, so configure explicit identity fields when service policy requires a predictable heading.

Roll out one entity at a time. Compare Standard and Refined with an intake role and a restricted reviewer, check tab overflow and the section rail on smaller screens, and confirm that related records and activity remain permission-filtered.

## A field-design review before publishing

1. Create one non-production record for each normal and exceptional path.
2. Confirm required fields prevent an incomplete decision without blocking legitimate drafts.
3. Check list filters, search, exports, dashboards, and documents using the fields that need to support them.
4. Verify that a restricted role cannot view or edit sensitive files, people, payroll, or decision data.
5. Ask a person who did not build the app to enter a record from the field labels alone. Revise any field that needs explanation from the builder.

## Next steps

* Learn how to create and relate records in [Entities](/build/entities).
* Configure durable references in [Serial IDs](/build/serial-ids).
* Build and test derived values in [Calculated fields](/build/calculated-fields).
* Use [Expressions in the builder](/build/expressions-in-builder) for calculated values and conditional rules.
* Build a clear capture experience in [Forms](/build/forms).

![KayanOS entity field and layout configuration](https://kayanos.app/docs-images/en/build/entity-fields-and-layouts.png)