Channel Schemas

Define JSON schemas for your channels to validate every event payload before it reaches subscribers. Invalid events are rejected with a 400 error, keeping your data clean at the transport layer.

Defining a Schema

Go to your app dashboard, open Schemas, and click New Schema. Each schema targets a channel pattern and event name.

{
    "channel": "private-orders",
    "event": "order.created",
    "schema": {
        "type": "object",
        "required": ["order_id", "amount", "currency"],
        "properties": {
            "order_id": { "type": "string" },
            "amount": { "type": "number", "minimum": 0 },
            "currency": { "type": "string", "enum": ["USD", "EUR", "GBP"] }
        },
        "additionalProperties": false
    }
}

Schemas follow the JSON Schema draft-2020-12 spec.

Wildcard Channel Patterns

Use * to match multiple channels:

Managing Schemas via API

Create or update a schema:

curl -X PUT https://your-relay-host.com/api/v1/apps/YOUR_APP_ID/schemas \
  -H "Authorization: Bearer YOUR_APP_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "channel": "private-orders",
    "event": "order.created",
    "schema": {
        "type": "object",
        "required": ["order_id", "amount"],
        "properties": {
            "order_id": { "type": "string" },
            "amount": { "type": "number" }
        }
    }
  }'

List all schemas:

curl https://your-relay-host.com/api/v1/apps/YOUR_APP_ID/schemas \
  -H "Authorization: Bearer YOUR_APP_TOKEN"

Delete a schema:

curl -X DELETE https://your-relay-host.com/api/v1/apps/YOUR_APP_ID/schemas/SCHEMA_ID \
  -H "Authorization: Bearer YOUR_APP_TOKEN"

Validation Modes

Configure how the server handles invalid payloads:

• Strict (default) — reject the event with a 400 response
• Warn — accept the event but log a validation warning in the Debug Console
• Permissive — accept the event, no warning (useful during migration)

Set the mode per schema in the dashboard or via the mode field in the API.

Error Response

When an event fails validation in strict mode:

{
    "error": "schema_validation_failed",
    "message": "Event payload does not match schema for 'order.created' on 'private-orders'",
    "violations": [
        { "path": "/currency", "message": "is not one of: USD, EUR, GBP" }
    ]
}