AI Worker worker.md

Data Validation Worker

Problem: Validate incoming records against rules and return structured validation errors.

This example follows the core principles described in the AI Worker Design Patterns and uses the standard Worker Protocol schema.

Key ideas#

  • Keep the worker single-purpose and explicit about inputs and outputs.
  • Put hard limits in the contract (timeout, retries, tools allowed).
  • Make failures machine-actionable with stable error codes.
  • Emit structured signals so orchestrators can route, retry, or escalate.

Diagram#

records -> validate -> {valid, errors, normalized?}

Worker spec#

worker_id: data-validation-worker
version: 1.0
purpose: Validate incoming records against rules and return structured validation errors.
inputs:
  - records: array
  - ruleset_id: string
  - schema_name: string
outputs:
  - valid: boolean
  - errors: array
  - normalized: array (optional)
constraints:
  timeout_seconds: 60
  max_tokens: 1500
  tools_allowed: [json_schema_validate, rules_engine]
retries:
  max_attempts: 2
  backoff: exponential
observability:
  trace_id: required
  log_fields: [worker_id, attempt, duration_ms]

Input schema#

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": false,
  "properties": {
    "records": {
      "type": "array"
    },
    "ruleset_id": {
      "type": "string"
    },
    "schema_name": {
      "type": "string"
    }
  },
  "required": [
    "records",
    "ruleset_id",
    "schema_name"
  ]
}

Output schema#

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "valid": {
      "type": "boolean"
    },
    "errors": {
      "type": "array"
    },
    "normalized": {
      "type": "array"
    }
  }
}

Constraints#

{
  "timeout_seconds": 60,
  "max_tokens": 1500,
  "retries": {
    "max_attempts": 2,
    "backoff": "exponential"
  },
  "rate_limit": "per-tenant (example: 10/min)",
  "tools_allowed": [
    "json_schema_validate",
    "rules_engine"
  ]
}

Failure modes & handling#

  • Schema not found: error_code=schema_missing.
  • Rules engine timeout: error_code=rules_timeout, retryable=true.
  • Malformed record: include a pointer path and stable error codes per field.

Observability signals#

  • logs: worker_id, attempt, duration_ms, status, error_code
  • metrics: success_count, failure_count, retry_count, p95_duration_ms
  • trace fields: trace_id, span_id, upstream_request_id (if present)

See also#

FAQ#

Should the worker return partial results on failure?

If partial results are safe and useful, return them with a stable status and error_code. Otherwise fail fast and let orchestration decide.

Where should large artifacts go?

Store them externally (object storage or DB) and return a reference (URL or artifact ID) in the response.

How should I choose timeouts?

Set a hard ceiling based on SLOs and queue backpressure. Prefer smaller workers with tighter timeouts over monolith workers.