domain-story

The Domain Storytelling extension defines a single document kind: domain-story. A story is a numbered sequence of sentences that describe one narrative flow through the domain.

Top-Level Fields

Field	Required	Description
apiVersion	yes	schema.esdm.io/domain-storytelling/v1
kind	yes	domain-story
name	yes	The story name.
scope	yes	scope.domain reference.
sentences	yes	Non-empty list of sentences.
pointInTime	no	as-is or to-be.
granularity	no	coarse-grained or fine-grained.
domainPurity	no	pure or digitalized.
groups	no	Non-empty list of declared groups.
actors	no	Story-global Actor declarations. Required only for Actors that carry an annotation or groups membership; bare Actors can be referenced inline from edges without declaration.
description	no	Free-form prose.
metadata	no	Non-semantic labels and annotations.

The DS annotation field that appears on Actors, Work Objects, and edges is distinct from metadata.annotations: it carries in-diagram text, while metadata.annotations is for tooling and provenance.

actors[]

Field	Required	Description
name	yes	Actor name.
annotation	no	In-diagram text attached to the Actor.
groups	no	Non-empty list of group names this Actor belongs to.

groups[]

Field	Required	Description
name	yes	Group name.
description	no	Description of what the group represents.
annotation	no	In-diagram text attached to the group.

sentences[]

Field	Required	Description
sequenceNumber	yes	Integer ≥ 1. Duplicate values denote parallel sentences at the same position.
edges	yes	Non-empty list of edges.
workObjects	no	Per-sentence Work Object declarations. Required only for Work Objects that carry an annotation or groups membership.

sentences[].workObjects[]

Field	Required	Description
name	yes	Work Object name.
annotation	no	In-diagram text attached to this instance.
groups	no	Non-empty list of group names this Work Object belongs to.

The same name in a different sentence is a new instance with its own annotation, because DS redraws Work Objects per sentence.

sentences[].edges[]

Field	Required	Description
from	yes	A node reference – either { actor: <name> } or { workObject: <name> }.
to	yes	A node reference.
label	no	The Activity text (verb, preposition, or conjunction).
annotation	no	In-diagram text attached to the edge.
groups	no	Non-empty list of group names this edge belongs to.

Example

apiVersion: schema.esdm.io/domain-storytelling/v1
kind: domain-story
name: invite-a-co-administrator
scope:
  domain: golf-club-management
pointInTime: as-is
granularity: coarse-grained
domainPurity: pure
sentences:
  - sequenceNumber: 1
    edges:
      - from: { actor: course-owner }
        to: { workObject: invitation }
        label: drafts
      - from: { actor: course-owner }
        to: { workObject: invitation }
        label: sends
  - sequenceNumber: 2
    edges:
      - from: { workObject: invitation }
        to: { actor: invitee }
        label: arrives at
      - from: { actor: invitee }
        to: { workObject: invitation }
        label: accepts