Form schema JSON

FormTemplate.schema, DefaultFormTemplate.schema, FormResponse.schemaSnapshot and FormAssignment.signSchema all hold the same document, FormSchemaV2. FormResponse.answers holds the trainee’s answers keyed by field key.

Where the contract lives

A field type is defined in four places. Change them together.

Repo	File	Role
Backend	`apps/core-api/src/modules/forms/form-schema.ts`	`FORM_FIELD_TYPES`, the types, `normalizeFormSchema`, `validateAnswers`, `stripHiddenAnswers`.
Backend	`apps/core-api/src/modules/forms/form-conditions.ts`	The conditions engine.
Frontend	`apps/saas/modules/shared/lib/form-schema.ts` and `form-conditions.ts`	The builder’s mirror, plus `makeField()` defaults.
Frontend	`apps/saas/app/(authenticated)/(main)/(organizations)/[organizationSlug]/forms/builder/field-defs.ts`	`FIELD_DEFS`: palette icon, group and the `hidden` flag.
Frontend	`apps/saas/modules/shared/lib/form-answers.ts`	`formatFieldAnswer`, the one place coach-side answer rendering lives.
Mobile	`src/features/forms/data/types.ts`, `lib/conditions.ts`, `lib/validate.ts` and the field renderer	The trainee-side control, conditions and validation.

The conditions engine exists three times: backend form-conditions.ts, frontend form-conditions.ts, and mobile lib/conditions.ts. They must agree, because the app decides what to show and the backend decides which answers to keep.

Shape

{
  "schemaVersion": 2,
  "fields": [
    {
      "id": "f_abc123",
      "type": "weight",
      "key": "weight",
      "label": "Weight (kg)",
      "placeholder": "",
      "helpText": "",
      "required": true,
      "order": 0,
      "page": 0,
      "saveToClient": true,
      "validation": { "min": 30, "max": 250, "unit": "kg" }
    },
    {
      "id": "f_def456",
      "type": "dropdown",
      "key": "injuries",
      "label": "Any injuries?",
      "required": false,
      "order": 1,
      "page": 0,
      "options": [
        { "value": "none", "label": "None" },
        { "value": "knee", "label": "Knee" }
      ],
      "config": { "multiple": true }
    },
    {
      "id": "f_ghi789",
      "type": "text",
      "key": "injury_details",
      "label": "Tell us more",
      "required": false,
      "order": 2,
      "page": 0,
      "validation": { "multiline": true, "maxLength": 500 },
      "condition": { "enabled": true, "sourceFieldId": "f_def456", "operator": "ne", "value": "none" }
    }
  ],
  "settings": {
    "rtl": true,
    "displayName": "Weekly check-in",
    "submitLabel": "Send",
    "pages": [{ "id": "p1", "title": "Body", "ctaLabel": "Next" }],
    "thankYou": { "richText": [{ "text": "Got it. I will review it soon." }] }
  }
}

normalizeFormSchema(raw) always returns schemaVersion: 2. Every read and write path calls it, so older stored forms heal themselves.

`fields[]`

Key	Type	Notes
`id`	string	Stable identity. Conditions reference it through `sourceFieldId`.
`type`	field type	See the table below.
`key`	string	The key in the answers object. For documents to sign it must match `SIGNING_KEY_PATTERN`.
`label`	string	A stored label that looks like a translation key (`common.` or `formBuilder.` prefix) is replaced by the Hebrew default on read by `uiText`.
`placeholder`, `helpText`	string	Optional.
`required`	boolean
`defaultValue`	any	Optional.
`order`	number	Position within the page.
`page`	number	Zero-based page index. Clamped to the last page on normalize.
`saveToClient`	boolean	Write the answer to the trainee’s profile or metrics. Only honoured for types in `CLIENT_SAVE_TYPES`.
`validation`	object	`minLength`, `maxLength`, `pattern`, `multiline`, `min`, `max`, `unit`.
`options`	array of `{ value, label }`	For `dropdown` and `goal`.
`link`	`{ label, url }`	For `checkbox_confirmation`: the document the trainee confirms.
`content`	object	For display blocks and confirmations: `title`, `preview`, `body`, `richText`, `background`, `fromLine`, `mediaUrl`, `mediaKind` (`image` or `video`).
`config`	object	Per-type parameters. See below.
`condition`	object	Visibility rule. See Conditions.
`visibleIf`	`{ fieldKey, equals }`	Legacy visibility rule. Migrated to `condition` on normalize.
`placement`	`{ page, x, y, w, h }`	Documents to sign only. Where the field sits on the PDF.
`filledBy`	`coach` or `trainee`	Documents to sign only. Absent means `trainee`.

