Reusable Schemas

Schemas let events and attributes share validation structures without repeating them. Define them once in schemas/, then reference them by key.

Define a Schema#

description: A non-empty identifier
type: string
minLength: 1

The file path without its extension is the Schema key. Nested paths are supported, so schemas/customer/address.yml has the key customer/address.

Reference a Schema#

Use schema at the root of an event or attribute:

description: User ID
tags: [web]
schema: identifier

References also work inside object properties and array items:

description: Order completed
tags: [backend]
type: object
properties:
  orderId:
    schema: identifier
  customer:
    schema: customer
  relatedIds:
    type: array
    items:
      schema: identifier
required: [orderId, customer]

A Schema can reference another Schema, which makes larger definitions composable:

type: object
properties:
  id:
    schema: identifier
  name:
    type: string
required: [id]

Properties next to schema override the referenced definition at that location. This is useful for a local description or a stricter constraint:

schema: identifier
description: Order ID
minLength: 8

Linting and building#

npx eventvisor lint validates Schema files, missing references, circular references, and the resolved event and attribute structures.

During npx eventvisor build, references are resolved and their definitions are inlined into the datafile. SDKs receive ordinary event and attribute schemas, so no runtime lookup is needed. A Target automatically gets the Schemas required by its selected events and attributes. Schemas are build dependencies and do not need their own include or exclude fields.

TypeScript code generation resolves the same references:

npx eventvisor generate-code --language typescript --out-dir src/eventvisor

Inspecting Schemas#

Schemas are first class project entities:

npx eventvisor list schema
npx eventvisor info schema identifier
npx eventvisor find-usage schema identifier
npx eventvisor lint --entityType schema

The Catalog provides Schema list and detail pages, source history, usage relationships, and Target membership.

Projects using Sets place Schemas in each Set's own schemas/ directory.