Concepts

Overview

The Vithanco Graph Language (VGL) is a human-readable text format for creating and editing graphs. VGL provides a simple, declarative syntax for defining nodes, edges, groups, and their attributes.

Notation

Every VGL document must declare a notation, which defines the types of nodes and edges available in the graph.

Syntax:

vgraph <graph_id>: <NOTATION> "<graph_label>" {
    ...
}

VGL supports both built-in notations and user-defined notations declared with vnotation (see User-Defined Notations). Built-in notations come with predefined node types and edge types:

• IBIS (Issue-Based Information System) - for decision-making and argumentation
• BBS (Benefit Breakdown Structure) - for benefit analysis
• ImpactMapping - for strategic planning and goal alignment
• ConceptMap - for defining domain vocabulary through falsifiable propositions that help people align on shared understanding
• CRT (Current Reality Tree) - for root cause analysis using Theory of Constraints
• EC (Evaporating Cloud) - for conflict resolution using Theory of Constraints necessary condition logic
• FRT (Future Reality Tree) - for solution validation using Theory of Constraints
• PRT (Prerequisite Tree) - for planning with necessary condition thinking using Theory of Constraints
• TRT (Transition Tree) - for step-by-step implementation planning using Theory of Constraints
• ADTree (Attack-Defense Tree) - for security modelling of attack and defense interactions
• GoalTree (Goal Tree) - for strategic planning using Theory of Constraints necessity logic
• CLD (Causal Loop Diagram) - for systems analysis modelling how elements reinforce or balance each other over time
• DecisionTree (Decision Tree) - for storing and evaluating decision logic through questions, choices, and outcomes
• Timeline (Timeline) - for visualizing events across multiple tracks aligned to a shared time axis

The notation determines what node types and edge types are available in your graph.

Extensions

Extensions add cross-cutting node types to any notation. They are listed after the notation, separated by commas:

vgraph <graph_id>: <NOTATION>, <EXTENSION> "<graph_label>" {
    ...
}

Multiple extensions can be combined:

vgraph myGraph: ConceptMap, Annotation "My Diagram" { ... }

Available extensions:

• Annotation - adds an Annotation node type that can be connected FROM any node in the notation. Use it to attach notes, comments, or clarifications to any element of the diagram.

Annotation example:

vgraph productMap: ConceptMap, Annotation "Product Strategy" {
    node c1: Concept "Customer Need"
    node r1: Relation "drives"
    node c2: Concept "Feature"
    node a1: Annotation "Validated in user research"
    edge c1 -> r1
    edge r1 -> c2
    edge c1 -> a1
}

Edge types from notation nodes to Annotation are automatically inferred, so no explicit : annotates__Concept type is needed on annotation edges.

Diagram Logic and Junctors

Each notation has a diagram logic: noLogic, sufficientCause, or necessaryCondition. The logic determines how multiple arrows pointing into the same node are read, and which junctor (AND, OR) needs to be an explicit node.

