Document Validation Started Event

The DOCUMENT_VALIDATION_STARTED event fires when a custom validation attempt begins for a document. It is the opening event of the validation lifecycle: it tells you that validation is expected, which path is running it, and which attempt the following events belong to.

It covers custom validations only. The model's validation rules evaluate synchronously during extraction and start no attempt, so a document validated by rules alone goes straight to DOCUMENT_VALIDATED with no started event before it.

When It Triggers

Custom validation runs on two independent paths, and each dispatch emits its own event:

source: "STATIC" -- the automatic batch of validation scripts has been enqueued. scriptCount reports how many enabled scripts the attempt covers.
source: "AGENT" -- a validator agent run has been enqueued for the document. agentId and runId identify the run.

Both paths can fire for the same document, and both carry the same validationAttemptId when they belong to the same attempt. Re-validating a document starts a new attempt with a fresh validationAttemptId.

This is a document event, routed to subscriptions by deployment route.

Payload Structure

Response200

{
  "eventId": "evt_valstart_101",
  "eventType": "DOCUMENT_VALIDATION_STARTED",
  "timestamp": "2024-01-15T10:38:00Z",
  "organizationId": "org_xyz789",
  "projectId": "proj_abc123",
  "deploymentId": "dep_123abc",
  "viaDeploymentId": "dpl_prod01",
  "deploymentName": "production",
  "schemaVersionId": "sv_7",
  "extractionSchemaId": "schema_456def",
  "fileId": "file_789ghi",
  "data": {
    "source": "AGENT",
    "scriptCount": 0,
    "agentId": "agent_555",
    "runId": "run_777",
    "validationAttemptId": "cm5attempt001"
  }
}

Payload Fields

Field	Type	Description
`eventId`	string	Unique event identifier. Use for idempotency.
`eventType`	string	Always `"DOCUMENT_VALIDATION_STARTED"`
`timestamp`	ISO 8601	When the attempt was dispatched (UTC)
`organizationId`	string	Your organization identifier
`projectId`	string	The project the document belongs to
`deploymentId`	string	The ID of the model that processed this document
`viaDeploymentId`	string \| null	The ID of the deployment the request arrived through. `null` when the request named the model directly
`deploymentName`	string \| null	The name of that deployment, such as `"production"`. `null` whenever `viaDeploymentId` is `null`
`schemaVersionId`	string \| null	The ID of the frozen schema version the run resolved to. `null` when the deployment tracks the draft schema
`extractionSchemaId`	string	The extraction schema ID of that model
`fileId`	string	The document being validated
`data.source`	`"STATIC"` \| `"AGENT"`	Which validation path was dispatched
`data.scriptCount`	number	Number of enabled static scripts in this attempt. `0` for agent dispatches.
`data.agentId`	string \| null	The validator agent, for `AGENT` dispatches
`data.runId`	string \| null	The agent run, for `AGENT` dispatches
`data.validationAttemptId`	string	Correlates every event of this validation attempt

Correlating the Lifecycle

This event and DOCUMENT_VALIDATION_FAILED are attempt-scoped: both carry the validationAttemptId of the attempt they describe, so pair them by that id.

DOCUMENT_VALIDATED is document-scoped. It reports the whole document -- rules included -- once every lane has settled, so it is not guaranteed to arrive once per started attempt, nor to carry the attempt id you saw here -- after a partial revalidation its top-level validationAttemptId is the newest attempt while data.results still carries entries from older ones.

Delivery is queued, retried and processed concurrently, so receipt order is not state order. Compare timestamp per fileId before overwriting stored state, or re-read the document rather than applying an event blind.

Handling the Event

function handleValidationStarted(event) {
const { fileId, data } = event

markValidationPending(fileId, {
  attemptId: data.validationAttemptId,
  source: data.source,
  scriptCount: data.scriptCount,
})
}