Defines the export file formats, import validation, template-based field mapping, and the asynchronous import-job contracts.
Data Export & Import Protocol
Defines the export file formats, import validation, template-based field
mapping, and the asynchronous import-job contracts.
Industry alignment: Salesforce Data Export, Airtable CSV Export,
Dynamics 365 Data Management.
The export the platform serves is the synchronous streaming door
GET /api/v1/data/:object/export, which answers the file itself as CSV,
JSON or XLSX. The asynchronous export-job API that used to be
declared here (export jobs, their progress / download / list shapes,
scheduled exports and ExportApiContracts) was never served by any route and
was removed in @objectstack/spec 17 (ADR-0049 enforce-or-remove); a recurring
export is a Job whose handler you write.
Name of a registered mapping metadata artifact to apply; the server resolves it (org-scoped rows first, then env-wide) and projects columns through it. Mutually exclusive with an inline mapping — supplying both is refused (400 CONFLICTING_MAPPING).
dryRun
boolean
optional (default: false)
Validate + coerce every row without persisting. The verdict is the engine's own write-path validation, with one boundary an author should know: a preview runs NO automations. Hooks never fire in a dry run — a preview that executed user-authored side effects (mail, outbound calls, writes to other objects) would be the retired validateOnly defect in a new spelling. So a dry run with runAutomations: true can report required for a field a beforeInsert hook would populate during the real import; for hook-derived fields the real write is authoritative.
writeMode
Enum<'insert' | 'update' | 'upsert'>
optional (default: "insert")
insert / update / upsert semantics
matchFields
string[] | string[][]
optional
Fields that identify an existing record (required for update/upsert). Either one key set (['email']), or an ordered list of key sets ([['credit_code'], ['country', 'registration_no']]) for a sheet whose rows are identified in different ways: each row is matched by the first set whose fields are all non-blank on that row, and only by that set. A row blank on every set fails with BLANK_MATCH_KEY instead of being created or skipped, so skipBlankMatchKey cannot be combined with key sets. A set that matches more than one record fails the row with AMBIGUOUS_MATCH, as one key set does. Rows of one import that carry the same key (the key set each row is matched by, with its cell values as coerced, so an option label and its value are one key) all fail with DUPLICATE_MATCH_KEY, naming every row that carries it, and none of them is written, on a dry run as on the import: keep one row per key. In update / upsert, a key (this field, or the named mapping's upsertKey it falls back to) naming a field that holds a list or a structured value — a multiple: true select, radio, lookup, user, file or image field, a multiselect, checkboxes or tags field, or a json, composite, repeater, record, location, address or vector field, the population isMultiValueField and STRUCTURED_JSON_TYPES define — is refused with 400 INVALID_REQUEST before any row is matched or written, on a dry run as on the import, naming each such field (match on single-value fields: a code, a name, an email); a caller that hands rows to the import runner without this door (a mapping's connector pull) gets every row failed with VALIDATION_ERROR and the same refusal instead.
runAutomations
boolean
optional (default: true)
Fire triggers/hooks for each imported row. ON by default, and opting out must be explicit: automations always ran on import historically (the engine ignored this flag until this flag was honoured), so omitting the key runs them. This matches platform convention (Salesforce fires triggers on import by default). Only the system principal (an in-process caller such as a seed or migration job) may send runAutomations: false, because it takes the object's triggers and metadata-bound hooks, its approvals and record freezes among them, off every row: the import doors refuse it from every other caller, every signed-in user and administrator included, with 403 PERMISSION_DENIED before any row is read. One boundary: a dryRun preview runs NO automations whatever this flag says.
treatAsHistorical
boolean
optional (default: false)
Import as established historical facts. Two effects, both off by default so a normal import is unchanged: (1) skip the state_machine rule so mid-lifecycle rows (e.g. already-closed tickets, closed_won deals) are not rejected by initialStates; and (2) preserve the original audit timeline — keep the supplied created_at / updated_at / updated_by and author-declared business readonly fields (e.g. closed_at, resolved_by) instead of stamping-now / stripping them. Undoing a historical import mirrors (2): the captured pre-import values are restored verbatim rather than re-stamped. Only the system principal (an in-process caller such as a seed or migration job) may send treatAsHistorical: true: the import doors refuse it from every other caller, every signed-in user and administrator included, with 403 PERMISSION_DENIED before any row is read.
trimWhitespace
boolean
optional (default: true)
Trim leading/trailing whitespace from string cells
nullValues
string[]
optional
Strings treated as null/blank (besides empty string)
createMissingOptions
boolean
optional (default: false)
Keep a select / radio / multiselect cell that matches none of the field's options instead of failing the row. The cell is stored as written (trimmed; for a multi-value cell, each unmatched item), and the engine's option check admits exactly the values this import kept, on this import's writes (dry run included). The field's option list is not changed: a later write that sends the field is judged against the options again, while one that leaves the field out is not affected. A field bound to a shared picklist that did not resolve is still refused.
skipBlankMatchKey
boolean
optional (default: false)
Skip rows whose matchFields are blank (default: upsert creates them, update skips them). One key set only: with ordered key sets a row blank on every set is a row error.
Whether this field is required (import validation)
applyOn
Enum<'create' | 'always'>
optional (default: "always")
When an import writes this column. always (default) writes it on every row the import creates or updates. create writes it only when the row is created: an upsert that matches an existing record leaves that record's value as it is, and an update import never writes it, so re-running one upsert refreshes the always columns without reverting state written since the first run. A create-only column is still read for matching: the match key a row was found by stays in that row's update.
Whether this field is required (import validation)
applyOn
Enum<'create' | 'always'>
optional (default: "always")
When an import writes this column. always (default) writes it on every row the import creates or updates. create writes it only when the row is created: an upsert that matches an existing record leaves that record's value as it is, and an update import never writes it, so re-running one upsert refreshes the always columns without reverting state written since the first run. A create-only column is still read for matching: the match key a row was found by stays in that row's update.
Whether this field is required (import validation)
applyOn
Enum<'create' | 'always'>
optional (default: "always")
When an import writes this column. always (default) writes it on every row the import creates or updates. create writes it only when the row is created: an upsert that matches an existing record leaves that record's value as it is, and an update import never writes it, so re-running one upsert refreshes the always columns without reverting state written since the first run. A create-only column is still read for matching: the match key a row was found by stays in that row's update.
Whether this job can still be logically rolled back (undo log captured, terminal state, not yet reverted)
revertedAt
string
optional
When the job was undone / rolled back (ISO 8601): set only once every row is reverted. An undo that left rows unreverted sets nothing, and the job stays undoable for those rows.
error
string
optional
Why the job failed (when status = failed): the fatal error that aborted it, or, when every row failed, one sentence pointing at the job's results, which carry each row's reason
Whether this job can still be logically rolled back (undo log captured, terminal state, not yet reverted)
revertedAt
string
optional
When the job was undone / rolled back (ISO 8601): set only once every row is reverted. An undo that left rows unreverted sets nothing, and the job stays undoable for those rows.
error
string
optional
Why the job failed (when status = failed): the fatal error that aborted it, or, when every row failed, one sentence pointing at the job's results, which carry each row's reason
Capped sample of per-row outcomes, failures first. An ok row, and any droppedFields or warnings it carries, reaches this reader only if it falls inside the sample; resultsTruncated says whether the sample is partial, and the job counters count every row.
resultsTruncated
boolean
✅
Whether results is a capped sample of a larger set
Every cell error of a failed row, one element per failed cell, in the validate verdict's issue shape (field, code, message). The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only rule or severity. Present only on a failed row that has at least one cell error, so a row that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys field, code and error stay and name element 0, so a reader of those keys sees the same answer as before. A server that does not produce this list omits the key, and the row then reports its first error only.
Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict's row warnings: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules (severity: 'warning' or 'info', each naming its rule and severity). Set only on a dry-run row the verdict accepted: the row is ok because the write would store it. A committed row does not carry it: the import does not copy a write answer's warnings onto the row.
Write-observability: caller-supplied fields the engine LEGALLY strips from THIS row, one event per reason, in the engine's own droppedFields shape and reason vocabulary. A committed row reports the strips its write made. A dry-run row reports the strips its preview runs, which for a row the import would update excludes readonlyWhen and primary-key strips, so that row can name fewer fields than its commit. The row still succeeds: ok and action are unchanged. Present only when at least one field was dropped. A server or write path that does not produce this report omits the key too, so an absent key alone does not prove nothing was dropped. In an async job's results, an ok row's drops reach the reader only if the row falls inside that capped, failures-first sample.
Whether this job can still be logically rolled back
revertedAt
string
optional
When the job was undone / rolled back (ISO 8601): set only once every row is reverted. An undo that left rows unreverted sets nothing, and the job stays undoable for those rows.
Name of a registered mapping metadata artifact to apply; the server resolves it (org-scoped rows first, then env-wide) and projects columns through it. Mutually exclusive with an inline mapping — supplying both is refused (400 CONFLICTING_MAPPING).
dryRun
boolean
optional (default: false)
Validate + coerce every row without persisting. The verdict is the engine's own write-path validation, with one boundary an author should know: a preview runs NO automations. Hooks never fire in a dry run — a preview that executed user-authored side effects (mail, outbound calls, writes to other objects) would be the retired validateOnly defect in a new spelling. So a dry run with runAutomations: true can report required for a field a beforeInsert hook would populate during the real import; for hook-derived fields the real write is authoritative.
writeMode
Enum<'insert' | 'update' | 'upsert'>
optional (default: "insert")
insert / update / upsert semantics
matchFields
string[] | string[][]
optional
Fields that identify an existing record (required for update/upsert). Either one key set (['email']), or an ordered list of key sets ([['credit_code'], ['country', 'registration_no']]) for a sheet whose rows are identified in different ways: each row is matched by the first set whose fields are all non-blank on that row, and only by that set. A row blank on every set fails with BLANK_MATCH_KEY instead of being created or skipped, so skipBlankMatchKey cannot be combined with key sets. A set that matches more than one record fails the row with AMBIGUOUS_MATCH, as one key set does. Rows of one import that carry the same key (the key set each row is matched by, with its cell values as coerced, so an option label and its value are one key) all fail with DUPLICATE_MATCH_KEY, naming every row that carries it, and none of them is written, on a dry run as on the import: keep one row per key. In update / upsert, a key (this field, or the named mapping's upsertKey it falls back to) naming a field that holds a list or a structured value — a multiple: true select, radio, lookup, user, file or image field, a multiselect, checkboxes or tags field, or a json, composite, repeater, record, location, address or vector field, the population isMultiValueField and STRUCTURED_JSON_TYPES define — is refused with 400 INVALID_REQUEST before any row is matched or written, on a dry run as on the import, naming each such field (match on single-value fields: a code, a name, an email); a caller that hands rows to the import runner without this door (a mapping's connector pull) gets every row failed with VALIDATION_ERROR and the same refusal instead.
runAutomations
boolean
optional (default: true)
Fire triggers/hooks for each imported row. ON by default, and opting out must be explicit: automations always ran on import historically (the engine ignored this flag until this flag was honoured), so omitting the key runs them. This matches platform convention (Salesforce fires triggers on import by default). Only the system principal (an in-process caller such as a seed or migration job) may send runAutomations: false, because it takes the object's triggers and metadata-bound hooks, its approvals and record freezes among them, off every row: the import doors refuse it from every other caller, every signed-in user and administrator included, with 403 PERMISSION_DENIED before any row is read. One boundary: a dryRun preview runs NO automations whatever this flag says.
treatAsHistorical
boolean
optional (default: false)
Import as established historical facts. Two effects, both off by default so a normal import is unchanged: (1) skip the state_machine rule so mid-lifecycle rows (e.g. already-closed tickets, closed_won deals) are not rejected by initialStates; and (2) preserve the original audit timeline — keep the supplied created_at / updated_at / updated_by and author-declared business readonly fields (e.g. closed_at, resolved_by) instead of stamping-now / stripping them. Undoing a historical import mirrors (2): the captured pre-import values are restored verbatim rather than re-stamped. Only the system principal (an in-process caller such as a seed or migration job) may send treatAsHistorical: true: the import doors refuse it from every other caller, every signed-in user and administrator included, with 403 PERMISSION_DENIED before any row is read.
trimWhitespace
boolean
optional (default: true)
Trim leading/trailing whitespace from string cells
nullValues
string[]
optional
Strings treated as null/blank (besides empty string)
createMissingOptions
boolean
optional (default: false)
Keep a select / radio / multiselect cell that matches none of the field's options instead of failing the row. The cell is stored as written (trimmed; for a multi-value cell, each unmatched item), and the engine's option check admits exactly the values this import kept, on this import's writes (dry run included). The field's option list is not changed: a later write that sends the field is judged against the options again, while one that leaves the field out is not affected. A field bound to a shared picklist that did not resolve is still refused.
skipBlankMatchKey
boolean
optional (default: false)
Skip rows whose matchFields are blank (default: upsert creates them, update skips them). One key set only: with ordered key sets a row blank on every set is a row error.
Whether this field is required (import validation)
applyOn
Enum<'create' | 'always'>
optional (default: "always")
When an import writes this column. always (default) writes it on every row the import creates or updates. create writes it only when the row is created: an upsert that matches an existing record leaves that record's value as it is, and an update import never writes it, so re-running one upsert refreshes the always columns without reverting state written since the first run. A create-only column is still read for matching: the match key a row was found by stays in that row's update.
Every cell error of a failed row, one element per failed cell, in the validate verdict's issue shape (field, code, message). The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only rule or severity. Present only on a failed row that has at least one cell error, so a row that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys field, code and error stay and name element 0, so a reader of those keys sees the same answer as before. A server that does not produce this list omits the key, and the row then reports its first error only.
Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict's row warnings: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules (severity: 'warning' or 'info', each naming its rule and severity). Set only on a dry-run row the verdict accepted: the row is ok because the write would store it. A committed row does not carry it: the import does not copy a write answer's warnings onto the row.
Write-observability: caller-supplied fields the engine LEGALLY strips from THIS row, one event per reason, in the engine's own droppedFields shape and reason vocabulary. A committed row reports the strips its write made. A dry-run row reports the strips its preview runs, which for a row the import would update excludes readonlyWhen and primary-key strips, so that row can name fewer fields than its commit. The row still succeeds: ok and action are unchanged. Present only when at least one field was dropped. A server or write path that does not produce this report omits the key too, so an absent key alone does not prove nothing was dropped. In an async job's results, an ok row's drops reach the reader only if the row falls inside that capped, failures-first sample.
Every cell error of a failed row, one element per failed cell, in the validate verdict's issue shape (field, code, message). The list holds the import's cell-coercion errors, and a cell error never carries the advisory-only rule or severity. Present only on a failed row that has at least one cell error, so a row that failed for another reason (a duplicate or ambiguous match key, say) omits it. The first-error keys field, code and error stay and name element 0, so a reader of those keys sees the same answer as before. A server that does not produce this list omits the key, and the row then reports its first error only.
Findings this deployment ADMITS rather than rejects, copied verbatim from the validate verdict's row warnings: ADR-0104 value shapes under a warn-first posture, then the hits of advisory validation rules (severity: 'warning' or 'info', each naming its rule and severity). Set only on a dry-run row the verdict accepted: the row is ok because the write would store it. A committed row does not carry it: the import does not copy a write answer's warnings onto the row.
Write-observability: caller-supplied fields the engine LEGALLY strips from THIS row, one event per reason, in the engine's own droppedFields shape and reason vocabulary. A committed row reports the strips its write made. A dry-run row reports the strips its preview runs, which for a row the import would update excludes readonlyWhen and primary-key strips, so that row can name fewer fields than its commit. The row still succeeds: ok and action are unchanged. Present only when at least one field was dropped. A server or write path that does not produce this report omits the key too, so an absent key alone does not prove nothing was dropped. In an async job's results, an ok row's drops reach the reader only if the row falls inside that capped, failures-first sample.
A write-path strip event: caller-supplied fields legally dropped from the payload, or written with the engine's computed value in place of the caller's
Property
Type
Required
Description
object
string
✅
Object the write targeted (resolved object name)
fields
string[]
✅
Caller-supplied field names whose value the engine did not store: removed from the write payload, or (stored_expression) written with the computed value in place of the caller's
Why the fields were dropped: static readonly, a TRUE readonlyWhen predicate, the primary-key strip of a payload id the engine ruled is not an identifier, a computed (formula) field no driver has a column for, or a stored field whose declared expression the engine computes on every write, so the caller's different value was replaced by the computed one
Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCode
string
optional
The producer-declared code, verbatim, when it is not a member of the closed code vocabulary — the open, author-authored channel (app-specific spellings; ADR-0112)
message
string
✅
Readable error message
userMessage
string
optional
Producer-marked user-facing refusal text, verbatim, in the request's locale: platform-composed text falls back to the workspace default locale, then en; an app-authored refusal falls back to its declared wording. Present exactly when the producer opted in at throw time; consumers render it to end users as received and keep their generic substitution for anything unmarked. Status-agnostic; never replaces message.
refusal
true
optional
Producer-declared: the 5xx this envelope carries is a deliberate refusal whose message is authored for the caller, so a boundary that reads the declaration keeps it verbatim (until the withhold arms read it, a declared refusal is still withheld). Absent (the default) on a declared fault, whose message is withheld from the body and logged for the operator; redundant on a 4xx. Presence is the declaration — true is the only value.
category
string
optional
Error category (e.g. validation, authorization)
httpStatus
integer
optional
HTTP status of the response carrying this error
details
any
optional
Additional error context (e.g. field validation errors)
Whether this job can still be logically rolled back
revertedAt
string
optional
When the job was undone / rolled back (ISO 8601): set only once every row is reverted. An undo that left rows unreverted sets nothing, and the job stays undoable for those rows.
One entry per row the undo did not revert, in the order the undo tried them (deletes first). For every caller but the system principal the reversal writes run under the object's hooks, record-change triggers and state_machine rule, so a row one of them refuses is listed here, as is a write that failed for any other reason. The job keeps these rows, each with its entry, in its undo log and stays undoable: undoing it again retries only them. Empty when every row was reverted.