`config`

One bag for all per-type parameters:

Key	Used by	Meaning
`accept`	uploads	Accepted file types.
`maxSizeMb`	uploads	Size limit.
`multiple`	`dropdown`	Accept more than one option. The answer becomes a string array.
`stars`	`rating`	Number of stars, 2 to 10, default 5.
`minLabel`, `maxLabel`	`rating`	Captions under the first and last star.
`pose`	`image_upload`	`FRONT`, `SIDE` or `BACK`. Copied onto the `ClientPhoto` created on submit.
`measurement`	`body_measurement`	Which circumference: `chest`, `waist`, `hips`, `arm`, `thigh`. Default `waist`.
`hiddenCategoryIds`	`food_preferences`	Food categories the coach hid from the field.

Field types

FORM_FIELD_TYPES has 25 entries.

Type	Answer value	Notes
`text`	string	`validation.multiline` makes it a long answer.
`number`	number	Decimal keypad on mobile. `validation.min` and `max` apply.
`phone`	string	Must normalize through `normalizeFormPhone`: Israeli local, `972` prefix, or `+` international with 7 to 15 digits.
`israeli_id`	string	Checked with the national id checksum in `isValidIsraeliId`.
`email`	string
`age`	number	Retired from the palette (`hidden: true`) but still valid in existing forms.
`height`	number	Saves to `Client.heightCm`.
`weight`	number	Saves a `WeightEntry`.
`body_measurement`	number	Merges into `DailyMetric.measurements` under `config.measurement`.
`goal`	option value	Options default to `DEFAULT_GOAL_OPTIONS`. Saves the option’s label to `Client.goal`.
`gender`	`male` or `female`
`date`	date string
`birth_date`	date string	Saves to `Client.birthDate`.
`dropdown`	option value, or string array with `config.multiple`	Every value must be one of `options[].value`.
`checkbox_confirmation`	`true`	A required confirmation needs exactly `true`. The sentence the trainee confirms is in `content.body`.
`rating`	integer from 1 to `config.stars`
`range`	number	A slider between `validation.min` and `max`, defaults 0 and 10.
`image_upload`	URL string	Can save a `ClientPhoto`.
`video_upload`	URL string
`food_preferences`	`{ excludedCategoryIds, excludedFoodIds, includedExceptionIds }`	Stores ids, never names. Never counts as blank: “nothing excluded” is a legitimate answer. Any shape is accepted and normalized.
`signature`	image URL after signing	Documents to sign. Hidden from the regular palette.
`read_more`	none	Display only. Retired from the palette.
`coach_message`	none	Display only.
`text_block`	none	Display only. Uses `content.richText`.
`media_block`	none	Display only. Uses `content.mediaUrl` and `content.mediaKind`.

DISPLAY_ONLY_TYPES is read_more, coach_message, text_block, media_block. They never produce answers and are skipped by validation. CLIENT_SAVE_TYPES is age, height, birth_date, weight, body_measurement, goal, image_upload, israeli_id, phone, email. Retiring a field type means setting hidden: true in FIELD_DEFS. The type stays in FORM_FIELD_TYPES so existing forms that use it keep working.

Rich text

content.richText and settings.thankYou.richText are arrays of spans:

[{ "text": "Welcome", "bold": true, "size": "lg", "align": "center", "color": "#111111" }]

size is sm, md or lg. align is start, center or end. bold, italic and underline are optional booleans.

`settings`

Key	Type	Notes
`rtl`	boolean	Required.
`pages`	array of `{ id, title?, ctaLabel?, condition? }`	One entry per page. The normalizer creates enough pages to hold every field. A page can carry its own condition.
`displayName`	string	Trainee-facing form name.
`submitLabel`	string	Label of the final button.
`successMessage`	string
`thankYou`	`{ richText }`	The thank-you screen.
`document`	object	Documents to sign only. See below.

Send cadence is not in the schema. It lives in the FormTemplate columns cadence, sendWeekday and sendDayOfMonth.

Conditions

A field or a page can be shown only when another field’s answer matches a rule.

{ "enabled": true, "sourceFieldId": "f_def456", "operator": "between", "value": "2026-01-01", "value2": "2026-12-31" }

