Augeo AI Docs
Events Dictionary

Validating events

Check a document against the contract at a boundary, with Zod schemas generated from it.

The function you want

import {
  validateAugeoEvent,
  formatIssues,
} from "@kigo-digital/augeo-events/validate";

const result = validateAugeoEvent(incoming);
if (!result.valid) {
  throw new Error(formatIssues(result.issues));
}

Why validating an event is two checks

The envelope constrains everything except data.occurrence. The occurrence is selected by type plus typeversion and validated against its own schema.

So a consumer that runs only the envelope check accepts any payload at all:

import {
  validateEnvelope,
  validateAugeoEvent,
} from "@kigo-digital/augeo-events/validate";

const event = {
  /* a well-formed envelope */
  type: "com.augeo.ui.component.viewed",
  data: { occurrence: { componentName: "product_card" }, context: {} },
  /* … */
};

validateEnvelope(event).valid; // true  — the envelope is fine
validateAugeoEvent(event).valid; // false — exposureMs is required

That is the most common way a consumer believes it is conformant when it is not, and it is why validateAugeoEvent exists rather than leaving the two calls to you.

An unregistered type fails here too, rather than being skipped. A validator that shrugs at an unknown name is a validator that lets one through.

The rest of the surface

import {
  validateAugeoEvent, // envelope + occurrence — use this
  validateEnvelope, // envelope only
  validateOccurrence, // one occurrence, by name
  validateAck, // augeo.ack
  validateState, // augeo.state
  validateCloudEvent, // the CloudEvents form
  isAugeoEvent, // narrowing predicate
  assertAugeoEvent, // throws, listing every failure
  formatIssues,
} from "@kigo-digital/augeo-events/validate";

validateOccurrence takes just a name and an occurrence — there is exactly one schema per name, so there is no typeversion parameter to pass it.

validateOccurrence("com.augeo.preference.quiz.step.completed", occurrence);

Version rejection happens one level up, in validateAugeoEvent. It reads typeversion off the event and resolves the schema $id that name-and-version would select, purely to refuse a typeversion the name does not support — then validates the occurrence against the current schema regardless.

Extra properties are accepted, on purpose

validateOccurrence("com.augeo.ui.component.viewed", {
  componentName: "product_card",
  exposureMs: 10,
  somethingAddedLater: true,
}).valid; // true

Additive evolution requires it: a consumer validating against a pinned copy must not reject a field a later version added. No schema in the dictionary closes additionalProperties, and CI refuses one that tries.

The TypeScript types are stricter than the validator here, and deliberately so. Excess-property checking bites on object literals — exactly where you want it, when an emitter typos a field — while a parsed JSON object still assigns structurally.

How validation is built

The JSON Schema is the artifact of record — it has to serve Go and Python consumers as well as browsers. From it, codegen emits Zod schemas, and the TypeScript types are inferred from those with z.infer.

That is one artifact rather than two. The alternative — a JSON Schema validator plus a separately generated type mirror — gives you two representations of the same schema that can disagree, and a second dependency to keep the first honest.

Zod is confined to this entry point. The root and /registry entries carry types and registry data and import no validator at all, so a design system that only emits correctly typed events ships none of it. If your app already uses Zod — and across this org it does — the marginal cost here is the schema definitions themselves.

This entry point validates; it does not transform

Nothing here returns parsed data, only a verdict and its issues.

That is a deliberate boundary. The generated schemas accept unknown keys but strip them from parsed output, so returning that output would silently drop a field a newer emitter added — the exact additive-evolution failure the open schemas exist to prevent. You already have the document; you passed it in.

Issues

result.issues is a stable shape of this package's own — { path, code, message } — rather than the validator's native error type. The validator is an implementation detail, and your error handling should not have to change because it moved.

Occurrence issues carry a path prefixed with /data/occurrence, so a merged report says which half failed:

/data/occurrence/exposureMs: Invalid input: expected number, received undefined

formatIssues renders one per line. assertAugeoEvent throws with all of them rather than the first, because an emitter being corrected wants the whole list.

Bringing your own validator

The raw schemas ship with the package. Swap the host in a $id for the package name:

// https://schemas.augeo.com/ui/component.viewed/1.json
import schema from "@kigo-digital/augeo-events/schemas/ui/component.viewed/1.json";

Or take them all as objects:

import { SCHEMAS, occurrenceSchema } from "@kigo-digital/augeo-events/schemas";

Register every schema under its own $id before compiling anything — all $refs are absolute https://schemas.augeo.com/… URIs and nothing resolves over the network.