Skip to content

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 = string

An 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.capacity

A 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 true

The 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.