ObjectStackObjectStack

Export schema — API Protocol reference

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.

Source: packages/spec/src/api/export.zod.ts

TypeScript Usage

import { CreateImportJobRequestSchema, CreateImportJobResponseSchema, DeduplicationStrategy, ExportFormat, ExportImportTemplateSchema, FieldMappingEntrySchema, ImportJobProgressSchema, ImportJobResultsSchema, ImportJobStatus, ImportJobSummarySchema, ImportMappingSchema, ImportRequestSchema, ImportResponseSchema, ImportRowResultSchema, ImportValidationConfigSchema, ImportValidationMode, ImportValidationResultSchema, ImportWriteMode, ListImportJobsRequestSchema, ListImportJobsResponseSchema, UndoImportJobResponseSchema } from '@objectstack/spec/api';
import type { CreateImportJobRequest, CreateImportJobResponse, DeduplicationStrategy, ExportFormat, ExportImportTemplate, FieldMappingEntry, ImportJobProgress, ImportJobResults, ImportJobStatus, ImportJobSummary, ImportMapping, ImportRequest, ImportResponse, ImportRowResult, ImportValidationConfig, ImportValidationMode, ImportValidationResult, ImportWriteMode, ListImportJobsRequest, ListImportJobsResponse, UndoImportJobResponse } from '@objectstack/spec/api';

// Validate data
const result = CreateImportJobRequestSchema.parse(data);

CreateImportJobRequest

Properties

