Concepts

A domain-story document captures one narrative flow through a domain. The structure follows the original Domain Storytelling canon and exists at three levels: the story itself, the sentences inside it, and the elements (Actors, Work Objects, edges) inside the sentences.

Actors and Work Objects

An Actor is someone (or something) that does things in the domain. A customer, a sales clerk, a scheduler. Actors live at story scope: one Actor icon appears once in the entire story, no matter how many sentences reference it. The story-level actors list is where Actors carry annotations and group memberships; if an Actor neither has an annotation nor a group membership, it can be referenced from edges without being declared at all.

A Work Object is something that gets produced, consumed, transferred, or transformed. A document, an order, an email, a record. Work Objects live at sentence scope: each sentence draws its own Work-Object icons, even if the same name appears in a previous sentence. The same Work Object name in two different sentences is two icons.

This split between story-scope Actors and sentence-scope Work Objects mirrors how Domain Storytelling diagrams are actually drawn. A story shows a single cast of Actors that performs activities across many sentences; the Work Objects flow through those activities, redrawn each time they participate.

Sentences and Edges

A sentence is one numbered unit of the story. It carries a sequenceNumber (its place in the story), an optional list of declared workObjects, and a list of edges.

An edge is one drawn arrow. It has a from and a to reference (each pointing at an Actor or a Work Object), an optional label (the activity – a verb, a preposition, or a conjunction), and may carry an annotation and group memberships of its own. The list is flat, not a tree: the sentence patterns of Domain Storytelling – linear flows, collaboration, conjunctions, tool use, parallel arrows – are all expressible as independent edges without special-case structures.

Sequence numbers may repeat. Duplicate sequenceNumber values denote parallel sentences at the same position in the flow.

Groups

A group is an arbitrary cluster of elements – Actors, Work Objects, or edges – that the story wants to mark together. Groups are declared once at the top level (so they can carry their own description and annotation) and then referenced inline from element membership lists (groups: [name, ...]).

The decoupling between top-level declaration and inline membership is deliberate. It mirrors how a diagram is read: the group in the legend says what the cluster means, and the membership tags on individual elements say who is in it.

What the Schema Does Not Enforce

Several integrity rules are modeling rules the schema deliberately leaves to the linter. Uniqueness of Actor names. Uniqueness of group names. Uniqueness of Work-Object names within a single sentence. Referential integrity of inline groups: [name, ...] memberships. The graph integrity of edges (every from/to reference resolves to a known Actor or Work Object).

The same convention as in the core schema applies: structural validity is one concern; modeling soundness is another. Keeping them separate makes the schema simpler and the linter rules more focused.