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.

Only top-level defaults: leaves are ExprStr; values nested inside an object or array default are emitted as literal text. (This is the inverse of state:, where nested leaves do evaluate.)

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

splunk

Splunk-specific delivery identity for this surface, namespaced under splunk: so the otherwise vendor-neutral event-type schema doesn't read as Splunk-only.

source and sourcetype are both intrinsic to the data — they describe what Splunk parses the event as and where it came from, so they travel with each event. This is what lets a single HEC pipeline carry every event type: the sink stamps the per-event values on emit and falls back to the pipeline's static value only when the event field is omitted. Only host and index remain destination concerns configured on the pipeline, not the event surface.

The value is an ExprStr resolved per emit against the event's own merged fields, so it can be a literal or interpolate a payload field for per-event sub-typing:

# Literal — every event of this type shares one sourcetype
splunk:
  sourcetype: aws:cloudtrail

# Interpolated — sub-type per event from a payload field
splunk:
  sourcetype: "o365:${ref.Workload}"   # → o365:Exchange, o365:AzureActiveDirectory, …

# Windows — source interpolated from the channel field, sourcetype fixed
splunk:
  source: "XmlWinEventLog:${ref.System.Channel}"
  sourcetype: XmlWinEventLog

pool.* draws are rejected (they would materialize a fresh value on every event). Only ${ref.*} interpolation against the event fields and the other non-pool ExprStr forms are allowed.

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.