Types and Empty Values
What type does a field need, and what happens when its value is missing? A type describes a value and its available operations. An empty value has a known type. If a node’s output is unresolved, downstream expressions do not yet have a usable contract.
| Type | Invoice example | Meaning |
|---|---|---|
text |
"INV-104" |
Text, including identifiers. |
number |
120 |
A numeric amount. |
boolean |
false |
A yes/no review decision. |
date |
"2026-09-07T14:00:00Z" |
Date/time; ISO text carries it across JSON. |
file |
Uploaded invoice PDF | Metadata: fileName, mimeType, sizeBytes, url. |
custom.invoice |
Invoice ID, Amount, Status | Structured fields without stored identity. |
dataRecord.custom.invoice |
Saved invoice | Invoice fields plus id, createdAt, updatedAt. |
list.custom.invoice |
Extracted invoices | A list of Invoice shapes. |
list.dataRecord.custom.invoice |
Saved invoices | A list of records with identity. |
A shape does not identify a saved row
Section titled “A shape does not identify a saved row”An Ask AI result can have the Invoice shape without being stored. Create a record to obtain identity. Update data and Delete data need a saved record. Ask AI rejects dataRecord.* response types. A returned record can satisfy its corresponding shape contract. Adding dataRecord. to a type name creates no row.
In a stored schema, a custom-typed field references another record. For direct writes, supply its ID. Expression field access resolves the reference. An ordinary shape’s structured field can hold nested data instead. Stored timestamps use expression IDs createdAt and updatedAt, displayed as created time and updated time. They are text, so convert them before date operations.
In the app: choose stored identity with the type selector’s Expect data record with id checkbox. Choose a list with List. For extracted invoice fields, leave the record checkbox off. With an assistant: when defining inputs, use the exact type ID to make these choices.
Resolve unknown outputs before using their fields
Section titled “Resolve unknown outputs before using their fields”An unresolved output blocks field access. Select the node’s supported output type, run it with representative data, or declare a documented sample as unverified. Observed types belong to that node, not every instance of its action.
In the app: inspect Action output format. In an editable development view only, No output format yet offers Test action. In a read-only view, it directs you to run in development. Configure the action before testing. Testing makes its real external request.
With an assistant: use <workflowId> and <nodeId> discovered in the node guide. Supply workflowId as a string containing a positive integer. Inspect the node’s status with node_status, called with { "workflowId": "<workflowId>", "nodeId": "<nodeId>" }, and resolve its schema with schema_type_resolve to see its output type:
{ "workflowId": "<workflowId>", "typeId": "node.<nodeId>" }schema_type_resolve only inspects. For a documented sample, take the provider’s response object or nonempty array of objects. Declare it with node_output_type_declare, passing the parsed JSON in sample, then resolve the schema again to inspect its type.
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "sample": { "<field>": "<value>" } }Alternatively, inspect the node’s test inputs with run_inputs to get the IDs for your representative values.
{ "workflowId": "<workflowId>", "nodeIdOrFlowId": "<nodeId>" }Key representative values by the returned IDs, including every data.flowInputs[].id. Then test the node with run_node and resolve its schema again to inspect the output type.
{ "workflowId": "<workflowId>", "nodeId": "<nodeId>", "inputs": { "<inputId>": "<value>" } }After a representative run completes, the node can adopt its observed output. If a known Invoice record is absent at runtime, Get data returns null. Define the missing-record branch instead of inventing a schema.
Empty does not mean false or zero
Section titled “Empty does not mean false or zero”For text, number, or boolean values only, use ?? with a literal fallback of the same type. These expressions supply fallbacks while preserving real 0 and false.
flow.amount ?? 0flow.reviewNeeded ?? falseflow.invoiceId ?? "missing"Dates, shapes, records, and lists reject ??. For these types, branch on presence instead. For output wrappers, access .data first. Unless you also flag an unknown invoice amount for review, do not default it to zero.
Text .isEmpty() recognizes null, undefined, and "". It treats whitespace as present. Text fallback, however, replaces whitespace-only text. Outside list predicates, presence checks for shapes, records, and files treat only null and undefined as missing. They treat {} as present. Inside .filter() and .every() field predicates, {} and [] count as empty. Check the fields the next step needs.
In list predicates, row.status === "" matches empty text. The predicate row.status !== "" also passes missing values. The predicate row.status.includes("") matches every text value. Use presence checks to exclude missing values. When a schema is known, an unknown field fails compilation. At runtime, .filter() drops missing-field constraints and can retain every row. For missing-field constraints, .every() returns false. Revalidate expressions after schema changes.
In development flow tests, if you omit a used input key, the run reuses its saved test value. To test missing data, supply its exact ID with null. Manual Test converts null text to "" and other missing values to null. Outside manual Test, omitted optional inputs become null. Check the intended trigger/live path too.
Distinguish a missing list from an empty list
Section titled “Distinguish a missing list from an empty list”On a typed null list, both .isEmpty() and .isNotEmpty() return false. Field filtering can fail on that list. Require the input or make its producer return []. Test null separately. For scalar values, .toList() wraps null as [null].
Operation on [] |
Result | Applicable list |
|---|---|---|
.length, .sum() |
0 |
Any list for length; numbers for sum. |
.average() |
null |
Numbers. |
.first(), .last(), .item(n) |
null |
Any list; no position exists. |
.find(predicate) |
null |
Structured items with a valid predicate. |
.some(predicate) |
false |
Structured items with a valid predicate. |
.every(predicate) |
true |
Structured items with a valid predicate. |
.join(separator), .formatAsText(...) |
"" |
Lists supporting the operation. |
.stringify() |
"[]" |
Any list. |
If at least one row must pass, require a positive length as well as .every(...). An empty list satisfies a valid every predicate.
Convert dates with the right unit
Section titled “Convert dates with the right unit”A date-typed field supports date operations directly. For text, use .toDate(). By default, parsing uses strict ISO. Invalid input returns null. Use the returned bindings and explicit epoch units to convert text into dates.
flow.dateText.toDate().format("YYYY-MM-DD")flow.epochText.toDate("epoch_seconds")flow.epochText.toDate("epoch_millis")Epoch seconds are multiplied by 1000. Epoch milliseconds and numeric values used directly as dates already use milliseconds. Parsing and formatting default to UTC. If parsed text includes an offset or Z, that takes precedence. .format() uses Moment tokens, so YYYY-MM-DD returns year-month-day text.
See expression operations for each operation’s input, result, and spelling.