Skip to Content
Baseera Docs

Fields and checks

Declare a record's fields and your own checks: field kinds, labels in Arabic and English, severities, when checks run, acknowledging, and what is sent to the model.

A record is a set of fields plus the checks that judge them. You declare both in useBaseeraImmersive. Baseera never reads your DOM or your database: it sees only what your get functions return and what your checks report.

useBaseeraImmersive({
  entity: { type: "invoice", ref: invoice.id, title: `Invoice ${invoice.number}` },
  fields: [
    { name: "customer", label: { ar: "العميل", en: "Customer" }, kind: "text", get: () => form.customer },
    { name: "total", label: { ar: "الإجمالي", en: "Total" }, kind: "number", get: () => form.total },
  ],
  checks: [
    {
      id: "total-mismatch",
      severity: "blocking",
      fields: ["total"],
      run: (r) => (Number(r.total) === linesSum(form.lines) ? { ok: true } : { ok: false, message: "The total does not match the lines." }),
    },
  ],
  finish: { label: "Send invoice", action: ({ receipt }) => sendInvoice(invoice.id, receipt) },
});

The entity

entity names the record: type (up to 100 characters), ref (up to 200) and an optional title. The pair type and ref identifies the record everywhere: in the receipt, in the trail, in the dashboard and in server signals. Use your own stable ids.

A different type or ref on the same component starts over as a new record. Only one record is in immersive mode at a time. A second useBaseeraImmersive, nested or mounted later, replaces the first, with a warning in development.

Fields

Prop

Type

KindUse forValue
textNames, ids, free text, summariesA string
numberAmounts, quantitiesA number or a numeric string
dateDatesAn ISO date such as 2026-10-01
selectA choice from a listThe chosen value

Values can be any JSON. A value that cannot be serialized is treated as unchanged and sent as null.

Labels in Arabic and English

Pass { ar, en } and the review panel picks the one that matches its locale. A plain string is used in both. Write the Arabic label as a person would say it, not as a translation of the field name.

Fields that are not inputs

A field does not have to be an input. Line items are a common case: send a one-line summary as the field, and let the checks read the real lines from your state.

{ name: "lines", label: { ar: "البنود", en: "Line items" }, kind: "text",
  get: () => form.lines.map((l) => `${l.description} ${l.qty} x ${l.unitPrice}`).join("; ") },

The record passed to run

Every check receives record, an object of { [name]: get() }, read at the moment the check runs. The second argument carries signals (see Signals).

run: (record, { signals }) => { /* ... */ }

run is synchronous. For a check that needs your server, compute the answer in your own state first (a loaded customer, a lookup result) and read it in the closure. Fresh closures on every render are fine: nothing restarts.

Severities

SeverityMeaningHolds the Finish button
blockingThe record should not be finished like this.Yes. The person can override with a reason.
warningProbably wrong, worth a look.Only if you set blockOnWarnings.
infoA note.No.

A check returns { ok: true } or { ok: false, message, fix? }. Write the message for the person: what is wrong, in their language. It is shown on the field and sent to the model.

If run throws, the check counts as failed with the message "This check could not run." A blocking check that throws keeps the finish disabled, and the override is unavailable until the check runs. A check that cannot run is unknown, not passing.

When checks run

  • When immersive mode starts.
  • 250 ms after a field's value changes. Values are compared as JSON on each render, so a burst of typing runs the checks once.
  • At once when you send a signal.
  • After recheck(), on the same 250 ms delay.

Call recheck() after anything that changes a result but is not a field: a lookup that finished, a toggle outside the form.

const { recheck } = useBaseeraImmersiveState();
useEffect(() => recheck(), [customer, recheck]);

A check that turns passing stays in results with the status resolved for 3 seconds, so the person sees it clear, and then drops.

Acknowledge

acknowledge(id) hides a warning or an info for this record until its result changes: the same check id with a different message shows again. In the review panel this is the Got it button.

  • Blocking checks cannot be acknowledged. The call is ignored, with a warning in development.
  • An acknowledged check still counts as failing for the model (ok: false on the wire), so the model knows it was dismissed rather than fixed.
  • An acknowledged warning no longer holds a finish when blockOnWarnings is on.
  • Each acknowledgement is written to the trail.

What is sent to the model

On every chat turn while a record is open, the SDK sends the entity, each field's name, label, kind and value, and each check's id, severity, pass or fail, message and fields. The runtime puts them in the system prompt as data from your app, never as instructions, and adds a platform rule telling the model to treat the checks as the source of truth.

LimitValueWhen over
Fields50The request is refused with invalid_request.
Checks100The request is refused with invalid_request.
One field value2 KB serializedThe SDK cuts it and ends it with …[truncated].
The whole immersive object16 KBThe SDK drops field values first, then passing checks.

The check function itself, and a check's fix, are not sent. Only results are.

Everything sent goes to the model provider you chose. Do not declare fields that hold secrets, and keep values to what the checks and the model need.

Next steps

On this page