Skip to content

Cratis Screenplay structured values for objects and lists

Cratis Screenplay writes objects and lists as indented blocks, not JSON. Use member assignments for an object and item lines for a list, with another level of indentation for each nested value. The same form supplies domain records in specifications and seeds, as well as screen component properties.

This screen fragment combines a list of column objects, an emptyState object with nested actions, and an empty rowActions list:

component Cratis.Blueprint.Default.kanbanBoard board
property label = "Orders by status"
property columns
item
id = "received"
label = "Received"
item
id = "approved"
label = "Approved"
property emptyState
title = "No orders"
actions
item "create"
item "import"
property rowActions none
You write It is
name = <value> A scalar: a string, a number, true, false or null.
name with lines indented under it An object, when the first line under it is member = ... or a member that opens its own block.
name with item lines indented under it A list, one item line per element.
name none An empty list.
name empty An object without members.

An object holds one member = value line per member. When a member is itself an object or a list, put its name on a line of its own and indent its contents underneath. In the fragment above, emptyState is an object; its actions member opens a list.

A list holds one item line per element, in order. Use item <value> for a scalar element, such as item "create". A bare item opens a block for an object element, as the columns show, or for a nested list if its first child is another item. Use item none for an empty nested list and item empty for an object element without members.

Align member assignments however reads best; spacing around = does not change their meaning.

A block whose first line is an item is a list; any other block is an object. A member literally named item is written @item, and a member name that is not an identifier is quoted: "first name" = "Ada".

A header without an inline value must open an indented block or end in none or empty. A bare header with no children is malformed (PLAY0291), not an empty value. An empty list, an object without members and null are different values; choose the one the target type accepts.

Use the block form at these assignment sites. The header changes with the surrounding construct, but the member and item lines follow the same rules:

Where Header line
Screen component property property columns
Literal UI binding property filter from literal, parameter range from literal mode oneWay
Composition set and contributed item value set "shell:header".actions, actions under an item
Specification given, when, then, case and example values lines
Absence key then no readmodel OrderView for
Structured command response then returns value
Generated and pinned fixtures generated receipt, given generated PlaceOrder.receipt
Seed event lines
produces, inline produces event, reaction produces and capture append mappings lines, lines InvoiceLine[]
Operation inputs contact Contact
Projection literal (exact numeric mode) amount

For an order specification, first declare the PlaceOrder command and OrderPlaced event with a lines collection whose item type has sku and quantity members. PlaceOrder also needs a numeric total property. The fragment below supplies one line to the command and expects that line in the event.

An inline assignment on a step header, such as given Invoice total = 1000, must be scalar. Put a structured value on its own line under the step:

specification Placing
when PlaceOrder
lines
item
sku = "A-1"
quantity = 2
total = 5000
then OrderPlaced
lines
item
sku = "A-1"
quantity = 2

The declaration tells the compiler what the value can contain. For lines InvoiceLine[], it checks that lines is a list and checks each item’s members against the declared type. Enum values are checked against their concept. The compiler does not infer members of undeclared shapes or shapes only named by external imports.

An unknown member produces PLAY0292; an incompatible shape, such as an object where a list belongs, produces PLAY0293. Repeating a member produces PLAY0294. When the model is bound for execution, a missing required member produces PLAY0354, so writing empty does not bypass a record’s required fields.

To use these values as an application’s initial facts rather than a specification’s inputs, group them under event sources in Event seeding.

JSON spellings such as property columns = [{"id":"received"}], lines = [] and then returns {"id":1} produce error PLAY0833. The parser retains the value so the canonical printer can rewrite it as blocks. Printing an existing document converts those values; for new values, use the block form directly. A malformed block produces PLAY0291.