Vithanco
Home / The best Tools for Structured Visual Thinking / Vithanco Graph Language (VGL) Guide

Vithanco Graph Language (VGL) Guide

Estimated reading time: 2 minutes.

VGL is a small, declarative text format for describing graphs — diagrams made of nodes, edges, groups, and attributes. A VGL document is plain text that any editor can produce, any reviewer can diff, and any version-control tool can track. The Vithanco app reads VGL and renders it in a chosen notation (IBIS, Concept Map, Causal Loop Diagram, Goal Tree, Timeline, and many more), so the same text file can be read as prose by a human and as a typed graph by the tool.

Use VGL when you want the structure of a diagram in source form — for collaboration over pull requests, for embedding diagrams in documentation, for generating diagrams programmatically, or simply for editing complex graphs faster than you could by clicking. Each notation defines its own node and edge types and the rules that connect them, and VGL enforces those rules so you can't draw an invalid diagram.

If you're new to VGL, start with Concepts for the model (nodes, edges, groups, attributes) and Grammar for the formal syntax. Then jump to Examples for one runnable diagram per built-in notation. If you want to define your own notation rather than use a built-in one, see User-Defined Notations.

Contents

Best Practices

  1. Use Meaningful IDs: Choose descriptive node IDs like security_question instead of n1
  2. Organize with Groups: Use groups to organize related nodes and improve readability
  3. Leverage Type Inference: Omit edge types when they can be inferred from node types
  4. Add Labels: Always provide labels for better human readability
  5. Comment Your Graphs: Use comments to explain complex relationships or decisions
  6. Keep It Simple: Start with minimal syntax and add attributes only when needed
  7. Consistent Naming: Use a consistent naming convention for IDs (e.g., snake_case or camelCase)
  8. Hierarchical Organization: Use nested groups to reflect the natural hierarchy of your domain

Error Handling

VGL provides clear error messages for common issues:

  • Duplicate Node ID: Each node ID must be unique
  • Undefined Node Reference: Edges can only reference existing nodes
  • Invalid Node Type: Node types must exist in the chosen notation (creates "unknown" type)
  • Invalid Edge Type: Edge types must be valid for the connected node types (creates "unknown" edge type)
  • Syntax Errors: Missing semicolons, braces, or other syntax requirements

When a node type or edge type is not found in the notation, VGL will create an "unknown" type to allow the graph to be processed, but you should verify that the type names are correct.