Metadata Schema

Define strict JSON Schema for validating event metadata.

Define metadata schemas to attach structured custom data to Audit Log events. Schemas enforce type safety and data consistency – events that do not match the provided schema return an error.

To add a schema, check the “Require metadata schema validation” checkbox when creating an event schema. This opens the schema editor where you can modify the underlying JSON Schema for all metadata objects.

A screenshot showing how to require metadata schema validation in the WorkOS Dashboard.

Locate the metadata objects at the root of the event and within actor and targets objects. Each can contain a unique JSON Schema. Click the ”+” sign to add to a metadata object.

Metadata objects have a limit of 50 keys. Key names can be up to 40 characters long, and values can be up to 500 characters long.

A screenshot showing the schema editor in the WorkOS Dashboard.

Event with metadata

 import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.auditLogs.createEvent('org_01EHWNCE74X7JSDV0X3SZ3KJNY', {
  action: 'user.signed_in',
  occurredAt: new Date(),
  actor: {
    type: 'user',
    id: 'user_01GBNJC3MX9ZZJW1FSTF4C5938',
    metadata: {
      role: 'admin',
    },
  },
  targets: [
    {
      type: 'team',
      id: 'team_01GBNJD4MKHVKJGEWK42JNMBGS',
      metadata: {
        owner: 'user_01GBTCQ2MZG9C87R7NAQZZS7M6',
      },
    },
  ],
  context: {
    location: '123.123.123.123',
    userAgent: 'Chrome/104.0.0.0',
  },
  metadata: {
    environment: 'staging',
  },
});