:hedgehog: PostHog is the leading platform for building self-driving products. Our developer tools – AI observability, analytics, session replay, flags, experiments, error tracking, logs, and more – capture all the context agents need to diagnose problems, uncover opportunities, and ship fixes. Steer it all from Slack, web, desktop, or the MCP.
Python ab-testingai-analyticsanalyticscdpdata-warehouseexperimentsfeature-flagsjavascriptproduct-analyticspythonreactsession-replaysurveystypescriptweb-analytics
import { EventSchemaEnforcementManager } from '~/common/utils/event-schema-enforcement-manager'
import { PipelineResultType, drop, ok } from '~/ingestion/framework/results'
import { EventSchemaEnforcement, Team } from '~/types'
import { createValidateEventSchemaStep, validateEventAgainstSchema } from './validate-event-schema'
/** Creates a mock EventSchemaEnforcementManager that returns the provided schemas for any team */
function createMockSchemaManager(schemas: EventSchemaEnforcement[]): EventSchemaEnforcementManager {
// Convert array to Map keyed by event_name for O(1) lookups
const schemaMap = new Map(schemas.map((s) => [s.event_name, s]))
return {
getSchemas: jest.fn().mockResolvedValue(schemaMap),
getSchemasForTeams: jest.fn().mockResolvedValue({}),
} as unknown as EventSchemaEnforcementManager
}
describe('validateEventAgainstSchema', () => {
// Note: The schema only includes required_properties since optional properties
// are filtered out at the database query level for performance.
describe('missing required fields', () => {
it.each([
['undefined', undefined],
['null', null],
])('should reject when required property is %s', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['required_prop', ['String']]]),
}
const result = validateEventAgainstSchema({ required_prop: value }, schema)
expect(result.valid).toBe(false)
expect(result.errors).toHaveLength(1)
expect(result.errors[0]).toEqual({
propertyName: 'required_prop',
reason: 'missing_required',
})
})
it('should reject when required property is missing from properties object', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['required_prop', ['String']]]),
}
const result = validateEventAgainstSchema({}, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].reason).toBe('missing_required')
})
it('should reject when properties object is undefined', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['required_prop', ['String']]]),
}
const result = validateEventAgainstSchema(undefined, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].reason).toBe('missing_required')
})
it('should report multiple missing required fields', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([
['field1', ['String']],
['field2', ['Numeric']],
['field3', ['Boolean']],
]),
}
const result = validateEventAgainstSchema({}, schema)
expect(result.valid).toBe(false)
expect(result.errors).toHaveLength(3)
})
})
describe('String type coercion', () => {
it.each([
['string', 'hello'],
['number', 42],
['boolean', true],
['object', { foo: 'bar' }],
['array', [1, 2, 3]],
])('should accept %s as String', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['String']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(true)
})
})
describe('Numeric type coercion', () => {
it.each([
['integer', 42],
['float', 3.14],
['negative number', -10],
['zero', 0],
['numeric string', '42'],
['negative numeric string', '-10'],
['float string', '3.14'],
])('should accept %s as Numeric', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['Numeric']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(true)
})
it.each([
['non-numeric string', 'hello'],
['empty string', ''],
['whitespace string', ' '],
['object', { foo: 'bar' }],
['array', [1, 2, 3]],
['boolean true', true],
['boolean false', false],
['Infinity', Infinity],
['-Infinity', -Infinity],
['NaN', NaN],
['string "Infinity"', 'Infinity'],
['string "-Infinity"', '-Infinity'],
['string "NaN"', 'NaN'],
])('should reject %s as Numeric', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['Numeric']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].reason).toBe('type_mismatch')
})
})
describe('Boolean type coercion', () => {
it.each([
['true', true],
['false', false],
['string "true"', 'true'],
['string "false"', 'false'],
])('should accept %s as Boolean', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['Boolean']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(true)
})
it.each([
['number 1', 1],
['number 0', 0],
['string "yes"', 'yes'],
['string "no"', 'no'],
['string "TRUE"', 'TRUE'],
['string "FALSE"', 'FALSE'],
['string "True"', 'True'],
['string "False"', 'False'],
['object', {}],
['array', []],
])('should reject %s as Boolean', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['Boolean']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].reason).toBe('type_mismatch')
})
})
describe('DateTime type coercion', () => {
it.each([
['unix timestamp', 1609459200],
['ISO string', '2021-01-01T00:00:00Z'],
['ISO string with offset', '2021-01-01T00:00:00+00:00'],
['date string', '2021-01-01'],
])('should accept %s as DateTime', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['DateTime']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(true)
})
it.each([
['invalid date string', 'not-a-date'],
['object', {}],
['array', []],
['boolean', true],
])('should reject %s as DateTime', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['DateTime']]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].reason).toBe('type_mismatch')
})
})
describe.each(['Object', 'Array'])('%s type coercion', (propertyType) => {
const objectCases: [string, unknown][] = [
['plain object', { foo: 'bar' }],
['empty object', {}],
]
const arrayCases: [string, unknown][] = [
['array', [1, 2, 3]],
['empty array', []],
['mixed array', [1, 'two', null, { nested: [true] }]],
]
const primitiveCases: [string, unknown][] = [
['string', 'hello'],
['number', 42],
['boolean', true],
]
const acceptCases = propertyType === 'Object' ? [...objectCases, ...arrayCases] : arrayCases
const rejectCases = propertyType === 'Object' ? primitiveCases : [...objectCases, ...primitiveCases]
it.each(acceptCases)('should accept %s', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', [propertyType]]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(true)
})
it.each(rejectCases)('should reject %s', (_, value) => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', [propertyType]]]),
}
const result = validateEventAgainstSchema({ prop: value }, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].reason).toBe('type_mismatch')
})
})
describe('multiple required properties', () => {
it('should accept when all required properties pass validation', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([
['name', ['String']],
['age', ['Numeric']],
]),
}
const result = validateEventAgainstSchema({ name: 'alice', age: 30 }, schema)
expect(result.valid).toBe(true)
})
it('should reject when one of multiple required properties fails', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([
['name', ['String']],
['age', ['Numeric']],
]),
}
const result = validateEventAgainstSchema({ name: 'alice', age: 'not-a-number' }, schema)
expect(result.valid).toBe(false)
expect(result.errors).toHaveLength(1)
expect(result.errors[0].propertyName).toBe('age')
})
})
describe('multi-type properties', () => {
it('should accept value matching any of the listed types', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['String', 'Numeric']]]),
}
expect(validateEventAgainstSchema({ prop: 'hello' }, schema).valid).toBe(true)
expect(validateEventAgainstSchema({ prop: 42 }, schema).valid).toBe(true)
})
it('should reject value matching none of the listed types', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['Numeric', 'Boolean']]]),
}
const result = validateEventAgainstSchema({ prop: { nested: true } }, schema)
expect(result.valid).toBe(false)
expect(result.errors[0].expectedTypes).toEqual(['Numeric', 'Boolean'])
})
})
describe('unknown types', () => {
it('should allow values for unknown property types', () => {
const schema: EventSchemaEnforcement = {
event_name: 'test_event',
required_properties: new Map([['prop', ['UnknownType']]]),
}
const result = validateEventAgainstSchema({ prop: 'anything' }, schema)
expect(result.valid).toBe(true)
})
})
})
describe('createValidateEventSchemaStep', () => {
const createInput = (eventName: string, properties: Record<string, unknown> | undefined) => ({
event: {
event: eventName,
distinct_id: 'user123',
team_id: 1,
uuid: '123e4567-e89b-12d3-a456-426614174000',
ip: '127.0.0.1',
site_url: 'https://example.com',
now: '2021-01-01T00:00:00Z',
properties,
},
team: {
id: 1,
name: 'Test Team',
} as unknown as Team,
})
it('should pass events that violate an enforced schema when enforcement is disabled', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'test_event',
required_properties: new Map([['required_prop', ['String']]]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, false)
const input = createInput('test_event', {})
const result = await step(input)
expect(result).toEqual(ok(input))
})
it('should pass events when team has no enforced schemas', async () => {
const mockManager = createMockSchemaManager([])
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', { prop: 'value' })
const result = await step(input)
expect(result).toEqual(ok(input))
})
it('should pass events that have no matching schema', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'other_event',
required_properties: new Map([['required_prop', ['String']]]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', {})
const result = await step(input)
expect(result).toEqual(ok(input))
})
it('should pass events that match schema requirements', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'test_event',
required_properties: new Map([['required_prop', ['String']]]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', { required_prop: 'hello' })
const result = await step(input)
expect(result).toEqual(ok(input))
})
it('should drop events missing required properties', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'test_event',
required_properties: new Map([['required_prop', ['String']]]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', {})
const result = await step(input)
expect(result).toEqual(
drop(
'schema_validation_failed',
[],
[
{
type: 'schema_validation_failed',
details: {
eventUuid: '123e4567-e89b-12d3-a456-426614174000',
eventName: 'test_event',
distinctId: 'user123',
errors: [
{
property: 'required_prop',
reason: 'missing_required',
expectedTypes: undefined,
actualValue: undefined,
},
],
},
},
]
)
)
})
it('should drop events with type mismatch on required properties', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'test_event',
required_properties: new Map([['numeric_prop', ['Numeric']]]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', { numeric_prop: 'not-a-number' })
const result = await step(input)
expect(result).toEqual(
drop(
'schema_validation_failed',
[],
[
{
type: 'schema_validation_failed',
details: {
eventUuid: '123e4567-e89b-12d3-a456-426614174000',
eventName: 'test_event',
distinctId: 'user123',
errors: [
{
property: 'numeric_prop',
reason: 'type_mismatch',
expectedTypes: ['Numeric'],
actualValue: 'not-a-number',
},
],
},
},
]
)
)
})
it('should include multiple errors in warning details', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'test_event',
required_properties: new Map([
['field1', ['String']],
['field2', ['Numeric']],
]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', { field2: 'not-numeric' })
const result = await step(input)
expect(result.type).toBe(PipelineResultType.DROP)
if (result.type === PipelineResultType.DROP) {
expect(result.warnings[0].details.errors).toHaveLength(2)
}
})
it('should stringify object values in error details', async () => {
const schemas: EventSchemaEnforcement[] = [
{
event_name: 'test_event',
required_properties: new Map([['prop', ['Boolean']]]),
},
]
const mockManager = createMockSchemaManager(schemas)
const step = createValidateEventSchemaStep(mockManager, true)
const input = createInput('test_event', { prop: { nested: 'object' } })
const result = await step(input)
expect(result.type).toBe(PipelineResultType.DROP)
if (result.type === PipelineResultType.DROP) {
expect(result.warnings[0].details.errors[0].actualValue).toBe('{"nested":"object"}')
}
})
})