Document Validation Started Event

The DOCUMENT_VALIDATION_STARTED event fires when a 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.

When It Triggers

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",
  "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 model or deployment that processed this document
`extractionSchemaId`	string	The extraction schema ID of that model or deployment
`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 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,
})
}