id: segment-event-taxonomy-validator
namespace: company.team
description: |
Validate Segment event batches against a naming and property contract:
webhook payloads are normalized into events, checked for lowercase
snake_case names, the track_ prefix, and typed properties, then
violations escalate as a GitHub issue and a Slack digest while clean
batches log quietly.
triggers:
- id: segment_webhook
type: io.kestra.plugin.core.trigger.Webhook
description: Segment (Webhooks destination, source function, or HTTP API call)
POSTs an event batch here; the key segment guards the URL.
key: "{{ secret('SEGMENT_WEBHOOK_KEY') }}"
- id: daily_digest
type: io.kestra.plugin.core.trigger.Schedule
description: Disabled daily sweep that validates the built-in sample batch, so
the contract can be rehearsed on a schedule once enabled.
cron: "0 6 * * *"
disabled: true
inputs:
- id: environment
type: STRING
defaults: production
description: Environment label carried into the report, the GitHub issue title,
and the Slack digest.
- id: issue_repository
type: STRING
defaults: your-org/analytics-contracts
description: GitHub repository in owner/repo form that receives the taxonomy
violation issue.
- id: sample_limit
type: INT
defaults: 200
description: Maximum number of events validated per batch, so one oversized
payload cannot blow up the report.
tasks:
# --- 1. extract the event batch ---
- id: extract_events
type: io.kestra.plugin.scripts.python.Script
description: Turn the webhook body into a normalized event batch, falling back
to a built-in sample when the run came from the schedule trigger.
taskRunner:
type: io.kestra.plugin.core.runner.Process
env:
BODY: "{{ trigger.body ?? '' }}"
SAMPLE_LIMIT: "{{ inputs.sample_limit }}"
script: |
import json
import os
SAMPLE_BATCH = [
{"type": "track", "event": "track_page_viewed",
"properties": {"page_path": "/pricing", "referrer": "email"}},
{"type": "track", "event": "track_signup_completed",
"properties": {"plan": "pro", "seats": 3, "invited_team": True}},
{"type": "track", "event": "track_order_completed",
"properties": {"order_id": "o-1001", "amount": 2500, "express": False}},
]
raw = (os.environ.get("BODY") or "").strip()
source = "webhook"
parse_error = ""
events = []
if not raw:
events = [dict(e) for e in SAMPLE_BATCH]
source = "sample"
else:
try:
doc = json.loads(raw)
except ValueError as exc:
parse_error = "body is not valid JSON (%s)" % exc
doc = None
if not parse_error:
if isinstance(doc, list):
events = [e for e in doc if isinstance(e, dict)]
if len(events) != len(doc):
parse_error = "batch contains entries that are not objects"
elif isinstance(doc, dict):
batch = doc.get("batch")
if isinstance(batch, list):
events = [e for e in batch if isinstance(e, dict)]
if len(events) != len(batch):
parse_error = "batch contains entries that are not objects"
elif isinstance(doc.get("event"), str) or isinstance(doc.get("name"), str) or "type" in doc:
events = [doc]
else:
parse_error = "object body has no event, name, or batch field"
else:
parse_error = "body is neither an object nor an array"
try:
limit = int(os.environ.get("SAMPLE_LIMIT") or "200")
except ValueError:
limit = 200
if limit > 0:
events = events[:limit]
names = []
for event in events:
label = event.get("event") or event.get("name") or "unnamed"
names.append(str(label))
payload = {"outputs": {
"source": source,
"event_count": len(events),
"event_names": names,
"events_json": json.dumps(events, sort_keys=True),
"parse_error": parse_error,
}}
print("segment batch: %d event(s) from %s" % (len(events), source))
print("::" + json.dumps(payload) + "::")
# --- 2. check the taxonomy contract ---
- id: check_taxonomy
type: io.kestra.plugin.scripts.python.Script
description: Apply the taxonomy contract (naming regex, track_ prefix, required
properties with declared types) and group every breach by rule for the
branch below.
taskRunner:
type: io.kestra.plugin.core.runner.Process
env:
EVENTS: "{{ outputs.extract_events.vars.events_json }}"
PARSE_ERROR: "{{ outputs.extract_events.vars.parse_error }}"
ENVIRONMENT: "{{ inputs.environment }}"
script: |
import json
import os
import re
from collections import Counter
NAME_RE = re.compile(r"^[a-z][a-z0-9]*(_[a-z0-9]+)*$")
CONTRACT = {
"track_page_viewed": {"page_path": "string", "referrer": "string"},
"track_signup_completed": {"plan": "string", "seats": "int", "invited_team": "bool"},
"track_order_completed": {"order_id": "string", "amount": "int", "express": "bool"},
"identify_profile_updated": {"plan": "string", "seats": "int"},
"page_marketing_viewed": {"path": "string", "referrer": "string"},
}
def type_ok(value, expected):
if expected == "string":
return isinstance(value, str)
if expected == "int":
return isinstance(value, int) and not isinstance(value, bool)
if expected == "bool":
return isinstance(value, bool)
return True
def clean(text):
return str(text).replace('"', "").replace("\\", "").replace("\n", " ").strip()
env_name = os.environ.get("ENVIRONMENT") or "unknown"
batch_error = (os.environ.get("PARSE_ERROR") or "").strip()
raw_events = os.environ.get("EVENTS")
events = None
if raw_events is None:
batch_error = batch_error or "events payload missing from the previous task"
else:
try:
parsed = json.loads(raw_events)
except ValueError as exc:
batch_error = batch_error or "events payload is not valid JSON (%s)" % exc
else:
if isinstance(parsed, list):
events = parsed
else:
batch_error = batch_error or "events payload is not a JSON array"
violations = []
unknown_names = []
event_count = 0
if batch_error:
violations.append({"rule": "malformed_batch", "event": "", "detail": batch_error})
elif events:
event_count = len(events)
for event in events:
if not isinstance(event, dict):
violations.append({"rule": "malformed_batch", "event": "", "detail": "batch entry is not an object"})
continue
name = str(event.get("event") or event.get("name") or "").strip()
if not name:
violations.append({"rule": "missing_name", "event": "unnamed", "detail": "event carries no event or name field"})
continue
if not NAME_RE.match(name):
violations.append({"rule": "naming", "event": name, "detail": "name is not lowercase snake_case"})
etype = str(event.get("type") or "").lower()
if etype == "track" and not name.startswith("track_"):
violations.append({"rule": "track_prefix", "event": name, "detail": "track events must start with track_"})
props = event.get("properties", {})
if name in CONTRACT:
if not isinstance(props, dict):
violations.append({"rule": "missing_property", "event": name, "detail": "properties field is not an object"})
props = {}
for prop in sorted(CONTRACT[name]):
expected = CONTRACT[name][prop]
if prop not in props:
violations.append({"rule": "missing_property", "event": name, "detail": "missing required property " + prop})
elif not type_ok(props[prop], expected):
violations.append({"rule": "type_mismatch", "event": name, "detail": "property " + prop + " must be " + expected})
elif NAME_RE.match(name):
unknown_names.append(name)
violations.append({"rule": "unknown_event", "event": name, "detail": "event is not in the taxonomy contract"})
seen = set()
unknown_unique = []
for name in unknown_names:
if name not in seen:
seen.add(name)
unknown_unique.append(name)
unknown_names = unknown_unique
if violations:
verdict = "violations_found"
elif event_count == 0:
verdict = "empty_batch"
else:
verdict = "pass"
grouped = {}
for entry in violations:
label = entry["event"] or "(batch)"
grouped.setdefault(entry["rule"], [])
if label not in grouped[entry["rule"]]:
grouped[entry["rule"]].append(label)
for rule in grouped:
grouped[rule] = sorted(grouped[rule])
counts = Counter(entry["event"] for entry in violations if entry["event"])
top = counts.most_common(5)
offenders_summary = ", ".join("%s (%d)" % (clean(name), count) for name, count in top) if top else "none"
unknown_summary = ", ".join(clean(name) for name in unknown_names[:10]) if unknown_names else "none"
offending_events = sorted({entry["event"] for entry in violations if entry["event"]})
report = {
"environment": env_name,
"verdict": verdict,
"event_count": event_count,
"violation_count": len(violations),
"unknown_count": len(unknown_names),
"violations_by_rule": grouped,
"offending_events": offending_events,
"unknown_names": unknown_names,
}
report_json = json.dumps(report, sort_keys=True)
payload = {"outputs": {
"verdict": verdict,
"environment": env_name,
"event_count": event_count,
"violation_count": len(violations),
"unknown_count": len(unknown_names),
"violations": violations,
"violations_by_rule": grouped,
"offending_events": offending_events,
"unknown_names": unknown_names,
"offenders_summary": offenders_summary,
"unknown_summary": unknown_summary,
"report": report_json,
}}
print("taxonomy %s: %d violation(s), %d unknown name(s)" % (verdict, len(violations), len(unknown_names)))
print("::" + json.dumps(payload) + "::")
# --- 3. escalate or record the clean sweep ---
- id: escalate_violations
type: io.kestra.plugin.core.flow.If
description: Branch on the violation count, opening the tracking backlog on
drift and logging the all-clear when the batch honors the contract.
condition: "{{ outputs.check_taxonomy.vars.violation_count > 0 }}"
then:
- id: create_issue
type: io.kestra.plugin.github.issues.Create
description: Open a labeled GitHub issue with the top offenders and unknown
names, so taxonomy drift lands in the same backlog as other analytics
work.
jwtToken: "{{ secret('GITHUB_TOKEN') }}"
repository: "{{ inputs.issue_repository }}"
title: "Segment taxonomy violations in {{ inputs.environment }} ({{
outputs.check_taxonomy.vars.violation_count }} finding(s))"
body: |
## Segment taxonomy violations
Environment `{{ inputs.environment }}` batch: **{{ outputs.check_taxonomy.vars.event_count }} event(s)** checked, **{{ outputs.check_taxonomy.vars.violation_count }} violation(s)**, **{{ outputs.check_taxonomy.vars.unknown_count }} unknown event name(s)**.
Top offenders: {{ outputs.check_taxonomy.vars.offenders_summary }}
Unknown names: {{ outputs.check_taxonomy.vars.unknown_summary }}
Contract report: `{{ outputs.check_taxonomy.vars.report }}`
Execution: {{ execution.id }}
Rename offenders to lowercase snake_case (track events prefixed with `track_`), add the missing properties with the declared types (string, int, bool), register genuinely new events in the contract, then close this issue.
labels:
- analytics
- segment
- taxonomy
- id: slack_digest
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Post the counts and the top offenders to Slack, so drift is visible
without opening the execution.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "Segment taxonomy digest: {{ outputs.check_taxonomy.vars.violation_count }} violation(s), {{ outputs.check_taxonomy.vars.unknown_count }} unknown name(s) across {{ outputs.check_taxonomy.vars.event_count }} event(s) in {{ inputs.environment }}. Top offenders: {{ outputs.check_taxonomy.vars.offenders_summary }}. A GitHub issue is waiting in {{ inputs.issue_repository }}. Execution {{ execution.id }}."
}
else:
- id: log_clean
type: io.kestra.plugin.core.log.Log
description: Record the clean sweep so execution history doubles as proof the
contract was checked.
message: "Taxonomy clean: {{ outputs.check_taxonomy.vars.event_count }}
event(s), verdict {{ outputs.check_taxonomy.vars.verdict }} in {{
inputs.environment }}."
errors:
- id: slack_alert
type: io.kestra.plugin.slack.notifications.SlackIncomingWebhook
description: Alert when the validation itself errors, because a broken check
must never look like a clean taxonomy.
url: "{{ secret('SLACK_WEBHOOK_URL') }}"
payload: |
{
"text": "Segment taxonomy validator FAILED in flow {{ flow.id }} (execution {{ execution.id }}). The batch was NOT checked: verify the SEGMENT_WEBHOOK_KEY, GITHUB_TOKEN, and SLACK_WEBHOOK_URL secrets on the worker."
}
outputs:
- id: violation_count
type: INT
description: Number of contract violations found in the validated batch, e.g. 3.
value: "{{ outputs.check_taxonomy.vars.violation_count }}"
- id: unknown_count
type: INT
description: Number of well-named events missing from the taxonomy contract, e.g. 1.
value: "{{ outputs.check_taxonomy.vars.unknown_count }}"
- id: verdict
type: STRING
description: 'Contract verdict, e.g. pass, violations_found, or empty_batch.'
value: "{{ outputs.check_taxonomy.vars.verdict }}"
- id: report
type: STRING
description: Single-line JSON report grouping violations by rule with offending
and unknown event names.
value: "{{ outputs.check_taxonomy.vars.report }}"