Form data schema

Every entry stores what people filled in under data. The form decides its shape: which keys exist, where they nest, which values each key takes and when a key is required. This page shows how to read that shape from the form, which value each kind of field stores, and how to generate a schema of your form that your code can check against.

To read a form's definition, see Forms.

From form to data

formSchema.rootElem in GET /form/{formId} is a tree of elements. Every element has a type and a name. The first letter of the type tells you what it is:

• c… is a container that groups other elements, such as a section (cSection), a repeating group (cRepeat), a row of columns (cRow) or tabs (cTabs). Its elements are in children.
• f… is a field that holds a value, such as a text input (fInput), a date (fDate) or a file upload (fFile).
• e… is content, such as text, a button or a calculation. It stores nothing in data.

The form definition leaves out every property that has its default value. A section without secFlat, for example, is a flat section.

Data paths

Each field's value sits at a path built from the name of the field and of some of the containers around it. The same paths apply when you prefill a form:

• A field adds its name to the path.
• A section (cSection) adds nothing, unless it has "secFlat": false. Then it adds its name, and its fields sit in a nested object.
• A repeating group (cRepeat) adds its name and holds an array, one object per row. It takes at most 10 rows unless it sets repMaxRows. A row with no values is stored as null.
• Rows (cRow) and tabs (cTabs) add nothing to the path of the fields inside them.
• Tabs keep their own state under their name: { "__activeTab": 1 } is the tab the person had open. A collapsible section ("secCollapse": true) can keep { "__isCollapsed": true } under its own name in the same way, even when it's flat. Keys that start with __ are the form's screen state, not data. Ignore them when you read an entry.

Take this form, shown with only the properties that matter for paths:

{
  "type": "cSection",
  "name": "root",
  "children": [
    { "type": "fInput", "name": "fullName" },
    { "type": "cSection", "name": "address", "secFlat": false, "children": [
      { "type": "fInput", "name": "city" },
      { "type": "fInput", "name": "street" }
    ] },
    { "type": "cTabs", "name": "steps", "tabsStyle": "wizard", "children": [
      [ { "type": "cRepeat", "name": "references", "children": [
        { "type": "fInput", "name": "name" },
        { "type": "fInput", "name": "phone" }
      ] } ],
      [ { "type": "fFile", "name": "cv" }, { "type": "fSign", "name": "signature" } ]
    ] }
  ]
}

A submitted entry of this form holds:

{
  "fullName": "Dana Levi",
  "address": {
    "city": "Haifa",
    "street": "Herzl 10"
  },
  "steps": { "__activeTab": 1 },
  "references": [
    { "name": "Yossi Cohen", "phone": "050-0000000" },
    { "name": "Rina Katz", "phone": "052-0000000" }
  ],
  "cv": [
    {
      "name": "cv.png",
      "size": 70,
      "type": "image/png",
      "s3Key": "form/<formId>/<uuid>/cv.png",
      "s3Bucket": "<bucket>",
      "url": "https://<bucket>.s3.eu-west-1.amazonaws.com/form/<formId>/<uuid>/cv.png?<presigned-query>"
    }
  ]
}

• address is an object, because its section has "secFlat": false.
• references is an array, one object per row.
• The tabs add nothing to the paths of references and cv. Their own key, steps, holds only the open tab.
• signature is missing because nobody signed. A field with no value is absent from data.

The form builder shows the same paths. In the builder, press Alt+Shift+D to show each field's data path and data type under it.

Field types

Send each value in the shape the field stores, and expect the same shape when you read an entry. Every field type the form builder offers:

A value of the wrong type, such as a date with an offset or a string sent to a checkboxes field, fails with 400 entry_failed_validation and the message Invalid data type., on a draft save as well as on a submit.

A text input (fInput), radio buttons (fRadio) and a select (fSelect) can set another data type with typeValidator: "num", "date", "bool", "color" or "sign". Then the value takes the shape of that type in the table, as the number field above does.

Content elements (e…) store nothing, and that includes calculations (eEq). Some forms fill values in the browser, for example a total calculated from other fields or a default value. The API doesn't run those calculations. When you create an entry through the API, send every value you need, including the ones the browser would calculate.

Options

A select (fSelect), radio buttons (fRadio), checkboxes (fCheckbox) and a matrix (fMatrix) take their values from options. The form definition holds them in one of three ways.

A list of options. Each option is a pair of value and label, [value, label]. The value is what data stores and what you send. The label is what people see. In this field, the value to send is "dev", not "Developer":

{
  "type": "fSelect",
  "name": "position",
  "label": "Position",
  "options": [["dev", "Developer"], ["qa", "QA engineer"]]
}

An option given as a single value, such as "morning", uses the same text as value and label. Options can also be grouped: { "label": "Classic", "options": [["red", "Red card"], …] }. A group only changes how the list looks. Its options' values are stored the same way.

An expression. options is a string, an expression the form evaluates for each entry, such as "model.items.length > 3 ? [['l', 'Large']] : [['s', 'Small'], ['l', 'Large']]". It returns a list in the format above. The allowed values depend on the entry's other values.

