Public form question types

A Form is bound to one database. Its field configurations refer to database field keys; the database schema remains the authority for each kind, option list, requiredness, and record validation. A public submission goes through the normal Database record-create path after Form-specific validation.

The current contract contains 13 public-collectable kinds. The canonical list is generated so a new kind cannot be added silently.

Canonical contract values:

• text
• long_text
• number
• rating
• date
• select
• multi_select
• status
• checkbox
• url
• email
• phone
• relation

Question kinds

Short text text

A single-line text answer, trimmed before storage. It supports placeholder, requiredness, help text, case-sensitive regex validation, minimum and maximum length, custom tooltip, and custom error message. An empty answer is omitted so the database can enforce requiredness and defaults.

Long text long_text

A multi-line text answer with the same length, pattern, message, placeholder, and required settings as Short text. It stores one trimmed string; it is not a Page rich-text block.

Number number

A finite numeric answer. Display can be a normal input, a stepper with − and + buttons, slider, numbered scale, stars, or hearts. Input and stepper show the field’s own unit — its currency symbol on the side the locale puts it, or a percent sign — unless the question sets its own prefix or suffix (“kg”, “people”). Slider and scale use minimum, maximum, and step; scales may label endpoints, with one-click presets for NPS (0–10) and 1–5 agreement; stars and hearts can set a symbol count. Validation can separately enforce numeric minimum and maximum. The server parses the answer with the field’s own format, so a duration field reads 1:30 as ninety minutes, and rejects anything that is not a number instead of dropping it.

Rating rating

A row of icons bound to a Rating field: the responder clicks one to answer, or clicks it again to take the answer back. The scale (1 to 10) and icon come from the field, not the form. The server accepts a whole number from 0 to the field’s maximum, or text such as 4 or 4/5; an empty answer is omitted, and a fraction or a value above the maximum is rejected.

Date date

A date answer. Display can be a date, a date and time, a date range, or a time range (start and end each with a time). A range is stored in the same field as { start, end }, the shape every date field already holds, and the server rejects a range that ends before it starts; a required range needs both ends. The public endpoint accepts a date or date-time string, a start/end interval string, or a { start, end } object. Date-times are local wall-clock times, as everywhere else in the app.

Select select

One option key from the database field. It can render as dropdown, a list of options, or buttons. Options are sorted by database option order and carry their names and colours to the public renderer. The Database kernel rejects a key that is not an allowed option.

Multi-select multi_select

Several database option keys, shown as a checkbox list or as chips. The public endpoint accepts an array or a comma-separated string, trims each value, and omits an empty list. Option membership is still checked by the Database kernel.

Status status

One lifecycle option key. Like Select, it can render as dropdown, radio, or buttons and uses the database’s ordered, coloured options. It stores one key; the field’s option order and completion semantics remain part of the Status field rather than the Form.

Checkbox checkbox

A boolean answer, shown as a checkbox, a switch, or Yes / No buttons. A checkbox or switch reads as consent (“I agree to the terms” — the question’s placeholder is the text beside it): a required one must be ticked. Yes / No asks a real question, where No is an answer. The public endpoint accepts a boolean or the case-insensitive strings true, yes, on, and 1; other strings are false.

URL url

A URL-oriented single-line input stored as a trimmed string. Requiredness and the underlying Database URL validation apply. Form regex and length rules can add stricter project-specific checks, but the Form does not fetch the URL.

Email email

An email-oriented input stored as a trimmed string and checked by the Database field rules. It can also use Form length and regex rules. Passing validation does not prove the mailbox exists.

Phone phone

A phone-oriented input stored as a trimmed string. Formatting is preserved as accepted by the Database Phone field; the Form contract does not resolve a country or promise deliverability.

Relation relation

Links the new record to records in the database the field points at. The public form shows a searchable dropdown of that database’s records (at most 200), single or multiple as the field allows, and the answer is the chosen record ids. A submission may only link records the form offered, so a public responder cannot reference arbitrary internal records.

Fields public Forms do not collect

User, File, Place, and JSON are writable database kinds but are excluded from unauthenticated collection because their IDs or payloads could expose internal resources or accept unsafe references. Computed, system, Button, and Time-tracking kinds are not writable answers. If a schema-required field is not public-collectable, the Form cannot safely publish a valid submission path.

The synthetic record-title question uses key __record_title__. It is not a database field kind and is hidden until explicitly enabled.

Field configuration

Each question can override its label and icon, visibility, requiredness, help text, placeholder, display, validation, step number, and order. A schema-required field is always visible. The synthetic title is opt-in. Every other database field defaults to visible even when it was added after the Form was last saved; hide new internal fields explicitly.

A question the Form marks required must be answered on a public submission even when its database field is optional; the kernel checks this before creating the record, and the record-create path still enforces the schema’s own required fields. Form validation is checked in the client for immediate feedback, with each failing question marked in place, and repeated in the kernel for public submissions. Text answers are capped at 10,000 characters (50,000 for long text). Invalid regular-expression patterns are ignored rather than blocking every response, so test a custom pattern before publishing.

A public link can prefill answers: add a question’s field key, or its label in lower case with underscores (?budget=5000&how_did_you_hear=Online%20ads). Choices take an option name or key; parameters that match nothing are ignored.

Form flow and publishing

With no steps, all questions share one implicit step. Otherwise each Form step has an ID, optional title, and description, and question step values assign them by array position. Themes support traditional or conversational flow, card or plain frame, background colour/gradient/image, radius, colour scheme, and scoped text, input, accent, and button colours.

Builder edits can live in draft; public and in-app respondents read only the published top-level content. Public config needs enabled and an optional normalised slug. A public response receives no draft fields or internal uncollectable fields from the resolver.