Diagram Proposal: RASCI Matrix

[nihilor]

Diagram Proposal: RASCI Matrix

Proposal

Mermaid.js should add a rasci diagram type that renders
Responsibility Assignment Matrices (RASCI/RACI) as styled, interactive
tables — because RASCI matrices are among the most widely used artefacts
in project management and organisational documentation, yet no dedicated
text-based authoring format exists that is both human-readable and
machine-processable.

Today, authors maintain RASCI matrices in spreadsheets or wiki tables.
These formats are disconnected from documentation workflows, hard to diff
in version control, and impossible to embed in Markdown-based docs without
losing editability. A native rasci diagram closes this gap — the matrix
lives as text alongside the documentation it describes, rendered on-demand
by Mermaid's existing pipeline.

Use Cases

• Project charters — define roles and responsibilities at kick-off,
  keep them in the same repository as the project plan
• Architecture documentation — assign decision authority (Accountable)
  and review obligations (Consulted) to teams for each ADR or component
• Process documentation — map organisational processes to role groups,
  embed directly in Confluence, Notion, or GitHub wikis
• Onboarding material — new team members see at a glance who owns what
• Audits and compliance — machine-readable JSON export (via CLI) feeds
  governance tooling without manual re-entry

Why a new diagram type and not an existing one?

Existing type	Why it falls short for RASCI
Flowchart	Models process flow, not actor–task assignments
Quadrant chart	Two-dimensional scatter, no notion of roles or task groups
xychart-beta	Continuous numeric axes; RASCI is categorical and matrix-shaped
Block diagram	Free-form layout; RASCI has strict row/column semantics

A RASCI matrix has two orthogonal dimensions (tasks × roles), optional
hierarchical grouping on both axes, and a fixed vocabulary of five
assignment values (R, A, S, C, I). None of the existing diagram types
model this structure.

Syntax

The diagram keyword is rasci. The format has two top-level sections:
roles: defines the column headers; tasks: defines the rows and their
assignments. Both sections support optional group blocks for hierarchical
organisation. Assignments use bracket notation: ALIAS[R].

Minimal example

rasci
  roles:
    PO "Product Owner"
    DEV "Developer"

  tasks:
    "Implement feature":
      PO[A] DEV[R]

Full example with groups and metadata

rasci
  %% Comments start with %%

  roles:
    PO  "Product Owner"
    PM  "Project Manager"
    "Stakeholder"                    %% alias defaults to label
    group "Engineering":
      FE  "Frontend Engineer"
      BE  "Backend Engineer"
      group "Platform":
        OPS "Operations"
        SEC "Security"

  tasks:
    group "Discovery":
      desc: "Clarify Requirements and Constraints"
      link: "https://nihilor.github.io/rasci"

      T01 "Collect requirements":    %% explicit task id
        desc: "Stakeholder interviews and documentation"
        PO[A] PM[R] FE[C] BE[C] Stakeholder[I]

      "Analyze market":              %% id defaults to slug: analyze_market
        PM[R] PO[A] Stakeholder[C]

    group "Realization":
      T02 "Design architecture":
        link: "https://github.com/nihilor/rasci"
        BE[R] FE[R] PO[A] SEC[C] OPS[C]

      T03 "Prepare deployment":
        OPS[R] BE[S] SEC[C] PM[A] Stakeholder[I]

    T04 "Approve release":           %% ungrouped task
      PO[A,R] PM[C] Stakeholder[I]  %% multiple attrs on one role

Rendered output

The renderer produces an HTML table with:

• Role column headers — alias as label, full name as tooltip
• Role group headers — optional spanning header row above aliases
  (e.g. "Engineering" spans FE, BE; "Platform" spans OPS, SEC)
• Task group rows — coloured separator row spanning all columns;
  desc as tooltip, link as inline ↗ anchor
• RASCI cells — colour-coded per assignment value:
  R = amber, A = red-tinted, S = green, C = blue, I = grey
• Empty cells — rendered in muted colour, clearly distinguishable

---

Syntax rules

Roles section

roles      ::= "roles" ":" role-item+
role-item  ::= role-def | role-group
role-def   ::= [alias] string
               %% alias optional; defaults to string value (trimmed)
               %% alias: /[A-Z][A-Z0-9_]*/
role-group ::= "group" string ":" role-item+
               %% groups nest arbitrarily; leaf path stored as string[]

Tasks section

tasks      ::= "tasks" ":" task-item+
task-item  ::= task-def | task-group
task-def   ::= [task-id] string ":" meta* assignment*
               %% assignments optional; empty task is valid (renders as blank row)
               %% task-id optional; defaults to slug(label)
               %% slug: lowercase, whitespace → "_", non-alnum stripped
task-group ::= "group" string ":" meta* task-item+
meta       ::= ("desc" | "link") ":" string
               %% desc: free text, rendered as tooltip
               %% link: URL, rendered as ↗ anchor next to label
assignment ::= alias "[" rasci-list "]"
rasci-list ::= rasci-char ("," rasci-char)*
rasci-char ::= "R" | "A" | "S" | "C" | "I"

Shared terminals