An options set. options is an object with the url of an options set's autocomplete endpoint. The field offers the set's options as the person types. See Options sets.

When an entry is submitted, the API checks the value of a field with a list of options, or with an expression, against the options, and fails with not in options when it isn't one of them. A field whose options come from an options set accepts any value, unless the field also has a remote validator that checks the value against the set.

To read a field's allowed values, read the form and take options from the field. The script in Get a schema for your form lists them for every field.

Required and conditional fields

A field is required when it has reqValidator. The form definition shows it in one of three forms:

An object with "level": "warning", "info" or "success" only shows its message in the form. It doesn't block a submit.

A required field fails when its value is empty, as defined in Field types. A matrix also fails when any of its questions has no answer. A required yes/no field accepts false, so it doesn't make the person agree to anything: check for true on your side. A required field inside a repeating group is required in every row, and the error names the row, for example model['items'][0]['product'].

A field, section or tab can also have relevant: false, or an expression such as "model.contactBy === 'phone'". While it's false, the form hides the element. When the entry is saved, every value inside it is dropped from data, and its required rule doesn't apply.

What this means when you write an entry through the API:

• Submitting checks every rule of the form. A missing required value, or a value that isn't one of the options, fails with 400 entry_failed_validation. Saving a draft checks only the value types, unless the form sets formSchema.validateSaved.
• A value you send for a hidden field is dropped. The request succeeds with 200, and the key is missing from the stored entry.
• A key the form doesn't declare is dropped in the same way.

This form asks for a phone number only when the person wants to be called. The request sends a phone number, but contactBy is email, and also sends an employeeNumber the form doesn't have:

curl -X POST https://api.tepez.co.il/v1.0/entry/submit \
  -H "x-api-key: $TEPEZ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "form": "<formId>",
    "data": {
      "fullName": "Dana Levi",
      "position": "dev",
      "agreeToTerms": true,
      "contactBy": "email",
      "phone": "050-0000000",
      "employeeNumber": "12345"
    }
  }'

The request succeeds, and the stored entry has neither phone nor employeeNumber. The response, trimmed to the entry's data:

{
  "entry": {
    "id": "<entryId>",
    "status": "submitted",
    "data": {
      "fullName": "Dana Levi",
      "position": "dev",
      "contactBy": "email",
      "agreeToTerms": true
    }
  }
}

With "contactBy": "phone" and no phone, the same request fails:

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "The entry failed validation on the server. Sorry, this is probably a BUG on our side. If the issue persists please contact us at support@tepez.co.il",
  "id": "entry_failed_validation",
  "messages": [
    {
      "modelPath": "model['phone']",
      "message": "You can't leave this empty.",
      "type": "error",
      "value": null
    }
  ]
}

Read the entry back and check that every value you sent is there.

Get a schema for your form

In the form builder

The form builder's ⋮ menu, at the top of the builder, downloads two files that describe the form:

• Fields report (דוח שדות): an Excel file. Its Fields sheet has a row for every field, with its display name, its path (such as model.address.city), its data type, where its options come from and whether it's required. A repeating group's fields appear once for each row it can hold, references[0], references[1] and so on. The Options sheet lists the label and value of every option. Other sheets list the PDF fields, the expressions and the texts of the form.
• TypeScript types definition file (קובץ TypeScript types definition): a .d.ts file with one TypeScript interface for the data of the form and one for each nested section and repeating group. A field with a list of options is typed as the union of its option values, with their labels in a comment.

Both files describe the form as it is in the builder when you download them. Two things in the TypeScript file differ from the JSON you read: a date is typed Date, while data holds an ISO string, and every key is typed as present, while a field with no value is absent.

From the API

This script reads a form and prints a JSON array that describes every field: its data path, type, data type, whether it's required, the conditions that hide it and its options. It follows the rules in Data paths and Options:

const res = await fetch('https://api.tepez.co.il/v1.0/form/<formId>', {
  headers: { 'x-api-key': process.env.TEPEZ_API_KEY },
});
const form = await res.json();

// The data type of each field type that doesn't set its own typeValidator
const defaultDataTypes = {
  fCheckbox: 'array', fBool: 'bool', fDate: 'date', fFile: 'file',
  fSign: 'sign', fRate: 'num', fColor: 'color', fMatrix: 'matrix',
};

// Static options become { value, label }; other sources are described, not listed
function toOptions(options) {
  if (typeof options === 'string') return { expression: options };
  if (!Array.isArray(options)) return { remote: options.url };
  return options.flatMap((opt) => {
    if (opt.options) return toOptions(opt.options).map((o) => ({ ...o, group: opt.label }));
    const [value, label = value] = Array.isArray(opt) ? opt : [opt];
    return [{ value, label }];
  });
}

