| name | example-data |
| description | Example Data Skill - Guide for adding example data to Command, Event, and Information elements in prooph board. Covers YAML examples with concrete values and documenting state changes. |
Example Data for Element Descriptions
This document describes how to add concrete example data to Command, Event, and Information elements in prooph board using YAML code blocks.
Why Example Data
Example data in element descriptions helps:
- Business users understand what data flows through the system
- Stakeholders validate that the model captures the right information
- Developers see concrete examples of expected payloads
Key Principles
Use Concrete Values, Not Types
✅ Good:
employee: Anna
location: loc-abc
startTime: 9am
❌ Avoid:
employeeId: string|format:uuid
locationId: string|format:uuid
startTime: string|format:time
Use schema/type definitions in element details (f.e. cody-schema), not in descriptions.
Show What Matters for This Step
Include only the fields relevant to understand this specific process step. Don't dump every possible field.
Command Elements
Commands represent business actions that change persistent system state. Show the data the command carries as input.
Pattern 1: Full Command Payload
trackingId: uuid
employee: uuid
location: uuid
day: 2026-03-05
startTime: 09:00
breaks:
-
startTime: 13:00
endTime: 13:30
-
startTime: 15:00
endTime: 15:15
endTime: 18:00
notes: Worked late on project documentation
Use when: The command has significant data that needs explanation.
Pattern 2: Minimal Identifier
trackingId: track1
Use when: The command only needs a reference ID and the context makes everything else clear.
Event Elements
Events represent business facts that became true. Show the state change the event carries.
Pattern 1: State After Event
trackingId: track1
breaks:
-
startTime: 1pm
endTime: now()|time()
The # ... indicates that other data from the state remains unchanged. Use now()|time() to show dynamic values computed at runtime.
Pattern 2: Minimal Event Data
trackingId: track1
Use when: The event only carries an entity reference and the fact itself is clear from the event name.
Information Elements
Information represents data read from the system. Show a snapshot of available information.
Pattern 1: Complete State Snapshot
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
breaks:
-
startTime: 1pm
endTime: 1:30pm
endTime: 6pm
overtime: 0
Use when: Showing the full state after multiple events helps understand the process.
Pattern 2: Partial State
trackingId: track1
employee: Anna
location: loc-abc
day: 2026-03-05
startTime: 9am
Use when: Only certain fields are relevant to this step or the information represents a query result with limited fields.
Pattern 3: Empty Description
If the information element name is self-explanatory and the technical details in element details provide full specification, no example data may be needed.
Documenting State Changes
Before/After Format
```markdown
**Before**: Employee is not clocked in
**After**: Time tracking session started at 09:00 AM
This pattern makes state transitions explicit for business understanding.
Slice Width
When adding example data to an element, check the width of the slice the element belongs to. If the width is less than 320, use the resize_slice tool to set the slice width to 320 before or after updating the element description. Do it only once per slice.
Common Mistakes
Too Technical
```markdown
❌ Bad:
The command handler validates the schema and if valid, records an event to the event store which triggers projections to update the read model.
✅ Better:
System records the clock-in time and starts tracking work hours.
Missing Context
❌ Bad:
trackingId: track1
✅ Better:
trackingId: track1
employee: Anna
location: loc-abc
Provide enough context so readers understand what the data represents.
Duplicating Element Details
❌ Bad:
{
"timeTrackingId": "string|format:uuid",
"employeeId": "string|format:uuid"
}
✅ Better:
trackingId: track1
employee: Anna
Descriptions use example data; details use schema definitions.