alias      ::= [A-Z][A-Z0-9_]*
task-id    ::= [A-Z][A-Z0-9_]*
string     ::= '"' [^"]* '"'
comment    ::= "%%" .*          %% stripped before tokenising (existing Mermaid convention)
indent     ::= "  "+            %% 2 spaces per level; tabs not supported

Semantics

• Every alias referenced in an assignment must be declared in roles:.
  Undeclared aliases are a validation error.
• Every alias in roles: must be unique across the entire roles section.
  Duplicate aliases are a validation error.
• Every task-id must be unique across all tasks.
  Duplicate ids are a validation error.
• Each task must have at most one Accountable (A) assignment.
  Multiple A values on a single task are a validation error.
• A role without an explicit alias uses its label string as alias.
  If the label contains spaces, callers must write it verbatim in assignments
  (e.g. Stakeholder[I]); using a short alias is therefore recommended for
  multi-word labels.
• A task without an explicit task-id derives its id from slug(label).
  The id is exposed in JSON export; it is not rendered in the table.
• Multiple RASCI values on one role (PO[A,R]) are valid and rendered
  comma-separated in the cell, coloured by the first value.
• Tasks may appear at the top level of tasks: without a group.
  Consecutive ungrouped tasks before the first group, between groups, or
  after the last group are collected into implicit unlabelled groups and
  rendered without a separator row.
• Role groups affect column header rendering only; they do not change
  assignment semantics.
• Task groups are rendered as full-width separator rows in the table body.

Configuration

The diagram respects Mermaid's standard %%{init: ...}%% front matter:

%%{init: {"rasci": {"showRoleGroups": true, "showRoleLabels": true}}}%%
rasci
  ...

Key	Type	Default	Effect
showRoleGroups	boolean	true	Show spanning group header row above role aliases
showRoleLabels	boolean	true	Show full role name as tooltip on alias column

RASCI legend

Value	Name	Meaning
R	Responsible	Does the work
A	Accountable	Ultimately answerable; approves the result; max. one per task
S	Supportive	Provides resources or assistance
C	Consulted	Input sought before or during; two-way communication
I	Informed	Notified after the fact; one-way communication

Relationship to existing Mermaid conventions

Convention	How rasci follows it
%% comments	Stripped by tokeniser before parsing, identical to all other diagram types
%%{init}%%	Standard config front matter supported
Indentation	2-space indent per level, consistent with block, mindmap, packet
Quoted strings	"label" for human-readable text, consistent with timeline, gantt
:::class syntax	Not used; RASCI cells are styled by assignment value, not user classes
Theme variables	Cell colours derived from --mermaid-primary-color and tone variants

Reference implementation

A complete reference implementation is publicly available:

Repository	https://github.com/nihilor/rasci
Live editor	https://nihilor.github.io/rasci/
License	MIT

The implementation is written in ES Module JavaScript (Node ≥ 18), has
zero runtime dependencies, and passes the full example above through
parse → validate → render without errors.

Module	Description	~Lines
src/parser.js	Tokeniser + recursive descent parser + validation	300
src/renderer-html.js	normalize() + HTML table renderer	150
src/renderer-markdown.js	GFM renderer (group headings, footnotes, desc column)	130
rasci-cli.js	CLI entry point (html / markdown / json, stdout or file)	120

The live editor at https://nihilor.github.io/rasci/ lets reviewers try
the syntax interactively without a local install, and serves as a
visual specification of the expected rendered output.

The repository layout is:

rasci/
├── src/
│   ├── parser.js            %% tokeniser + recursive descent parser + validation
│   ├── renderer-html.js     %% normalize() + HTML table renderer
│   └── renderer-markdown.js %% GFM renderer
├── docs/                    %% live editor (GitHub Pages)
├── example/                 %% example.rasci + rendered outputs (html, md, json, png)
├── standard/                %% formal syntax specification and this proposal
└── rasci-cli.js             %% CLI entry point

The codebase structure maps directly onto Mermaid's existing diagram
module layout (src/diagrams/rasci/):

src/diagrams/rasci/
├── rasciDiagram.ts          %% diagram registration
├── rasciParser.jison        %% or: hand-written TS tokeniser + parser
├── rasciDb.ts               %% IR store (roles, tasks)
├── rasciRenderer.ts         %% SVG/HTML table renderer
└── rasciDiagram.spec.ts     %% unit + snapshot tests

Open questions for the Mermaid team

1. Jison vs hand-written parser — RASCI's indentation-sensitive grammar
   is awkward to express in Jison (which is context-free). A hand-written
   tokeniser that emits INDENT/DEDENT tokens would be more robust.
   Does the team have a preference?

2. SVG vs HTML table — Mermaid renders everything as SVG. A RASCI
   matrix is inherently tabular; an <svg> with manually positioned
   <text> elements is possible but loses browser table semantics
   (accessibility, copy-paste, print). Would an HTML-output path be
   acceptable for this diagram type, similar to how some tools handle it?

3. Export format — Should JSON export (machine-readable matrix) be a
   first-class output, accessible via mermaid.render() options, or is
   that out of scope for the core library?

4. Diagram name — rasci is unambiguous but niche. raci is more
   widely recognised (the S for Supportive is often omitted).
   responsibility-matrix is descriptive but verbose. Suggestion: accept
   rasci as the keyword, document RACI as a compatible subset.