PropertyTypeRequiredDescription
formatEnum<'csv' | 'json' | 'xlsx'>optionalPayload shape: csv text, a rows[] array, or a base64 xlsx (inferred when omitted)
csvstringoptionalCSV text (when format = csv)
rowsRecord<string, any>[]optionalRow objects (when format = json)
xlsxBase64stringoptionalBase64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side
sheetstring | integeroptionalWorksheet name or 1-based index to read (xlsx; defaults to the first sheet)
mappingRecord<string, string> | { sourceField: string; targetField: string; targetLabel?: string; transform?: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[]optionalSource column → target field mapping
mappingNamestringoptionalName 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).
dryRunbooleanoptional (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.
writeModeEnum<'insert' | 'update' | 'upsert'>optional (default: "insert")insert / update / upsert semantics
matchFieldsstring[] | string[][]optionalFields 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.
runAutomationsbooleanoptional (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.
treatAsHistoricalbooleanoptional (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.
trimWhitespacebooleanoptional (default: true)Trim leading/trailing whitespace from string cells
nullValuesstring[]optionalStrings treated as null/blank (besides empty string)
createMissingOptionsbooleanoptional (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.
skipBlankMatchKeybooleanoptional (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.

Nested Shape: CreateImportJobRequest.mapping[number]

PropertyTypeRequiredDescription
sourceFieldstring✅Field name in the source data (import) or object (export)
targetFieldstring✅Field name in the target object (import) or file column (export)
targetLabelstringoptionalDisplay label for the target column (export)
transformEnum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>optional (default: "none")Transformation to apply during mapping
defaultValueanyoptionalDefault value if source field is null/empty
requiredbooleanoptional (default: false)Whether this field is required (import validation)
applyOnEnum<'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.

CreateImportJobResponse

Properties

PropertyTypeRequiredDescription
jobIdstring✅Import job id — poll progress/results with this
objectstring✅Target object name
statusEnum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>✅Initial job status (usually "pending")
totalinteger✅Rows accepted for processing
createdAtstring✅Job creation timestamp (ISO 8601)

DeduplicationStrategy

Allowed Values

  • skip
  • update
  • create_new
  • fail

ExportFormat

Allowed Values

  • csv
  • json
  • jsonl
  • xlsx
  • parquet

ExportImportTemplate

Properties

PropertyTypeRequiredDescription
idstringoptionalTemplate ID (generated on save)
namestring✅Template machine name (snake_case)
labelstring✅Human-readable template label
descriptionstringoptionalTemplate description
objectstring✅Target object name
directionEnum<'import' | 'export' | 'bidirectional'>✅Template direction
formatEnum<'csv' | 'json' | 'jsonl' | 'xlsx' | 'parquet'>optionalDefault file format for this template
mappings{ sourceField: string; targetField: string; targetLabel?: string; transform?: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[]✅Field mapping entries
createdAtstringoptionalTemplate creation timestamp
updatedAtstringoptionalLast update timestamp
createdBystringoptionalUser who created the template

Nested Shape: ExportImportTemplate.mappings[number]

PropertyTypeRequiredDescription
sourceFieldstring✅Field name in the source data (import) or object (export)
targetFieldstring✅Field name in the target object (import) or file column (export)
targetLabelstringoptionalDisplay label for the target column (export)
transformEnum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>optional (default: "none")Transformation to apply during mapping
defaultValueanyoptionalDefault value if source field is null/empty
requiredbooleanoptional (default: false)Whether this field is required (import validation)
applyOnEnum<'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.

FieldMappingEntry

Properties

PropertyTypeRequiredDescription
sourceFieldstring✅Field name in the source data (import) or object (export)
targetFieldstring✅Field name in the target object (import) or file column (export)
targetLabelstringoptionalDisplay label for the target column (export)
transformEnum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>optional (default: "none")Transformation to apply during mapping
defaultValueanyoptionalDefault value if source field is null/empty
requiredbooleanoptional (default: false)Whether this field is required (import validation)
applyOnEnum<'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.

ImportJobProgress

Properties

PropertyTypeRequiredDescription
jobIdstring✅Import job id
objectstring✅Target object name
statusEnum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>✅Current job status
dryRunboolean✅Whether this is a validate-only pass
writeModeEnum<'insert' | 'update' | 'upsert'>✅Write mode used
totalinteger✅Total rows to process
processedinteger✅Rows processed so far
createdinteger✅Rows that created a new record
updatedinteger✅Rows that updated an existing record
skippedinteger✅Rows skipped
errorsinteger✅Rows that failed
percentCompletenumber✅processed / total as a percentage
undoableboolean✅Whether this job can still be logically rolled back (undo log captured, terminal state, not yet reverted)
revertedAtstringoptionalWhen 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.
errorstringoptionalWhy 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
startedAtstringoptionalProcessing start timestamp (ISO 8601)
completedAtstringoptionalCompletion timestamp (ISO 8601)
createdAtstring✅Job creation timestamp (ISO 8601)

ImportJobResults

Properties

PropertyTypeRequiredDescription
jobIdstring✅Import job id
objectstring✅Target object name
statusEnum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>✅Current job status
dryRunboolean✅Whether this is a validate-only pass
writeModeEnum<'insert' | 'update' | 'upsert'>✅Write mode used
totalinteger✅Total rows to process
processedinteger✅Rows processed so far
createdinteger✅Rows that created a new record
updatedinteger✅Rows that updated an existing record
skippedinteger✅Rows skipped
errorsinteger✅Rows that failed
percentCompletenumber✅processed / total as a percentage
undoableboolean✅Whether this job can still be logically rolled back (undo log captured, terminal state, not yet reverted)
revertedAtstringoptionalWhen 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.
errorstringoptionalWhy 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
startedAtstringoptionalProcessing start timestamp (ISO 8601)
completedAtstringoptionalCompletion timestamp (ISO 8601)
createdAtstring✅Job creation timestamp (ISO 8601)
results{ row: integer; ok: boolean; action: Enum<'created' | 'updated' | 'skipped' | 'failed'>; id?: string; … }[]✅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.
resultsTruncatedboolean✅Whether results is a capped sample of a larger set

Nested Shape: ImportJobResults.results[number]

PropertyTypeRequiredDescription
rowinteger✅1-based row number in the source data
okboolean✅Whether the row succeeded
actionEnum<'created' | 'updated' | 'skipped' | 'failed'>✅What happened to the row
idstringoptionalRecord id (created/updated rows)
fieldstringoptionalField that caused a coercion/validation error (element 0 of errors when present)
codestringoptionalError code (failed rows; element 0 of errors when present)
errorstringoptionalHuman-readable error message (failed rows; element 0 of errors when present)
errors{ field: string; code: string; message: string; rule?: string; … }[]optionalEvery 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.
warnings{ field: string; code: string; message: string; rule?: string; … }[]optionalFindings 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.
droppedFields{ object: string; fields: string[]; reason: Enum<'readonly' | 'readonly_when' | 'primary_key' | 'computed' | 'stored_expression'> }[]optionalWrite-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.

ImportJobStatus

Allowed Values

  • pending
  • running
  • succeeded
  • failed
  • cancelled

ImportJobSummary

Properties

PropertyTypeRequiredDescription
jobIdstring✅Import job id
objectstring✅Target object name
statusEnum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>✅Job status
totalinteger✅Total rows
processedinteger✅Rows processed
createdinteger✅Rows created
updatedinteger✅Rows updated
skippedinteger✅Rows skipped
errorsinteger✅Rows failed
createdAtstring✅Job creation timestamp (ISO 8601)
completedAtstringoptionalCompletion timestamp (ISO 8601)
undoableboolean✅Whether this job can still be logically rolled back
revertedAtstringoptionalWhen 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.

ImportMapping

Union Options

This schema accepts one of the following structures:

Option 1

Type: Record<string, string>


Option 2

Type: { sourceField: string; targetField: string; targetLabel?: string; transform?: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[]



ImportRequest

Properties

PropertyTypeRequiredDescription
formatEnum<'csv' | 'json' | 'xlsx'>optionalPayload shape: csv text, a rows[] array, or a base64 xlsx (inferred when omitted)
csvstringoptionalCSV text (when format = csv)
rowsRecord<string, any>[]optionalRow objects (when format = json)
xlsxBase64stringoptionalBase64-encoded .xlsx workbook bytes (when format = xlsx); parsed server-side
sheetstring | integeroptionalWorksheet name or 1-based index to read (xlsx; defaults to the first sheet)
mappingRecord<string, string> | { sourceField: string; targetField: string; targetLabel?: string; transform?: Enum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>; … }[]optionalSource column → target field mapping
mappingNamestringoptionalName 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).
dryRunbooleanoptional (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.
writeModeEnum<'insert' | 'update' | 'upsert'>optional (default: "insert")insert / update / upsert semantics
matchFieldsstring[] | string[][]optionalFields 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.
runAutomationsbooleanoptional (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.
treatAsHistoricalbooleanoptional (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.
trimWhitespacebooleanoptional (default: true)Trim leading/trailing whitespace from string cells
nullValuesstring[]optionalStrings treated as null/blank (besides empty string)
createMissingOptionsbooleanoptional (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.
skipBlankMatchKeybooleanoptional (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.

Nested Shape: ImportRequest.mapping[number]

PropertyTypeRequiredDescription
sourceFieldstring✅Field name in the source data (import) or object (export)
targetFieldstring✅Field name in the target object (import) or file column (export)
targetLabelstringoptionalDisplay label for the target column (export)
transformEnum<'none' | 'uppercase' | 'lowercase' | 'trim' | 'date_format' | 'lookup'>optional (default: "none")Transformation to apply during mapping
defaultValueanyoptionalDefault value if source field is null/empty
requiredbooleanoptional (default: false)Whether this field is required (import validation)
applyOnEnum<'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.

ImportResponse

Properties

PropertyTypeRequiredDescription
objectstring✅Target object name
dryRunboolean✅Whether this was a validate-only pass
writeModeEnum<'insert' | 'update' | 'upsert'>✅Write mode used
totalinteger✅Rows processed
okinteger✅Rows that succeeded
errorsinteger✅Rows that failed
createdinteger✅Rows that created a new record
updatedinteger✅Rows that updated an existing record
skippedinteger✅Rows skipped (no match in update mode, etc.)
results{ row: integer; ok: boolean; action: Enum<'created' | 'updated' | 'skipped' | 'failed'>; id?: string; … }[]✅Per-row outcomes

Nested Shape: ImportResponse.results[number]

PropertyTypeRequiredDescription
rowinteger✅1-based row number in the source data
okboolean✅Whether the row succeeded
actionEnum<'created' | 'updated' | 'skipped' | 'failed'>✅What happened to the row
idstringoptionalRecord id (created/updated rows)
fieldstringoptionalField that caused a coercion/validation error (element 0 of errors when present)
codestringoptionalError code (failed rows; element 0 of errors when present)
errorstringoptionalHuman-readable error message (failed rows; element 0 of errors when present)
errors{ field: string; code: string; message: string; rule?: string; … }[]optionalEvery 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.
warnings{ field: string; code: string; message: string; rule?: string; … }[]optionalFindings 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.
droppedFields{ object: string; fields: string[]; reason: Enum<'readonly' | 'readonly_when' | 'primary_key' | 'computed' | 'stored_expression'> }[]optionalWrite-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.

ImportRowResult

Properties

PropertyTypeRequiredDescription
rowinteger✅1-based row number in the source data
okboolean✅Whether the row succeeded
actionEnum<'created' | 'updated' | 'skipped' | 'failed'>✅What happened to the row
idstringoptionalRecord id (created/updated rows)
fieldstringoptionalField that caused a coercion/validation error (element 0 of errors when present)
codestringoptionalError code (failed rows; element 0 of errors when present)
errorstringoptionalHuman-readable error message (failed rows; element 0 of errors when present)
errors{ field: string; code: string; message: string; rule?: string; … }[]optionalEvery 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.
warnings{ field: string; code: string; message: string; rule?: string; … }[]optionalFindings 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.
droppedFields{ object: string; fields: string[]; reason: Enum<'readonly' | 'readonly_when' | 'primary_key' | 'computed' | 'stored_expression'> }[]optionalWrite-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.

Nested Shape: ImportRowResult.errors[number]

PropertyTypeRequiredDescription
fieldstring✅The field the finding is about (_record for an object-level rule).
codestring✅Machine-readable finding code, e.g. required, invalid_type, rule_violation.
messagestring✅Human-readable message — a validation rule's author-written text where one exists.
rulestringoptionalThe name of the ADVISORY validation rule this finding reports. Present only on an advisory rule hit.
severityEnum<'warning' | 'info'>optionalThe advisory rule's declared severity, warning or info. Present only on an advisory rule hit.

Nested Shape: ImportRowResult.warnings[number]

PropertyTypeRequiredDescription
fieldstring✅The field the finding is about (_record for an object-level rule).
codestring✅Machine-readable finding code, e.g. required, invalid_type, rule_violation.
messagestring✅Human-readable message — a validation rule's author-written text where one exists.
rulestringoptionalThe name of the ADVISORY validation rule this finding reports. Present only on an advisory rule hit.
severityEnum<'warning' | 'info'>optionalThe advisory rule's declared severity, warning or info. Present only on an advisory rule hit.

Nested Shape: ImportRowResult.droppedFields[number]

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

PropertyTypeRequiredDescription
objectstring✅Object the write targeted (resolved object name)
fieldsstring[]✅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
reasonEnum<'readonly' | 'readonly_when' | 'primary_key' | 'computed' | 'stored_expression'>✅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

ImportValidationConfig

Properties

PropertyTypeRequiredDescription
modeEnum<'strict' | 'lenient' | 'dry_run'>optional (default: "strict")Validation mode for the import
deduplication{ strategy?: Enum<'skip' | 'update' | 'create_new' | 'fail'>; matchFields: string[] }optionalDeduplication configuration
maxErrorsintegeroptional (default: 100)Maximum validation errors before aborting
trimWhitespacebooleanoptional (default: true)Trim leading/trailing whitespace from string fields
dateFormatstringoptionalExpected date format in import data (e.g., "YYYY-MM-DD")
nullValuesstring[]optionalStrings to treat as null (e.g., ["", "N/A", "null"])

Nested Shape: ImportValidationConfig.deduplication

PropertyTypeRequiredDescription
strategyEnum<'skip' | 'update' | 'create_new' | 'fail'>optional (default: "skip")How to handle duplicate records
matchFieldsstring[]✅Fields used to identify duplicates (e.g., "email", "external_id")

ImportValidationMode

Allowed Values

  • strict
  • lenient
  • dry_run

ImportValidationResult

Properties

PropertyTypeRequiredDescription
successboolean✅Operation success status
error{ code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … }optionalError details if success is false
meta{ timestamp: string; duration?: integer; requestId?: string; traceId?: string }optionalResponse metadata
data{ totalRecords: integer; validRecords: integer; invalidRecords: integer; duplicateRecords: integer; … }✅

Nested Shape: ImportValidationResult.error

PropertyTypeRequiredDescription
codeEnum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>✅Error code (e.g. VALIDATION_ERROR; StandardErrorCode ∪ the ledger the serving side registers — ERROR_CODE_LEDGER for framework packages)
declaredCodestringoptionalThe 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)
messagestring✅Readable error message
userMessagestringoptionalProducer-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.
refusaltrueoptionalProducer-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.
categorystringoptionalError category (e.g. validation, authorization)
httpStatusintegeroptionalHTTP status of the response carrying this error
detailsanyoptionalAdditional error context (e.g. field validation errors)
requestIdstringoptionalRequest ID for tracking

Nested Shape: ImportValidationResult.meta

PropertyTypeRequiredDescription
timestampstring✅
durationintegeroptionalServer-side processing duration in milliseconds
requestIdstringoptional
traceIdstringoptional

Nested Shape: ImportValidationResult.data

PropertyTypeRequiredDescription
totalRecordsinteger✅Total records in import file
validRecordsinteger✅Records that passed validation
invalidRecordsinteger✅Records that failed validation
duplicateRecordsinteger✅Duplicate records detected
errors{ row: integer; field?: string; code: string; message: string }[]✅List of validation errors
previewRecord<string, any>[]optionalPreview of first N valid records (for dry_run mode)

ImportWriteMode

Allowed Values

  • insert
  • update
  • upsert

ListImportJobsRequest

Properties

PropertyTypeRequiredDescription
objectstringoptionalFilter to one target object
statusEnum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>optionalFilter by job status
limitintegeroptional (default: 50)Max rows to return
offsetintegeroptional (default: 0)Pagination offset

ListImportJobsResponse

Properties

PropertyTypeRequiredDescription
jobs{ jobId: string; object: string; status: Enum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>; total: integer; … }[]✅Import jobs, newest first

Nested Shape: ListImportJobsResponse.jobs[number]

PropertyTypeRequiredDescription
jobIdstring✅Import job id
objectstring✅Target object name
statusEnum<'pending' | 'running' | 'succeeded' | 'failed' | 'cancelled'>✅Job status
totalinteger✅Total rows
processedinteger✅Rows processed
createdinteger✅Rows created
updatedinteger✅Rows updated
skippedinteger✅Rows skipped
errorsinteger✅Rows failed
createdAtstring✅Job creation timestamp (ISO 8601)
completedAtstringoptionalCompletion timestamp (ISO 8601)
undoableboolean✅Whether this job can still be logically rolled back
revertedAtstringoptionalWhen 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.

UndoImportJobResponse

Properties

PropertyTypeRequiredDescription
successboolean✅Whether every row was reverted. False when any row is listed in failures: the undo did not complete, and the job is not stamped reverted.
jobIdstring✅Import job id
objectstring✅Target object name
deletedinteger✅Created records deleted
restoredinteger✅Updated records restored to pre-import values
failedinteger✅Rows the undo did not revert: one per entry in failures
failures{ id: string; action: Enum<'delete' | 'restore'>; code: string; error: string }[]✅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.

Nested Shape: UndoImportJobResponse.failures[number]

PropertyTypeRequiredDescription
idstring✅Id of the record the reversal targeted
actionEnum<'delete' | 'restore'>✅The reversal that did not happen: delete for a record the import created, restore for one it updated
codestring✅Error code the write was refused or failed with, as the single-record write door answers it
errorstring✅Human-readable message: a refusing hook or validation rule's own sentence, or the door's withheld-fault sentence

On this page