A condition has exactly one rule. There is no AND or OR. A field is answerable when its own condition passes and its page’s condition passes (isFieldAnswerable).

Operators by source type

The operators offered depend on the kind of the source field:

Source kind	Field types	Operators
numeric	`number`, `age`, `weight`, `body_measurement`, `height`, `range`, `rating`	`eq`, `ne`, `gt`, `lt`, `empty`, `filled`
date	`date`, `birth_date`	`on`, `after`, `before`, `between`, `age_gt`, `age_lt`, `age_eq`, `empty`, `filled`
choice	`dropdown`, `gender`, `goal`	`eq`, `ne`, `empty`, `filled`
boolean	`checkbox_confirmation`	`checked`, `unchecked`
presence	`text`, `email`, `phone`, `israeli_id`, `image_upload`, `video_upload`	`empty`, `filled`

Types not in this table cannot be a condition source: food_preferences, signature and the display blocks.

Evaluation rules

empty and filled look only at whether there is an answer. An empty array counts as empty.
checked means the answer is exactly true. unchecked means anything else.
For every other operator an empty answer makes the condition false.
Choice comparisons are string comparisons. For a multi-select the rule matches when any picked value equals the target.
Dates are compared as whole days. ISO dates and day-first dd/mm/yyyy are both parsed.
The age_* operators compute the age in whole years from a date answer.
between is inclusive and accepts the two bounds in either order.

It fails open

isConditionMet returns true, meaning “show it”, whenever the condition cannot be evaluated: it is disabled, has no source, the source field was deleted, the source is not a valid condition source, or the operator does not belong to that source type. A broken rule never hides content permanently. normalizeFormSchema also runs reconcileCondition on every field and page and removes conditions that can no longer be satisfied structurally.

Hidden answers are dropped

stripHiddenAnswers(schema, answers) runs on submit. Answers for display-only fields and for fields that are not answerable under the submitted answers never reach storage. validateAnswers skips the same fields, so a required field hidden by a condition does not block submission.

`FormResponse.answers`

A flat object keyed by field key:

{
  "weight": 78.4,
  "injuries": ["knee"],
  "injury_details": "Old meniscus tear, fine with squats",
  "terms": true,
  "food": { "excludedCategoryIds": ["dairy"], "excludedFoodIds": [], "includedExceptionIds": [] }
}

validateAnswers returns a list of { key, message } errors. Messages are in Hebrew because they are shown to the trainee. Always render a response with schemaSnapshot ?? formTemplate.schema. The form may have been edited since the trainee answered it.

Documents to sign

A PDF_SIGNATURE form uses the same schema with three additions.

`settings.document`

{
  "url": "https://CDN_HOST/path/contract.pdf",
  "pageCount": 2,
  "pages": [{ "width": 595, "height": 842 }, { "width": 595, "height": 842 }],
  "fileName": "contract.pdf",
  "sizeBytes": 184211
}

Page sizes are in PDF points with rotation applied. Limits: DOCUMENT_MAX_PAGES is 200 and DOCUMENT_MAX_PAGE_POINTS is 14400.

`fields[].placement`

{ "page": 0, "x": 0.12, "y": 0.78, "w": 0.3, "h": 0.06 }

page is the zero-based PDF page. x, y, w and h are fractions of that page as pdf.js displays it, measured from the top-left corner. The minimum size is PLACEMENT_MIN_SIZE, 0.01. A placement on a page past the end is clamped to the last page.

`fields[].filledBy`

coach fields are filled when the form is sent. Their values are stored on FormAssignment.prefill as an object of key to string, each up to SIGNING_TEXT_MAX_LENGTH (500) characters, with blanks dropped. validateFieldValues in forms/signing.ts checks them: only coach field keys are accepted and every required one must be present. Signature fields are always the trainee’s. Field keys on a signing form must match SIGNING_KEY_PATTERN: a lowercase letter followed by up to 39 lowercase letters, digits or underscores. enforceSigningKeys applies this during normalization. The signed PDF and its audit trail are stored on the response. See Form models.

​Where the contract lives

​Shape

​fields[]

​config

​Field types

​Rich text

​settings

​Conditions

​Operators by source type

​Evaluation rules

​It fails open

​Hidden answers are dropped

​FormResponse.answers

​Documents to sign

​settings.document

​fields[].placement

​fields[].filledBy