// Walk the element tree and describe every field
function describe(elem, prefix = '', conditions = []) {
  const { type, name } = elem;
  if ('relevant' in elem) conditions = [...conditions, elem.relevant];
  if (type.startsWith('f')) {
    const tv = elem.typeValidator;
    const req = elem.reqValidator;
    const field = {
      path: `${prefix}${name}`,
      type,
      dataType: (typeof tv === 'string' ? tv : tv?.type) ?? defaultDataTypes[type] ?? 'str',
      required: typeof req === 'object' ? (req.req ?? true) : (req ?? false),
    };
    if (conditions.length) field.relevant = conditions;
    if (elem.options) field.options = toOptions(elem.options);
    if (elem.matrixQuestions) field.questions = elem.matrixQuestions.map((q) => [q].flat()[0]);
    return [field];
  }
  if (!type.startsWith('c')) return []; // content elements (e*) hold no data
  let childPrefix = prefix;
  if (type === 'cSection' && elem.secFlat === false) childPrefix = `${prefix}${name}.`;
  if (type === 'cRepeat') childPrefix = `${prefix}${name}[].`;
  // cRow and cTabs hold one array of children per column or tab
  return (elem.children ?? []).flatMap((child, i) => {
    const tab = type === 'cTabs' ? elem.tabs?.[i] : undefined;
    const childConditions = tab && 'relevant' in tab ? [...conditions, tab.relevant] : conditions;
    return [child].flat().flatMap((c) => describe(c, childPrefix, childConditions));
  });
}

console.log(JSON.stringify(describe(form.formSchema.rootElem), null, 2));

For a job application form, it prints (trimmed to some of the fields):

[
  {
    "path": "fullName",
    "type": "fInput",
    "dataType": "str",
    "required": true
  },
  {
    "path": "yearsOfExperience",
    "type": "fInput",
    "dataType": "num",
    "required": false
  },
  {
    "path": "position",
    "type": "fSelect",
    "dataType": "str",
    "required": true,
    "options": [
      { "value": "dev", "label": "Developer" },
      { "value": "qa", "label": "QA engineer" }
    ]
  },
  {
    "path": "languages",
    "type": "fSelect",
    "dataType": "array",
    "required": false,
    "options": [
      { "value": "he", "label": "Hebrew" },
      { "value": "en", "label": "English" }
    ]
  },
  {
    "path": "phone",
    "type": "fInput",
    "dataType": "str",
    "required": true,
    "relevant": ["model.contactBy === 'phone'"]
  },
  {
    "path": "address.city",
    "type": "fInput",
    "dataType": "str",
    "required": false
  },
  {
    "path": "references[].name",
    "type": "fInput",
    "dataType": "str",
    "required": false
  },
  {
    "path": "cv",
    "type": "fFile",
    "dataType": "file",
    "required": false
  }
]

For an order form, with its feedback fields on a tab shown only after the person adds an item, it prints entries such as:

[
  {
    "path": "items[].product",
    "type": "fInput",
    "dataType": "str",
    "required": true
  },
  {
    "path": "city",
    "type": "fSelect",
    "dataType": "str",
    "required": false,
    "options": {
      "remote": "https://api.tepez.co.il/v1.0/optionsSet/572078298b59b1ba2ebcd824/autocomplete"
    }
  },
  {
    "path": "giftCard",
    "type": "fSelect",
    "dataType": "str",
    "required": false,
    "options": [
      { "value": "red", "label": "Red card", "group": "Classic" },
      { "value": "blue", "label": "Blue card", "group": "Classic" },
      { "value": "winter", "label": "Winter card", "group": "Seasonal" }
    ]
  },
  {
    "path": "satisfaction",
    "type": "fMatrix",
    "dataType": "matrix",
    "required": false,
    "relevant": ["model.items.length > 0"],
    "options": [
      { "value": "1", "label": "Bad" },
      { "value": "2", "label": "OK" },
      { "value": "3", "label": "Good" }
    ],
    "questions": ["speed", "quality"]
  },
  {
    "path": "email",
    "type": "fInput",
    "dataType": "str",
    "required": "model.rating < 3",
    "relevant": ["model.items.length > 0"]
  }
]

An expression in required or relevant uses the form's own syntax: model is the entry's data. Treat these as hints for a person reading the schema rather than code to run.

Keep in sync

The schema changes when someone edits the form. A form's modifyTime is the last time someone changed the form itself. changedAt also moves when people fill the form, so it changes far more often. Store the modifyTime of each form you use, and generate its schema again when it moves.

GET /form with fields reads the modifyTime of all your forms in one request:

curl -G https://api.tepez.co.il/v1.0/form \
  -H "x-api-key: $TEPEZ_API_KEY" \
  --data-urlencode 'fields=["id","name","modifyTime"]' \
  --data-urlencode 'limit=100'

{
  "data": [
    { "id": "<formId>", "name": "Job application", "modifyTime": "2026-10-01T10:17:19.185Z" },
    { "id": "<formId2>", "name": "Order feedback", "modifyTime": "2026-10-01T10:25:02.446Z" }
  ]
}

modifyTime also moves when someone changes other parts of the form, such as its emails. Compare the new schema with the one you stored, and act only on a real difference: a new required field, a removed field, or a changed list of options.

Troubleshooting

The error message of entry_failed_validation says the problem is probably a bug on our side. For an API call, it almost always means the data you sent broke a rule of the form: read the messages array, as Errors explains. Every response carries an x-tepez-request-id header. Quote it when you contact us.