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 requiredThat 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; // trueAdditive 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 undefinedformatIssues 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.