Skip to main content
Ask your AI

Validate

Source code Package

Checks events against JSON Schema contracts and records a verdict. In pass mode it annotates the event and continues so a downstream step can route on the result. In strict mode it drops invalid events by stopping the chain. The transformer runs on both web and server.

Installation​

npm install @walkeros/transformer-validate
import { startFlow } from '@walkeros/collector';
import { transformerValidate } from '@walkeros/transformer-validate';

await startFlow({
  transformers: {
    validate: {
      code: transformerValidate,
      config: { settings: { contract: [contractWeb], mode: 'strict' } },
    },
  },
});

How it works​

The transformer reads the { ingest, event } context and validates the canonical event. Each contract entry is a constraint: a $contract.<name> reference resolves to the entity-action schemas for the event, an inline JSON Schema applies to the whole event. All entries are AND-ed and every error is aggregated. Set format: true to additionally check the canonical partial event shape (field types and structure): no unknown top-level fields and no unknown keys on a nested entity; user, source, data, globals, custom, context and consent accept extra keys of their value type. Required-field rules come from contract.

mode decides what happens to an invalid event:

  • pass (default): write the verdict to the event and continue. A downstream destination or transformer routes on event.source.valid.
  • strict: record the errors, then stop the chain so the event never reaches downstream steps.

The verdict and the error list are written to two different places. The boolean verdict goes onto the event (output.isValid, default source.valid) as analytics-grade data that travels with the event. The issue list goes onto the ingest (output.errors, default validation) as observer-visible diagnostics, never event data, so it survives even a strict-mode drop. Set either path to an empty string to skip that write.

The transformer never throws. A schema the engine cannot compile or apply (for example an unresolvable $ref) is reported as an issue with level: "error", so pass still forwards the event and strict drops it like an invalid one. A field whose value is undefined counts as absent, as in JSON.

Configuration​

This transformer uses the standard transformer config wrapper (consent, data, env, id, ...). For the shared fields see transformer configuration. Package-specific fields live under config.settings and are listed below.

Settings​

PropertyTypeDescriptionMore
contractArray<object>Validation constraints. Each entry is a resolved $contract.* rule (with entity-action `events` schemas and/or a full-event `schema`) or an inline whole-event JSON Schema. All entries are AND-ed; every error is aggregated.
formatbooleanWhen true, also validate the canonical WalkerOS.Event structural shape (correct field types; no unknown top-level fields and no unknown keys on a nested entity; `user`, `source`, `data`, `globals`, `custom`, `context` and `consent` accept extra keys of their value type). All fields are optional, so this checks structure and types, not presence.
mode'strict' | 'pass'`strict` drops invalid events (chain-stop) after recording errors; `pass` annotates and continues. Default `pass`.
outputoutputWhere the verdict (on the event) and the issue list (on the ingest) are written.
isValidstringEvent dot-path for the boolean verdict. Default `source.valid`. Empty string = skip.
errorsstringIngest dot-path for the issue list. Default `validation`. Empty string = skip.

Mapping​

This package does not define custom rule-level settings. For the standard rule fields (consent, condition, data, batch, name, policy) see mapping.

Examples

Format check accepts custom user keys

With format:true, extra keys on user (segment, ltv) are part of the event model and pass. The verdict source.valid:true is written to the event.

Event
{
  "name": "page view",
  "entity": "page",
  "action": "view",
  "data": {
    "title": "Home"
  },
  "user": {
    "id": "u1",
    "segment": "vip",
    "ltv": 5
  }
}
Out
return {
  "event": {
    "name": "page view",
    "entity": "page",
    "action": "view",
    "data": {
      "title": "Home"
    },
    "user": {
      "id": "u1",
      "segment": "vip",
      "ltv": 5
    },
    "source": {
      "valid": true
    }
  }
}

Filter gtm.* via a contract pattern (real event passes)

The same ^gtm\. rejection contract leaves a real "page view" untouched: it passes and is annotated source.valid:true.

Event
{
  "name": "page view",
  "entity": "page",
  "action": "view"
}
Out
return {
  "event": {
    "name": "page view",
    "entity": "page",
    "action": "view",
    "source": {
      "valid": true
    }
  }
}

Strict validate against a contract (valid)

A "page view" with the required data.title passes the inline contract. The verdict source.valid:true is written to the event; the chain continues.

Event
{
  "name": "page view",
  "entity": "page",
  "action": "view",
  "data": {
    "title": "Home"
  }
}
Out
return {
  "event": {
    "name": "page view",
    "entity": "page",
    "action": "view",
    "data": {
      "title": "Home"
    },
    "source": {
      "valid": true
    }
  }
}

