> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hookstream.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Schema Validation

Validate incoming payloads against JSON Schema with reject or warn mode.

Schema validation checks every incoming webhook against a JSON Schema you attach to the source. Catch malformed payloads before they hit your destinations — either by rejecting them outright, or by flagging them and letting them through. Hookstream uses [`@cfworker/json-schema`](https://github.com/cfworker/cfworker/tree/main/packages/json-schema), a Workers-native validator with support for Draft 4, 6, and 7 (including `$ref`, `allOf`, `anyOf`, `oneOf`, `pattern`, and `format`).

## Two modes

### Reject mode

Invalid payloads return HTTP `422 Unprocessable Entity` with a `validation_errors` array in the response. The event is **not** stored or delivered. Use this when bad data must never reach your destinations — for example, a billing event that must have a `customer_id`.

### Warn mode

Invalid payloads are accepted and stored, but tagged with `verification_status: "schema_invalid"` so you can spot them in the dashboard. Delivery still happens. Use this during migrations or when you want visibility without blocking production traffic.

## Attach a schema

**Write the schema**

Any JSON Schema Draft 7 document works. Start with the shape you expect and add constraints as you learn more.

    ```json
    {
      "type": "object",
      "required": ["type", "data"],
      "properties": {
        "type": { "type": "string" },
        "data": {
          "type": "object",
          "required": ["id"],
          "properties": {
            "id": { "type": "string" }
          }
        }
      }
    }
    ```
  **Patch the source**

Enable validation and set the action:

    ```bash
    curl -X PATCH https://hookstream.io/v1/sources/src_abc \
      -H "X-API-Key: $HOOKSTREAM_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "schema_validation_enabled": true,
        "schema_action": "reject",
        "json_schema": {
          "type": "object",
          "required": ["type", "data"],
          "properties": {
            "type": { "type": "string" },
            "data": { "type": "object" }
          }
        }
      }'
    ```
  **Test both paths**

Send a valid event (should deliver normally) and an invalid one (should return 422 in reject mode, or arrive with `schema_invalid` in warn mode).

Start in warn mode, leave it for a few days, then audit the `schema_invalid` events in the dashboard. Once you're confident the schema matches real traffic, flip to reject mode.

## Don't have a schema yet? Infer one.

Hookstream's [Instant Database](/concepts/instant-database) can reverse-engineer a schema from live events:

**Create a collection backed by the source**

A collection auto-ingests events through a connection and stores them as records.
  **Wait for a few hundred events**

Schema inference samples up to 200 records to build its types, so the more you send, the more accurate the inferred schema.
  **Fetch the inferred schema**

Call `GET https://hookstream.io/v1/collections/:id/schema`. Copy the result into `json_schema` on the source.

## Next Steps

**[Sources API](/api/sources)**

Schema validation fields on the source schema.
  **[Filters & Transforms](/concepts/filters-transforms)**

Use filter expressions to narrow what reaches each destination.