bte
Notation Log in

Notation

BT/Modern: a small textual notation for what a system does, and the picture it projects to.

Legend

  • COMPONENT [behaviour] (line 1) COMPONENT [behaviour]
    State / behaviour
    A component exhibits a behaviour or is in a state: SESSION [authenticated], TEMP [monitoring].
  • COMPONENT :event (line 1) COMPONENT :event
    Event
    An occurrence or action on a component that triggers behaviour: USER :login, DOOR :opened.
  • ? condition (line 1) ? condition
    Condition
    A predicate that decides whether the path beneath it applies: ? credentials-valid, ? temperature > 90C.
  • COMPONENT [behaviour] #R1 (line 1) COMPONENT [behaviour] #R1
    Requirement tag
    The requirement that justifies this behaviour. A node may cite several.
  • COMPONENT [behaviour] #? (line 1) COMPONENT [behaviour] #?
    Missing requirement
    Behaviour that seems necessary but that no requirement asks for. Replace it with an identifier once the requirement exists.
  • yes no ? condition (line 1) ? condition A [handled] (line 2) A [handled] Not in the model: this outcome has no behaviour. Add it, tagged #? until a requirement covers it. MISSING BEHAVIOUR when not: condition #?
    Missing outcome
    An analysis overlay: a dashed ghost where a condition has only one outcome handled, joined by a dashed inferred flow.

A file

A leading comment names and describes the model. Requirements are one per line. Then the tree: a child is indented under its parent, drawn with box characters or plain spaces.

// Login
// A user logs in and a session opens when the credentials are valid.

R1: A user shall be able to log in.
R2: Valid credentials shall open a session.

USER :login                      #R1
└─ AUTH [checking]               #R1
   ├─ ? credentials-valid        #R2
   │  └─ SESSION [authenticated] #R2
   └─ ? credentials-invalid      #?
      └─ SESSION [rejected]      #?

Grammar

NODE      := STATE | EVENT | CONDITION
STATE     := COMPONENT "[" BEHAVIOUR "]"
EVENT     := COMPONENT ":" NAME
CONDITION := "?" EXPRESSION
TRACE     := "#" REQUIREMENT-ID      e.g. #R1, #REQ-12
MISSING   := "#?"
TREE      := NODE TRACE* MISSING? COMMENT?
             CHILDREN*
REQ       := REQUIREMENT-ID ":" TEXT   at the left margin, before the tree
COMMENT   := "//" TEXT

Rules of thumb

  1. Model externally or logically significant behaviour, not implementation mechanisms. Mutexes, queues, retries and transactions belong in a design document.
  2. Prefer component-oriented statements: COMPONENT [behaviour]. Use events for things that happen and states for things that hold.
  3. Use a condition only when behaviour depends on a predicate, and write the other outcome as a sibling condition -- ? valid beside ? invalid -- so the decision is complete.
  4. Attach requirement provenance wherever practical. Use #? the moment behaviour is inferred but unspecified, and replace it once the requirement exists.
  5. Add syntax only when a real class of requirements cannot be expressed with the core.

Simple sequence

A user logs in and a session becomes authenticated. The diagram raises the question the text leaves open: what if the credentials are invalid?

USER :login                 #R1
└─ AUTH [checking]          #R1
   └─ ? credentials-valid   #R1
      └─ SESSION [authenticated] #R1
yes no USER :login #R1 (line 1) USER :login #R1 AUTH [checking] #R1 (line 2) AUTH [checking] #R1 ? credentials-valid #R1 (line 3) ? credentials-valid #R1 SESSION [authenticated] #R1 (line 4) SESSION [authenticated] #R1 Not in the model: this outcome has no behaviour. Add it, tagged #? until a requirement covers it. MISSING BEHAVIOUR when not: credentials-valid #?

Conditional branching, complete

Both outcomes are specified. Two sibling conditions that are each other's negation are drawn as one decision with a yes and a no branch.

USER :login                      #R1
└─ AUTH [checking]               #R1
   ├─ ? credentials-valid        #R1
   │  └─ SESSION [authenticated] #R1
   └─ ? credentials-invalid      #R2
      └─ SESSION [rejected]      #R2
yes no #R2 USER :login #R1 (line 1) USER :login #R1 AUTH [checking] #R1 (line 2) AUTH [checking] #R1 ? credentials-valid #R1 (line 3) ? credentials-valid #R1 SESSION [authenticated] #R1 (line 4) SESSION [authenticated] #R1 SESSION [rejected] #R2 (line 6) SESSION [rejected] #R2

A system with analysis overlays

Start, run with monitoring, stop on overheating. The ordinary temperature-normal case is not modelled, and the overlay says so.

// Simple System
// A system that starts on request, monitors its temperature while
// running, and stops when it overheats. The "temperature normal" case is
// not modelled, which the analysis points out.

R1: The system shall initially be idle.
R2: When the user starts the system, it shall run.
R3: While running, the API shall listen for requests.
R4: While running, temperature shall be monitored.
R5: If temperature exceeds 90C, the system shall stop.

SYSTEM [idle]                   #R1
└─ USER :start                  #R2
   └─ SYSTEM [running]          #R2
      ├─ API [listening]        #R3
      └─ TEMP [monitoring]      #R4
         └─ ? temperature > 90C #R5
            └─ SYSTEM [stopped] #R5
yes no SYSTEM [idle] #R1 (line 12) SYSTEM [idle] #R1 USER :start #R2 (line 13) USER :start #R2 SYSTEM [running] #R2 (line 14) SYSTEM [running] #R2 API [listening] #R3 (line 15) API [listening] #R3 TEMP [monitoring] #R4 (line 16) TEMP [monitoring] #R4 ? temperature > 90C #R5 (line 17) ? temperature > 90C #R5 SYSTEM [stopped] #R5 (line 18) SYSTEM [stopped] #R5 Not in the model: this outcome has no behaviour. Add it, tagged #? until a requirement covers it. MISSING BEHAVIOUR when not: temperature > 90C #?

Questions a tree should answer

QuestionHow to answer
What happens after event X?Follow the descendants of the event.
What causes state Y?Walk backward from the state.
What can component C do?The Components panel lists every state and event of C.
Which requirement justifies behaviour B?Read its #R tag.
Which behaviour lacks a requirement?The #? nodes; the Analysis panel lists them.
What happens when a condition is false?Look for a complementary sibling; the diagram draws a ghost where there is none.
Is a leaf intentional?Confirm that termination is specified; the analysis notes every dead end.