Diagram logic	Multiple unjoined arrows mean…	Explicit junctor needed	Implicit (don't add as a node)
sufficientCause	OR — any one arrow is enough	AND — all inputs required together	OR
necessaryCondition	AND — all arrows are required	OR — alternative paths	AND
noLogic	Notation-defined	—	—

Rule of thumb: add only the exception junctor for your logic. For sufficient-cause notations (CRT, FRT, ADTree, TRT) declare an AndJunctor only when you need "all of these together." For necessary-condition notations (EC, PRT, GoalTree) declare an OrJunctor only when you need "any one of these alternatives." Adding the implicit junctor produces a redundantJunctor quality warning, since direct edges already express the same semantics with less visual noise.

This applies equally to user-defined notations declared with vnotation — match the junctor you expose to the diagram logic you choose.

Nodes

Nodes represent the primary entities in your graph. Each node has:

• ID: A unique identifier (required)
• Type: The kind of node, determined by the notation (required)
• Label: A human-readable display name (optional)
• Attributes: Additional properties like color, fontsize, etc. (optional)

Syntax:

node <id>: <NodeType> "<label>" [<attributes>];

Example:

node q1: Question "What should we do?" [fontsize: 16; color: red];

Node Types

Node types are defined by the chosen notation. Each notation has its own set of node types with specific purposes and default styling.

IBIS Node Types:

• Question - A question or issue to be resolved (default: blue)
• Answer - A proposed answer or solution (default: pink)
• Pro - An argument supporting an answer (default: green)
• Con - An argument opposing an answer (default: red)

BBS Node Types:

• InvestmentObjective - High-level business objective
• Benefit - Expected benefit from the investment
• BusinessChange - Organizational or process change required
• Enabler - Technology or capability enabler

ImpactMapping Node Types:

• Goal - Strategic goal or objective (default: dark blue)
• Actor - Person or group who can produce impact (default: blue)
• Impact - Behavioral change or outcome (default: cyan)
• Deliverable - Product feature or capability (default: green)

ConceptMap Node Types:

• Concept - A concept or term
• EmphasizedConcept - An important concept to highlight
• Relation - A linking verb or phrase connecting concepts (forms propositions: Concept → Relation → Concept)

CRT Node Types:

CRT uses sufficient-cause logic, so multiple unjoined causes feeding the same effect are implicitly OR (any one is sufficient). Only AND is an explicit junctor.

• UndesirableEffect - An unwanted outcome requiring investigation (default: red)
• IntermediateEffect - A neutral outcome in the causal chain (default: blue)
• DesirableEffect - A wanted outcome caused by other conditions (default: green)
• Given - An unchangeable constant like laws or physics (default: dark purple)
• Changeable - A modifiable condition that can be addressed (default: light purple)
• AndJunctor - Indicates multiple conditions required together to produce the downstream effect (icon: AND circle)

FRT Node Types: FRT shares the same node types as CRT, as both are Theory of Constraints tools that use sufficient-cause logic. The difference is in usage: FRT starts with solutions (Changeable/injections) and builds upward to show how they lead to desirable effects. Multiple unjoined inputs into one effect are implicitly OR.

• Changeable - Proposed solutions or injections to implement (default: light purple)
• Given - Unchangeable facts that still apply (default: dark purple)
• IntermediateEffect - Expected intermediate outcomes from solutions (default: blue)
• DesirableEffect - Goals we want to achieve (default: green)
• UndesirableEffect - Potential negative side effects to monitor (default: red)
• AndJunctor - Indicates multiple conditions required together to produce the downstream effect (icon: AND circle)

EC Node Types: EC (Evaporating Cloud) is a conflict resolution tool using necessary-condition logic. It surfaces the assumptions behind a conflict and finds breakthrough solutions. The graph flows left-to-right from Common Objective to Conflict. Multiple necessary inputs are implicitly AND; OR is the explicit junctor for alternative paths.

• CommonObjective - The shared objective valid for both sides of the conflict (default: green)
• Need - A perceived need that must be met (default: blue)
• Want - A perceived want derived from a need (default: orange)
• Conflict - The perceived conflict expressed as mutually exclusive wants (icon: lightning bolt circle, no text)
• OrJunctor - Marks alternative necessary inputs — any one of them suffices for the downstream condition (icon: OR circle)
• Assumption - Exposes the underlying assumptions behind the conflict (default: purple)
• Solution - Marks the final solution that breaks the conflict (default: teal)

PRT Node Types: PRT (Prerequisite Tree) is a planning tool using necessary condition thinking. It starts with the desired objective and works backward to identify obstacles and the intermediate objectives needed to overcome them.

• Objective - The desired goal you aim to achieve (default: green)
• Obstacle - Barriers preventing objective achievement (default: red)
• IntermediateObjective - A milestone that overcomes a specific obstacle (default: blue)
• OR - Connector allowing optional conditions instead of requiring all predecessors (icon: OR circle)

TRT Node Types: TRT (Transition Tree) is an implementation planning tool that answers "HOW TO CAUSE the change?" by providing step-by-step actions needed to implement changes. It shares node types with CRT/FRT but focuses on the detailed action sequence.

• UndesirableEffect - Current state problems being addressed (default: red)
• IntermediateEffect - Stepping stone outcomes from actions (default: blue)
• DesirableEffect - Goal outcomes we want to achieve (default: green)
• Given - Unchangeable facts and constraints (default: dark purple)
• Changeable - Actions we can take to cause change (default: light purple)
• AndJunctor - Indicates multiple conditions required together for an effect (icon: AND circle)

ADTree Node Types: ADTree (Attack-Defense Tree) is a security modelling methodology based on Kordy et al. (2014). It extends classical attack trees by allowing defense nodes at any level, modelling the ongoing arms race between attacker and defender. ADTree uses sufficient-cause logic — multiple unjoined children are implicitly OR (any one suffices); only AND is an explicit junctor.

• Attack - An attacker's goal or sub-goal (default: red)
• Defense - A defender's countermeasure or protective measure (default: green)
• AndJunctor - Conjunctive refinement: all children must be achieved together (icon: AND circle)

GoalTree Node Types: GoalTree (Goal Tree) is a strategic planning tool using necessity condition logic from Theory of Constraints. It defines what a system must achieve through a hierarchy of Goal, Critical Success Factors, and Necessary Conditions. Invented by H. William Dettmer, it is the foundation of the Logical Thinking Process.

• Goal - The single top-level objective — the ultimate purpose for which the system exists (default: cyan/teal)
• CriticalSuccessFactor - High-level terminal outcomes (3-5 maximum) without which the Goal cannot be achieved (default: light blue)
• NecessaryCondition - Indispensable prerequisite tasks that support CSFs; can cascade into sub-NCs becoming more specific at lower levels (default: amber/yellow)

CLD Node Types: CLD (Causal Loop Diagram) is a systems analysis tool for modelling how elements interconnect and reinforce or balance each other over time. All elements are represented as Stocks whose amounts can change based on incoming connections.

• Stock - A variable or element in the system whose value changes over time (default: blue)

DecisionTree Node Types:

• DecisionPoint - A question that determines which path to follow (default: amber)
• Choice - A potential answer or path branching from a question (default: blue)
• Outcome - A terminal result of the decision tree (default: green)

Timeline Node Types:

• TimePoint - An axis marker representing a point in time (default: gray, optional)
• Event - A generic event that can be aligned to a time point via alignGroup (default: steel blue)

Edges

Edges represent connections between nodes. Each edge has:

• From: Source node ID (required)
• To: Target node ID (required)
• Type: The kind of connection (optional, can be inferred)
• Label: A description of the relationship (optional)
• Attributes: Additional properties like style, weight, etc. (optional)

Syntax:

edge <from_id> -> <to_id>: <EdgeType> "<label>" [<attributes>];

Concise Syntax (omitting type):

edge <from_id> -> <to_id>;

When the edge type is omitted, VGL will automatically infer it based on the connected node types, if unambiguous.

Example:

edge q1 -> a1: answered_by "Initial solution";
edge a1 -> pro1 [style: dashed];
edge q2 -> a2;  // Type inferred from node types

Edge Types

Edge types are defined by the notation and specify valid connections between node types.

IBIS Edge Types:

• answered_by - Connects Question → Answer
• supports - Connects Answer → Pro
• objects_to - Connects Answer → Con
• pro_questions_question - Connects Pro → Question
• con_questions_question - Connects Con → Question

BBS Edge Types:

• requires_benefit - Connects Benefit → InvestmentObjective
• requires_business_change - Connects BusinessChange → Benefit
• requires_enabler - Connects Enabler → BusinessChange
• change_requires_change - Connects BusinessChange → BusinessChange
• enabler_requires_enabler - Connects Enabler → Enabler

ImpactMapping Edge Types:

• goal_to_actor - Connects Goal → Actor
• actor_to_impact - Connects Actor → Impact
• impact_to_deliverable - Connects Impact → Deliverable

ConceptMap Edge Types:

• concept_to_relation - Connects Concept → Relation (tail marker only)
• relation_to_concept - Connects Relation → Concept (arrow head only)

CRT Edge Types: CRT has many edge types connecting causes to effects. The graph flows bottom-to-top (causes at bottom, effects at top).

From effects to effects:

• undesirable_causes_undesirable, undesirable_causes_intermediate, undesirable_causes_desirable
• intermediate_causes_undesirable, intermediate_causes_intermediate, intermediate_causes_desirable
• desirable_causes_undesirable, desirable_causes_intermediate, desirable_causes_desirable

From Given/Changeable to effects:

• given_causes_undesirable, given_causes_intermediate, given_causes_desirable
• changeable_causes_undesirable, changeable_causes_intermediate, changeable_causes_desirable

To/From AndJunctor:

• *_to_and_junctor - Connect any type to AndJunctor
• and_junctor_causes_* - Connect AndJunctor to effects

FRT Edge Types: FRT shares the same edge types as CRT. The graph flows bottom-to-top (solutions at bottom, desired effects at top).

From Changeable/Given to effects (typical starting points in FRT):

• changeable_causes_undesirable, changeable_causes_intermediate, changeable_causes_desirable
• given_causes_undesirable, given_causes_intermediate, given_causes_desirable

Between effects:

• intermediate_causes_undesirable, intermediate_causes_intermediate, intermediate_causes_desirable
• desirable_causes_*, undesirable_causes_*

To/From AndJunctor:

• *_to_and_junctor - Connect any type to AndJunctor
• and_junctor_causes_* - Connect AndJunctor to effects

EC Edge Types: EC uses edges to show necessary condition relationships flowing from shared objective through needs and wants to the conflict. The graph flows left-to-right (Common Objective on left, Conflict on right).

From Common Objective:

• objective_to_need - Connects CommonObjective → Need
• objective_to_or - Connects CommonObjective → OrJunctor

From Need:

• need_to_want - Connects Need → Want
• need_to_or - Connects Need → OrJunctor
• need_to_assumption - Connects Need → Assumption
• need_to_solution - Connects Need → Solution

From Want:

• want_to_conflict - Connects Want → Conflict
• want_to_or - Connects Want → OrJunctor
• want_to_assumption - Connects Want → Assumption

From Conflict:

• conflict_to_or - Connects Conflict → OrJunctor
• conflict_to_assumption - Connects Conflict → Assumption

From OrJunctor:

• or_to_want - Connects OrJunctor → Want
• or_to_conflict - Connects OrJunctor → Conflict
• or_to_or - Connects OrJunctor → OrJunctor

PRT Edge Types: PRT uses edges to show how obstacles block objectives and how intermediate objectives overcome obstacles. The graph flows bottom-to-top (intermediate objectives at bottom, main objective at top).

Obstacle blocking relationships:

• obstacle_blocks_objective - Connects Obstacle → Objective
• obstacle_blocks_intermediate_objective - Connects Obstacle → IntermediateObjective

Intermediate objective relationships:

• intermediate_objective_overcomes_obstacle - Connects IntermediateObjective → Obstacle
• intermediate_objective_to_objective - Connects IntermediateObjective → Objective (direct path)

To/From OR Junctor:

• obstacle_to_or, intermediate_objective_to_or - Connect to OR junctor
• or_to_objective, or_to_intermediate_objective, or_to_obstacle - Connect from OR junctor

TRT Edge Types: TRT shares similar edge types with CRT/FRT but focuses on action planning. The graph flows bottom-to-top (actions at bottom, desired effects at top).

From Changeable/Given to effects (typical starting points for actions):

• changeable_causes_undesirable, changeable_causes_intermediate, changeable_causes_desirable
• given_causes_undesirable, given_causes_intermediate, given_causes_desirable

Between effects:

• intermediate_causes_undesirable, intermediate_causes_intermediate, intermediate_causes_desirable
• desirable_causes_*, undesirable_causes_*

To/From And Junctor:

• *_to_and_junctor - Connect any type to And junctor
• and_junctor_causes_* - Connect And junctor to effects (excluding And)

ADTree Edge Types: ADTree uses two kinds of edges: refinement edges (solid lines) for same-type decomposition, and countermeasure edges (dotted lines) for opposite-type countering. The graph flows top-to-bottom (root goal at top).

Refinement edges (solid):

• attack_refines_attack - Decompose an attack into sub-attacks
• defense_refines_defense - Decompose a defense into sub-defenses

Countermeasure edges (dotted):

• defense_counters_attack - A defense that mitigates an attack
• attack_counters_defense - An attack that circumvents a defense

To/From AND Junctor:

• attack_to_and_junctor, defense_to_and_junctor - Connect to AND junctor
• and_junctor_to_attack, and_junctor_to_defense - Connect from AND junctor

GoalTree Edge Types: GoalTree uses edges to show necessity relationships. The graph flows top-to-bottom (Goal at top, Necessary Conditions expand downward). The necessity logic reads: "In order to achieve [upper], we must have [lower]."

• csf_to_goal - Connects CriticalSuccessFactor → Goal (CSF is necessary for Goal)
• nc_to_csf - Connects NecessaryCondition → CriticalSuccessFactor (NC is necessary for CSF)
• nc_to_nc - Connects NecessaryCondition → NecessaryCondition (sub-NC supports parent NC)

CLD Edge Types: CLD uses two edge types representing positive and negative causal links between Stocks. Loops with an even number of negative links (including zero) are reinforcing; loops with an odd number are balancing.

• same - Connects Stock → Stock (positive causal link: both change in the same direction, solid line, marked "s")
• opposite - Connects Stock → Stock (negative causal link: nodes change in opposite directions, dashed line, marked "o")

DecisionTree Edge Types:

• decision_to_choice - Connects DecisionPoint → Choice (the question branches into options)
• choice_to_decision - Connects Choice → DecisionPoint (the option leads to a further question)
• choice_to_outcome - Connects Choice → Outcome (the option terminates at a result)

Timeline Edge Types:

• sequence - Connects TimePoint → TimePoint (creates the time axis, thin gray line)
• influence - Connects Event → Event (cross-track or within-track dependency, dashed, constraint=false)

Edge types ensure that connections make semantic sense within the notation's domain.

Groups

Groups organize nodes hierarchically and can be nested to create subgroups. Groups help visually organize complex graphs.

Syntax:

group <id> "<label>" {
    <attributes>;
    <nodes>;
    <edges>;
    <nested_groups>;
};

Features:

• Groups can contain nodes, edges, and other groups
• Groups can have attributes like style, color, label
• Groups can be nested to unlimited depth
• Edges can connect nodes across different groups

Example:

group research "Research Phase" {
    style: filled;
    color: lightblue;

    node q1: Question "What to research?";
    node a1: Answer "User interviews";

    group methodology "Methods" {
        node m1: Pro "Direct feedback";
    };
};

Attributes

Attributes customize the appearance and behavior of nodes, edges, and groups.

Inline Syntax (brackets):

[attribute1: value1; attribute2: value2]

Graph-Level Attributes (inside graph body):

rankdir: LR;
fontcolor: darkblue;

Common Node Attributes:

• color - Node color (e.g., red, blue, #FF0000)
• fontsize - Font size for node label (number)
• shape - Node shape (varies by notation)
• alignGroup - Alignment group identifier; nodes sharing the same value are placed at the same rank in layout (used by Timeline and available in all notations)

Common Edge Attributes:

• style - Line style (solid, dashed, dotted)
• weight - Edge weight (number)
• label - Edge label text

Common Group Attributes:

• style - Group style (filled, dashed, dotted)
• color - Group background or border color
• label - Group display name

Common Graph Attributes:

• rankdir - Layout direction (LR for left-to-right, TB for top-to-bottom)
• fontcolor - Default font color
• labeljust - Label justification (l for left, r for right, c for center)

Comments

VGL supports single-line comments using //:

// This is a comment
node q1: Question "Main question";  // This is also a comment

Comments can appear anywhere in the document and are ignored by the parser.

---