Event Type Schema

Complete field reference for event-type configuration files. For conceptual overview, see event types in scenario concepts.

IDE Integration

Add this directive to the top of your YAML file for autocomplete and validation:

# yaml-language-server: $schema=https://tracemill.dev/schemas/event-type.schema.json

Properties

schema

A JSON Schema (draft 2020-12 recommended) describing the event payload structure. The engine validates every emitted event against this schema after merging defaults and scenario fields.

The schema can include required, properties, additionalProperties, and any other standard JSON Schema keywords.

defaults

Default field values merged into every event of this type before scenario fields are applied. Scenario fields override defaults. ExprStr values (generators, refs) are supported.

defaults:
  eventVersion: "1.08"
  eventTime: gen.timestamp()
  eventSource: sts.amazonaws.com

correlation

Declares dotted payload paths that together uniquely identify a generated event instance in the SIEM. Required on every event type.

Each entry is a dotted path into the event payload. When the event is persisted, the engine walks nested maps using these paths to extract the value, and the trailing segment of the path becomes the stored map key:

Pick paths whose trailing segment matches the field name your SIEM exposes after ingestion. The TA uses the stored map to search the SIEM, and the platform uses run_events.id (a stable UUID) as the reference key for reporting results back.

# Single field — native UUID
correlation: [eventID]

# Composite — network event without a native ID
correlation: [srcaddr, dstaddr, srcport, dstport, protocol]

# Nested — Windows/Sysmon events (stored keys: Computer, Channel, EventRecordID)
correlation: [System.Computer, System.Channel, System.EventRecordID]

Constraints:

• The declared paths must resolve against the payload produced by the scenario. If any intermediate map is missing or any leaf is empty, the event's correlation map is null and the event is excluded from the validation manifest.
• No two paths may share the same trailing segment. The registry rejects event types where, for example, System.Name and EventData.Name would both key as Name — pick paths with distinct leaves.
• The declared paths must survive SIEM ingestion pipelines unchanged. Do not use tracemill_* envelope fields — they may be stripped by some ingestion tools.

Example

type: event-type
id: aws.cloudtrail
version: v1
full_name: AWS CloudTrail Management Event

timestamp: eventTime
correlation: [eventID]

defaults:
  eventVersion: "1.08"
  eventTime: gen.timestamp()

schema:
  $schema: https://json-schema.org/draft/2020-12/schema
  type: object
  required: [eventID, eventTime, eventSource, eventName]
  properties:
    eventID:
      type: string
    eventTime:
      type: string
    eventSource:
      type: string
    eventName:
      type: string
  additionalProperties: true

Events are referenced in scenarios by id@version (e.g. aws.cloudtrail@v1) or bare id (resolves to the latest loaded version). The engine auto-discovers event types from event-types/ directories in the content hierarchy (project > user > library). An emit step that references an unknown event type is a hard error when event types are available.