DCB notation reference
Every construct of the DCB notation, grouped like the help of the DCB Playground. The advanced constructs, which are not needed to read most examples, and the experimental ones are listed at the end. The guide introduces the notation step by step.
The snippets are taken from one model about courses and students, which the build of this website checks like every example.
Text
model
The model's name, once per text.
model "Course reference"Comments
// a line comment
/* a block comment */Comments are for the reader only. The DCB Playground does not store them, so they get lost once a text is applied.
Literals
"text" 42 1.5 true false null ["c1", "c2"] { given: "Ada", family: "Lovelace" }Values are written as JSON. Keys of objects may be written without quotes. Members of an enum are written without quotes wherever the type is known. A value of a tag type may be written with its type, CourseId("c1"), and has to be where a read is given one.
Annotations
| Annotation | On | Effect |
|---|---|---|
@icon("π") |
events, commands (and entities) | the symbol the playground shows it with |
@feature("Enrolment") |
commands | the feature group the playground lists it under |
@tagSchema("{type}={value}") |
tag types | how a Tag of the type is written, see tag type |
@feature("Course management")
@icon("β¨")
command DefineCourse(capacity: Capacity) {
emit CourseDefined { courseId: CourseNumbering(), capacity }
}Annotations change how the DCB Playground presents a definition, not what it means. An annotation stands on the line before the definition.
Data
tag type
tag type CourseId = string { pattern: "^c[0-9]+$" }
tag type StudentId = stringAn identifier that can be a Tag. The type's name is the key of the Tag: the value "c1" is the Tag CourseId:c1. Only a value of a tag type can be a Tag.
The constraints after the base type are optional, see type. With @tagSchema("{type}={value}") a Tag is written differently, {type}:{value} is the default.
event
event CourseDefined { tag courseId: CourseId, capacity: Capacity }
event StudentRegistered { tag studentId: StudentId, name: PersonName, email?: string }An Event, named in the past tense, with its properties:
| Property | Meaning |
|---|---|
capacity: Capacity |
a property, typed with a declared type or a basic one (string, number, integer, boolean) |
email?: string |
optional: null when not set |
slots: TimeSlot[] |
a list |
tag courseId: CourseId |
a Tag of the Event, see tag |
tag
event StudentSubscribedToCourse { tag courseId: CourseId, tag studentId: StudentId }Marks a property of an Event as one of its Tags. The property has to be of a tag type. An Event has no other Tags than the ones it marks.
| Mark | Meaning |
|---|---|
tag courseId: CourseId |
the value is a Tag |
items: Item[] tag each productId |
every element of the list is a Tag, by the field of the record it holds |
State
projection
projection CourseCapacity (tag courseId: CourseId): integer = 0 {
on CourseDefined => set event.data.capacity
on CourseCapacityChanged => set event.data.newCapacity
}
projection CourseSubscribedStudentIds (tag courseId: CourseId): StudentId[] = [] {
on StudentSubscribedToCourse => append event.data.studentId
}A fold over Events: the Tags it is kept by, the value's type, the initial value, and one handler per Event type. CourseCapacity is kept per course: read for "c1", it only sees Events tagged CourseId:c1. A projection with several Tags, (tag courseId: CourseId, tag studentId: StudentId), only sees Events with all of them.
See projections for the concept.
untagged
untagged projection CourseNumbering: CourseId = "c1" {
on CourseDefined => set successor(event.data.courseId)
}A projection without Tags, which sees all Events of the types it handles. A projection either names its Tags or says it has none.
on
| Handler | Effect |
|---|---|
on E => set <value> |
replaces the value |
on E => increment 1, on E => decrement 1 |
changes a number (integer, number or a type based on one) |
on E => append <value>, on E => remove <value> |
changes a list |
The set of operations is fixed, because the DCB Playground analyses them. A derived projection works out a value from others, and a scripted projection can do anything else.
event.data
on CourseDefined => set event.data.capacityA property of the Event being handled. Besides that, a handler's value is a literal or an enum member.
Behaviour
command
@feature("Course management")
command ChangeCourseCapacity(courseId: CourseId, newCapacity: Capacity) {
require CourseStatus(courseId) == Existent
else reject "Course is not active"
require CourseSubscriptionCount(courseId) <= newCapacity
else reject "Course has more subscriptions than that"
emit CourseCapacityChanged { courseId, newCapacity }
}What can be done and how it is decided: the command's name and properties (? optional, [] a list), then its aliases, conditions and Events, in this order.
Reads
CourseStatus(courseId)
CourseNumbering()
CourseStatus(CourseId("c1"))The value of a projection, for a value of each of its Tags and then of each of its arguments (see derived), in the order the projection declares them. An untagged projection is read with (). A value is a property of the command, an alias, another read or a literal of the tag type.
A read can be written wherever a value is: in a condition, in an Event's property, or as the value of another read. The same read written twice is read once.
alias
alias subscribedCourseIds = StudentSubscribedCourseIds(studentId)A name for a read, for conditions and Events that use it more than once. It does not read anything where it is written: which Events a command reads follows from what its conditions and Events use.
require
@feature("Enrolment")
command SubscribeStudentToCourse(courseId: CourseId, studentId: StudentId) {
alias subscribedCourseIds = StudentSubscribedCourseIds(studentId)
require CourseStatus(courseId) == Existent
else reject "Course is not active"
require StudentExists(studentId) is true
else reject "Student is not registered"
require CourseSubscribedStudentIds(courseId) not contains studentId
else reject "Student is already subscribed"
require count(subscribedCourseIds) < 10
else reject "Student is subscribed to too many courses"
emit StudentSubscribedToCourse { courseId, studentId }
}A condition that has to hold, otherwise the command is rejected with the message after else reject. The message is required, on the same line or the next. It is static text, one line, by convention in sentence case without a full stop. Several conditions may share a message: the messages are the complete set of reasons a command can be rejected for, and a scenario names a rejection by its message.
Operands are properties of the command (studentId), reads, aliases and their properties (course.status), literals and enum members.
| Condition | Meaning |
|---|---|
a == b, a != b, <, <=, >, >= |
comparison |
x in [Draft, Published], x not in [β¦] |
one of a list of values |
xs contains x, xs containsAny ys |
lists |
s startsWith "c", s endsWith "1" |
strings |
count(xs) < 10, ==, > |
the length of a list |
x is empty, x is not empty |
an empty string or list, or null |
b is true, b is false |
booleans |
not a < b, xs not contains x |
negation |
emit
@feature("Course management")
@icon("β¨")
command DefineCourse(capacity: Capacity) {
emit CourseDefined { courseId: CourseNumbering(), capacity }
}Appends an Event if all conditions hold. Each property is taken from a property of the command, a read, an alias or a literal. capacity is short for capacity: capacity.
Consistency boundary
Never written. Each read contributes the Event types of the projection it reads, with the Tags it is read for. The Events are appended with an Append Condition that fails if an Event matching that Query was appended since the command read. See from notation to DCB in the guide.
Scenarios
scenario
@feature("Course management")
command ArchiveCourse(courseId: CourseId) {
require CourseStatus(courseId) == Existent
else reject "Course is not active"
emit CourseArchived { courseId }
2 scenarios
scenarios {
scenario "an archived course cannot be archived again" {
given CourseDefined { courseId: "c1", capacity: 10 }
and CourseArchived { courseId: "c1" }
when ArchiveCourse { courseId: "c1" }
then rejected "Course is not active"
}
scenario "an existing course is archived" {
given CourseDefined { courseId: "c1", capacity: 10 }
when ArchiveCourse { courseId: "c1" }
then CourseArchived { courseId: "c1" }
}
}}An example that pins behaviour down. The scenarios of a command or projection sit in one scenarios { β¦ } group at its end. The name is optional.
| Line | Meaning |
|---|---|
given E { β¦ } |
an Event already appended. Values are JSON, enum members without quotes |
when C { β¦ } |
the command, with all of its properties |
then E { β¦ } |
the Events appended |
then nothing |
no Event appended |
then rejected "<message>" |
the message the command was rejected with |
and E { β¦ } |
a further Event after given or then |
A scenario reads as a sentence: given, when and then are each said once, and further Events continue with and. Every scenario states its then; the DCB Playground offers to write in what the model does.
Projection scenarios
projection CourseStatus (tag courseId: CourseId): CourseStatus = NonExistent {
on CourseDefined => set Existent
on CourseArchived => set Archived
1 scenario
scenarios {
scenario "a defined course exists" {
given CourseDefined { courseId: "c1", capacity: 10 }
then CourseStatus(CourseId("c1")) == Existent
}
}}A scenario of a projection asserts the value the given Events fold to, read for the Tags it names.
Advanced
The constructs below are not needed to read most examples. They are listed in the same order as the ones above.
json advanced
// Written as JSON: β¦
command Foo json { β¦ }A definition the notation cannot express is written as the JSON the DCB Playground stores, under a comment explaining why. Examples on this website never contain one. See the guide.
type advanced
type Capacity = integer { minimum: 1 }
type TimeSlot = string { pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}T[0-9]{2}$" }A named type based on string, number, integer, boolean, object, array or null, optionally followed by JSON Schema keywords that constrain it. type Point = { β¦schemaβ¦ } declares a type by a complete JSON Schema.
enum advanced
enum CourseStatus { NonExistent, Existent, Archived }A fixed set of values. The members are strings and are written without quotes wherever the type is known: set Existent, CourseStatus(courseId) == Existent.
record advanced
record PersonName { given: string, family: string }A value with fields, each typed with a basic or declared type. A record has no identity of its own. A list of records can tag an Event by one of its fields, see tag.
successor advanced
on CourseDefined => set successor(event.data.courseId)The value following another one: 7 β 8, c1 β c2, inv-009 β inv-010. See numbering in the guide.
derived advanced
derived projection CourseIsFull (tag courseId: CourseId): boolean {
CourseSubscriptionCount(courseId) >= CourseCapacity(courseId)
}
derived projection CourseSeatsLeft (tag courseId: CourseId): integer {
CourseCapacity(courseId) - CourseSubscriptionCount(courseId)
}
derived projection CourseHasSeatsFor (tag courseId: CourseId, seats: integer): boolean {
CourseSeatsLeft(courseId) >= seats
}A value worked out from other projections, without handlers or initial value. Its block holds one expression:
| Expression | Value |
|---|---|
A(courseId) >= B(courseId) |
a comparison, written like a require. Always a boolean |
A(courseId) - B(courseId) |
a computation with +, - or *, over two projections or numbers. An integer from two integers, a number otherwise |
min(A(courseId), 10) |
the smaller of two numbers, max(β¦) the larger |
A longer expression is a chain of derived projections. If one side is null, a computation is null, too. A derived projection declares its Tags and passes them on to the projections it reads. A parameter without tag, like seats, is an argument: a read gives it after the Tags, CourseHasSeatsFor(courseId, 3), and the expression compares or computes with it by name, or passes it on to a read. An argument narrows nothing, unless it is passed on as a Tag of a read. Reading it reads its operands, each by its own Tags, so their Events are part of the Query. See derived projections in the guide.
Fan-out advanced
require ProductExists(each items.productId) is true
else reject "Product does not exist"each in front of a list reads once per element. A condition over the read has to hold for every element, and the Query contains one Query Item per element. See fan-out reads in the guide.
Experimental
The constructs below are still being tried out. The DCB Playground only offers them once experimental features are switched on in its settings.
currentValue experimental
on CourseDefined => set successor(currentValue)The projection's own value, before the handler is applied.
entity experimental
@icon("π")
entity Course (tag courseId: CourseId) {
lifecycle status
status = CourseStatus
capacity = CourseCapacity
subscriptionCount = CourseSubscriptionCount
subscribedStudentIds = CourseSubscribedStudentIds
slots = CourseSlots
isFull = CourseIsFull
}A name for projections that share an identity. The entity declares its identifier like a projection declares a Tag, and each property is a projection with exactly that Tag.
An entity is not stored, and it is not a consistency boundary: a command's Query contains only the Events of the properties it uses. See entities in the guide.
lifecycle experimental
@icon("π§βπ")
entity Student (tag studentId: StudentId) {
lifecycle exists
exists = StudentExists
subscribedCourseIds = StudentSubscribedCourseIds
}
projection StudentExists (tag studentId: StudentId): boolean = false {
on StudentRegistered => set true
}Marks the property of an entity that holds the state an instance is in, a boolean (two states) or an enum. The DCB Playground draws the state machine from its handlers and the conditions that guard them. An entity doesn't need a lifecycle.
scripted experimental
scripted projection CoursePeakSubscriptions (tag courseId: CourseId): integer {
initialState { current: 0, peak: 0 }
exposes peak
on StudentSubscribedToCourse => ```({ current: state.current + 1, peak: Math.max(state.peak, state.current + 1) })```
}A projection written in JavaScript, scripted in front of projection. Its Tags are declared like for any projection, so its Query is derived the same way.
| Field | Meaning |
|---|---|
scripted projection CourseActivity (tag courseId: CourseId, days: integer) |
the Tags, then arguments, as for a derived projection. A read gives them in that order: CourseActivity(courseId, 14) |
initialState { β¦ } |
the state before the first Event |
exposes peak |
the field of the state commands read. Without it, the whole state is the value |
on E => ```expr``` |
a handler: an expression over state, event, tags (tags.courseId) and args (args.days) that returns the next state |
The DCB Playground asks for confirmation before it opens a model containing scripts, and ?safe in its address disables them.
Reading an entity experimental
@feature("Course management")
command RescheduleCourse(courseId: CourseId, slots: TimeSlot[]) {
alias course = Course(courseId)
alias students = Student(each course.subscribedStudentIds)
alias theirs = Course(each students.subscribedCourseIds) excluding courseId
require course.status == Existent
else reject "Course is not active"
require theirs.slots not containsAny slots
else reject "Slots clash with a subscriber's other course"
emit CourseRescheduled { courseId, slots }
}| Read | Meaning |
|---|---|
alias course = Course(courseId) |
one instance of an entity, by its identifier. Only the properties that are used contribute to the Query |
alias students = Student(each course.subscribedStudentIds) |
one instance per element of a list, see fan-out |
β¦ excluding courseId |
drops one identifier from the list |
Reads can build on earlier ones, and the Query is then as deep as the chain. See chained reads in the guide.
Arguments of an entity experimental
alias course = Course(courseId, since: today)Values for the arguments of the projections among the entity's properties, by name after the identifier.
Optional reads experimental
alias tutor? = Student(tutorId)The value may be null. Then nothing is read, and conditions over the alias hold.
emit β¦ when experimental
emit StudentSubscribedToCourse { courseId, studentId }
when CourseIsFull(courseId) is false
emit StudentWaitlistedForCourse { courseId, studentId }
when CourseIsFull(courseId) is trueThe Event is only appended if its conditions hold, combined with and. A failing when does not reject the command. If no Event is appended, the command still succeeds. The conditions count towards the Query like the ones of require.