Reference a contract​

The canonical place for event shapes is the top-level contract block. Reference it with $contract.<name>; the bundler resolves the reference to a concrete schema before deploy, so the runtime transformer only ever sees resolved schemas.

In flow-complete.json the server flow's validate step checks every enriched event against the server contract, which extends default with the visitor hash:

/flows/server/transformers/validate
{
  "package": "@walkeros/transformer-validate",
  "config": {
    "settings": {
      "contract": [
        "$contract.server"
      ],
      "mode": "pass"
    }
  },
  "examples": { … }
}
validate checks each event against $contract.server at runtime. Guide chapter contract

The order has everything the server contract asks for, so source.valid is true and the event continues.

Event
{
  "name": "order complete",
  "entity": "order",
  "action": "complete",
  "data": {
    "id": "ORD-100",
    "total": 149.8,
    "currency": "EUR",
    "coupon": "WELCOME10"
  },
  "id": "ev-order-complete",
  "trigger": "load",
  "timestamp": 1700000000000,
  "consent": {
    "functional": true,
    "marketing": true
  },
  "globals": {
    "language": "en",
    "pageGroup": "checkout"
  },
  "user": {
    "device": "d3v1c3",
    "session": "s3ss10n",
    "id": "cust-42",
    "email": "jane@example.com",
    "hash": "5f1c0a9e7d3b2c41",
    "botScore": 0,
    "botCategory": "human",
    "ltv": 420
  },
  "source": {
    "type": "express",
    "platform": "server",
    "url": "https://www.example.com/checkout/thanks"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "SKU-1",
        "name": "Trail Runner",
        "price": 129.9,
        "quantity": 1
      }
    },
    {
      "entity": "product",
      "data": {
        "id": "SKU-2",
        "name": "Running Socks",
        "price": 9.95,
        "quantity": 2
      }
    }
  ]
}
Out
return {
  "event": {
    "name": "order complete",
    "entity": "order",
    "action": "complete",
    "data": {
      "id": "ORD-100",
      "total": 149.8,
      "currency": "EUR",
      "coupon": "WELCOME10"
    },
    "id": "ev-order-complete",
    "trigger": "load",
    "timestamp": 1700000000000,
    "consent": {
      "functional": true,
      "marketing": true
    },
    "globals": {
      "language": "en",
      "pageGroup": "checkout"
    },
    "user": {
      "device": "d3v1c3",
      "session": "s3ss10n",
      "id": "cust-42",
      "email": "jane@example.com",
      "hash": "5f1c0a9e7d3b2c41",
      "botScore": 0,
      "botCategory": "human",
      "ltv": 420
    },
    "source": {
      "type": "express",
      "platform": "server",
      "url": "https://www.example.com/checkout/thanks",
      "valid": true
    },
    "nested": [
      {
        "entity": "product",
        "data": {
          "id": "SKU-1",
          "name": "Trail Runner",
          "price": 129.9,
          "quantity": 1
        }
      },
      {
        "entity": "product",
        "data": {
          "id": "SKU-2",
          "name": "Running Socks",
          "price": 9.95,
          "quantity": 2
        }
      }
    ]
  }
}
Order matches the server contract: example validOrder of step validate. Guide chapter contract

It runs in pass mode, so an invalid event keeps flowing with source.valid: false and the warehouse keeps the violation:

/flows/server/transformers/validate/config/settings/mode: "pass". mode pass marks source.valid instead of dropping, so the warehouse keeps violations; strict is the hard gate. Guide chapter contract

Without user.hash the event breaks the server contract. mode pass keeps it for the warehouse and writes source.valid false; eventFilter keeps it from vendors.

