Chapter 2: Bringing Data In

Fail-Fast Validation

In traditional automation platforms, if an external system sends malformed data (like missing a required client email, or sending text where a number is expected), the workflow often proceeds anyway. It eventually fails deep in the pipeline—or worse, generates a broken, unprofessional PDF.

Strucsta takes a different approach: Fail-Fast Validation.

We act as a strict gatekeeper at the very edge of your pipeline. Before a single AI credit is spent, and before any rendering logic is executed, incoming data must prove it belongs there.

How the Gatekeeper Works

When you build a workflow using the Blueprint Engine, or manually configure a Source step, you define an Expected JSON Schema. This schema dictates exactly what fields are required, their data types (string, number, boolean, array), and any specific formatting rules.

When a payload arrives via Webhook or API, it is immediately tested against this schema.

1. The "Happy Path" (Success)

If the incoming data perfectly matches your schema:

• Strucsta accepts the payload.
• Your endpoint returns an immediate 202 Accepted (or 200 OK).
• The system provisions a new Run and securely passes the data to the AI Reasoning engine.

2. The "Fail-Fast" Path (Rejection)

If the incoming data violates the schema—for instance, missing a highly critical contractValue field—the pipeline is immediately halted.

• Strucsta outright rejects the payload.
• No Run is created, meaning zero AI credits are consumed.
• The endpoint returns a 400 Bad Request.

Developer-Friendly Error Responses

When a payload is rejected, we don't just return a generic error. Strucsta responds with a detailed, developer-friendly JSON payload that pinpoints exactly which fields failed and why. This makes debugging external integrations (like Zapier, HubSpot, or custom code) incredibly fast.

Example Error Response:

{
  "error": "Validation Failed",
  "status": 400,
  "message": "The incoming payload did not match the expected schema.",
  "issues": [
    {
      "field": "clientEmail",
      "expected": "string (email)",
      "received": "undefined",
      "message": "Required field 'clientEmail' is missing."
    },
    {
      "field": "contractValue",
      "expected": "number",
      "received": "string",
      "message": "Expected a number, but received '5000' (string)."
    }
  ]
}

Why Strict Validation Matters

1. Cost Protection: LLM calls are the most expensive part of document orchestration. By failing fast, we ensure you never pay OpenAI or Anthropic to process garbage data.
2. Template Safety: Your JSONC templates rely on specific variables existing to render tables and conditional logic. Strict validation guarantees your templates will never crash due to an undefined variable.
3. Brand Integrity: It is better to have a document generation fail quietly in the background (alerting your IT team) than to successfully deliver a legal contract to a client that says "Dear [undefined]".