Event Schema Reference
The Event object is the body of every DcpMessage. It records exactly one state change in a project. An Event MUST contain at least one of: entity, delta, or refs.
Schema: https://schemas.devcopro.org/v1/event.schema.json
Required fields
Section titled “Required fields”event_id
Section titled “event_id”Type: string — MUST be present.
A unique identifier for this event. Recommended format: evt_ prefix followed by a ULID or UUID. Used for deduplication and correlation.
entity_type
Section titled “entity_type”Type: string (enum) — MUST be present.
The kind of project entity this event concerns. One of eight values:
| Value | Description |
|---|---|
project | A project-level record |
task | A unit of work |
dependency | A declared dependency between tasks or entities |
architecture_impact | An architectural change or risk |
decision | A recorded decision |
review_request | A request for human or agent review |
finding | An observation, issue, or discovery |
milestone | A significant project checkpoint |
Type: string — MUST be present.
Describes what happened to the entity. The verb vocabulary is controlled. Universal verbs apply to all entity types; some entity types define additional verbs:
Universal: created, updated, status_changed, snapshot, deleted
Task-specific: completed, blocked, unblocked, assigned
Decision-specific: recorded, accepted, rejected, superseded
ReviewRequest-specific: requested, approved, changes_requested, rejected
Finding-specific: raised, acknowledged, resolved
Milestone-specific: reached, missed
ArchitectureImpact-specific: assessed
Dependency-specific: created, removed
See the verb vocabulary reference for the complete table. Verbs are open tokens: consumers MUST tolerate unknown verbs and pass them through.
entity_id
Section titled “entity_id”Type: string — MUST be present.
The stable identifier of the entity this event describes. Must remain consistent across multiple events concerning the same entity (e.g. a task’s ID does not change when its status changes).
Optional fields
Section titled “Optional fields”project_id
Section titled “project_id”Type: string — MAY be present.
Scopes the event to a specific project. Useful when a single DCP stream carries events from multiple projects.
occurred_at
Section titled “occurred_at”Type: string (ISO 8601 datetime) — MAY be present.
When the state change actually occurred, as distinct from issued_at in the envelope (when the message was emitted). Use this when there is a lag between the event and the message.
attributed_to
Section titled “attributed_to”Type: string — MAY be present.
The agent, user, or system associated with causing this change, in project terms. This is descriptive metadata only — it carries no authenticated identity. See Carries No Trust.
entity
Section titled “entity”Type: object — MAY be present. Required if neither delta nor refs is present.
A full snapshot of the entity’s state at the time of the event. Shape varies by entity_type. Use for created events or any event where a full snapshot is warranted.
Type: object — MAY be present. Required if neither entity nor refs is present.
A map from field name to a change record. Maximum 64 entries.
Each entry has the shape:
{ "from": <previous value>, "to": <new value> }tois REQUIRED — the new value after the change.fromis OPTIONAL — the previous value. Omit when the previous state is unknown or not meaningful (e.g. on creation).
Example:
"delta": { "status": { "from": "in_progress", "to": "completed" }, "assignee": { "to": "agent-builder" }}Type: array of ref objects — MAY be present. Required if neither entity nor delta is present.
Semantic links from this event to other entities. Each ref has:
rel— the relationship type. Drawn from a closed vocabulary:relates_to,part_of,references,caused_by,derived_from,supersedes,concerns,blocksref— the target entity identifier (string).
The vocabulary intentionally excludes routing and permission relations. See Carries No Trust.
extensions
Section titled “extensions”Type: object — MAY be present.
A free-form map for implementor-specific fields. DCP processors that do not recognise an extension key MUST ignore it. Extension keys SHOULD be namespaced (e.g. "acme:priority": 1) to avoid future conflicts with the core spec.