Event
{
  "name": "order complete",
  "entity": "order",
  "action": "complete",
  "data": {
    "id": "ORD-100",
    "total": 149.8,
    "currency": "EUR",
    "coupon": "WELCOME10"
  },
  "id": "ev-order-complete",
  "trigger": "load",
  "timestamp": 1700000000000,
  "consent": {
    "functional": true,
    "marketing": true
  },
  "globals": {
    "language": "en",
    "pageGroup": "checkout"
  },
  "user": {
    "device": "d3v1c3",
    "session": "s3ss10n",
    "id": "cust-42",
    "email": "jane@example.com",
    "botScore": 0,
    "botCategory": "human"
  },
  "source": {
    "type": "express",
    "platform": "server",
    "url": "https://www.example.com/checkout/thanks"
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "SKU-1",
        "name": "Trail Runner",
        "price": 129.9,
        "quantity": 1
      }
    },
    {
      "entity": "product",
      "data": {
        "id": "SKU-2",
        "name": "Running Socks",
        "price": 9.95,
        "quantity": 2
      }
    }
  ]
}
Out
return {
  "event": {
    "name": "order complete",
    "entity": "order",
    "action": "complete",
    "data": {
      "id": "ORD-100",
      "total": 149.8,
      "currency": "EUR",
      "coupon": "WELCOME10"
    },
    "id": "ev-order-complete",
    "trigger": "load",
    "timestamp": 1700000000000,
    "consent": {
      "functional": true,
      "marketing": true
    },
    "globals": {
      "language": "en",
      "pageGroup": "checkout"
    },
    "user": {
      "device": "d3v1c3",
      "session": "s3ss10n",
      "id": "cust-42",
      "email": "jane@example.com",
      "botScore": 0,
      "botCategory": "human"
    },
    "source": {
      "type": "express",
      "platform": "server",
      "url": "https://www.example.com/checkout/thanks",
      "valid": false
    },
    "nested": [
      {
        "entity": "product",
        "data": {
          "id": "SKU-1",
          "name": "Trail Runner",
          "price": 129.9,
          "quantity": 1
        }
      },
      {
        "entity": "product",
        "data": {
          "id": "SKU-2",
          "name": "Running Socks",
          "price": 9.95,
          "quantity": 2
        }
      }
    ]
  }
}
Order without visitor id: example missingHash of step validate. Guide chapter contract

The vendors only get valid events: their shared eventFilter step stops an event whose verdict is false. Use strict instead when invalid events should reach no destination at all.

/flows/server/transformers/eventFilter/next/match/or/2
{
  "key": "event.source.valid",
  "operator": "eq",
  "value": "false"
}
Only events that match the contract reach the vendors. Guide chapter contract

source.valid false (contract broken) is stopped for vendors; the warehouse keeps it.

Event
{
  "name": "order complete",
  "entity": "order",
  "action": "complete",
  "data": {
    "id": "ORD-100",
    "total": 149.8,
    "currency": "EUR",
    "coupon": "WELCOME10"
  },
  "id": "ev-order-complete",
  "trigger": "load",
  "timestamp": 1700000000000,
  "consent": {
    "functional": true,
    "marketing": true
  },
  "globals": {
    "language": "en",
    "pageGroup": "checkout"
  },
  "user": {
    "device": "d3v1c3",
    "session": "s3ss10n",
    "id": "cust-42",
    "email": "jane@example.com",
    "hash": "5f1c0a9e7d3b2c41",
    "botScore": 0,
    "botCategory": "human",
    "ltv": 420
  },
  "source": {
    "type": "express",
    "platform": "server",
    "url": "https://www.example.com/checkout/thanks",
    "valid": false
  },
  "nested": [
    {
      "entity": "product",
      "data": {
        "id": "SKU-1",
        "name": "Trail Runner",
        "price": 129.9,
        "quantity": 1
      }
    },
    {
      "entity": "product",
      "data": {
        "id": "SKU-2",
        "name": "Running Socks",
        "price": 9.95,
        "quantity": 2
      }
    }
  ]
}
Out
return false
Invalid event stopped: example invalidStopped of step eventFilter. Guide chapter contract

Add format: true to also check the canonical event shape, and output to move the verdict (isValid, default source.valid) or the issue list (errors, default validation).

Filter unwanted events​

There is no separate ignore or filter setting. To drop unwanted events (for example GTM lifecycle pings like gtm.js / gtm.dom), author an inline schema that rejects them and run mode: "strict". A schema where name must NOT match ^gtm\. fails those events while real events pass.

"validate": {
  "package": "@walkeros/transformer-validate",
  "config": { "settings": {
    "contract": [{ "type": "object", "properties": { "name": { "not": { "pattern": "^gtm\\." } } } }],
    "mode": "strict"
  } }
}

Limitations​

  • The error list may contain an extra parent entry pointing at a properties wrapper per failure, a quirk of the underlying JSON Schema engine. The isValid verdict is unaffected: it is false exactly when there is at least one failure.
  • Issues are emitted at level: "error"; there is no warn level.
  • flow_simulate does not run a source's policy and next chain, so a green simulation does not prove a validate step placed there.

Next steps​

💡 Need implementation support?
elbwalker offers hands-on support: setup review, measurement planning, destination mapping, and live troubleshooting. Book a 2-hour session (€399)