vis.js Network Format Reference for Learning Graph Generator¶

Overview¶

This document defines the standard JSON format for learning graphs compatible with the vis.js Network library. Use this format when generating learning graphs to ensure proper visualization.

Purpose¶

When using the Learning Graph Generator skill, the final JSON output must conform to this specification to work with vis.js network visualizations commonly used in educational web applications.

JSON Structure¶

Top-Level Schema¶

{
  "nodes": [...],
  "edges": [...],
  "metadata": {...}
}

Complete Example¶

{
  "nodes": [
    {
      "id": 1,
      "label": "Complex Numbers",
      "group": "MATH"
    },
    {
      "id": 2,
      "label": "Euler's Formula",
      "group": "MATH"
    }
  ],
  "edges": [
    {
      "from": 1,
      "to": 2
    }
  ],
  "metadata": {
    "title": "Course Learning Graph",
    "description": "200 interconnected concepts",
    "nodeCount": 200,
    "edgeCount": 229,
    "taxonomies": {
      "MATH": "Mathematical Foundations",
      "FFT": "FFT Algorithm & Implementation"
    }
  }
}

Node Format¶

Required Properties¶

Property	Type	Description	Example
`id`	number	Unique identifier (1-based index)	`1`, `2`, `3`
`label`	string	Display text (max 32 chars)	`"Complex Numbers"`

Optional Properties¶

Property	Type	Description	Example
`group`	string	Taxonomy/category for styling	`"MATH"`, `"FFT"`
`title`	string	Tooltip text on hover	`"Foundational concept"`
`shape`	string	Node shape	`"dot"`, `"box"`, `"star"`
`color`	string	Override group color	`"red"`, `"#FF0000"`
`x`	number	Fixed horizontal position	`-900`, `900`
`y`	number	Fixed vertical position	`0`, `100`
`fixed`	object	Lock position	`{"x": true, "y": false}`

Node Example with All Properties¶

{
  "id": 1,
  "label": "Complex Numbers",
  "group": "MATH",
  "title": "Foundational mathematical concept",
  "shape": "box",
  "color": "red",
  "x": -900,
  "fixed": {"x": true, "y": false}
}

Edge Format¶

Required Properties¶

Property	Type	Description	Example
`from`	number	Source node ID (prerequisite)	`1`
`to`	number	Target node ID (dependent)	`2`

Optional Properties¶

Property	Type	Description	Example
`arrows`	string/object	Arrow direction	`"to"`, `{"to": true}`
`color`	string	Edge color	`"gray"`, `"#888888"`
`width`	number	Edge thickness	`1`, `2`, `3`
`label`	string	Text on edge	`"prerequisite"`
`dashes`	boolean/array	Dashed line style	`true`, `[5, 5]`

Edge Example¶

{
  "from": 1,
  "to": 2,
  "arrows": "to",
  "color": "gray",
  "width": 1
}

Metadata Format¶

Optional but recommended for documentation and analytics.

Standard Metadata Properties¶

{
  "metadata": {
    "title": "FFT Benchmarking Course Learning Graph",
    "description": "200 interconnected concepts for a 10-week course",
    "nodeCount": 200,
    "edgeCount": 229,
    "version": "1.0",
    "generated": "2025-10-30",
    "taxonomies": {
      "MATH": "Mathematical Foundations",
      "FFT": "FFT Algorithm & Implementation",
      "SIG": "Signal Processing",
      "ARM": "ARM Architecture & DSP Hardware",
      "MEM": "Memory Management & Optimization",
      "FXP": "Fixed-Point Arithmetic",
      "BENCH": "Benchmarking & Testing",
      "LIB": "FFT Libraries & Integration",
      "OPT": "Optimization Techniques"
    }
  }
}

Important Distinctions¶

❌ WRONG: D3.js Format¶

{
  "nodes": [
    {
      "id": 1,
      "label": "Complex Numbers",
      "taxonomy": "MATH"          // ❌ Wrong property name
    }
  ],
  "links": [                      // ❌ Wrong array name
    {
      "source": 1,                // ❌ Wrong property name
      "target": 2                 // ❌ Wrong property name
    }
  ]
}

✅ CORRECT: vis.js Format¶

{
  "nodes": [
    {
      "id": 1,
      "label": "Complex Numbers",
      "group": "MATH"             // ✅ Correct for vis.js
    }
  ],
  "edges": [                      // ✅ Correct array name
    {
      "from": 1,                  // ✅ Correct property name
      "to": 2                     // ✅ Correct property name
    }
  ]
}

Python Conversion Template¶

Standard CSV to vis.js JSON Converter¶

#!/usr/bin/env python3
"""
Convert concept dependencies CSV to vis.js network JSON format.
"""

import csv
import json

def convert_csv_to_json(csv_file, json_file):
    """Convert CSV to vis.js network format."""
    nodes = []
    edges = []

    with open(csv_file, 'r') as f:
        reader = csv.DictReader(f)

        for row in reader:
            concept_id = int(row['ConceptID'])
            label = row['ConceptLabel']
            taxonomy = row['TaxonomyID']
            deps = row['Dependencies'].strip()

            # Create node (vis.js format)
            node = {
                "id": concept_id,
                "label": label,
                "group": taxonomy
            }
            nodes.append(node)

            # Create edges (vis.js format: from/to)
            if deps:
                dependencies = [int(d) for d in deps.split('|')]
                for dep in dependencies:
                    edge = {
                        "from": dep,
                        "to": concept_id
                    }
                    edges.append(edge)

    # Create graph structure
    graph = {
        "nodes": nodes,
        "edges": edges,
        "metadata": {
            "title": "Learning Graph",
            "nodeCount": len(nodes),
            "edgeCount": len(edges)
        }
    }

    # Write to JSON file
    with open(json_file, 'w') as f:
        json.dump(graph, f, indent=2)

    return graph

JavaScript Loading Template¶

Standard vis.js Network Initialization¶

function drawGraph() {
  // Fetch the graph data from JSON file
  fetch('learning-graph.json')
    .then(response => response.json())
    .then(data => {
      // Create DataSets for vis.js
      const nodes = new vis.DataSet(data.nodes);
      const edges = new vis.DataSet(data.edges);

      // Optional: Customize nodes after loading
      nodes.forEach(function (node) {
        if (node.group === "MATH") {
          node.x = -900;
          node.fixed = { x: true, y: false };
          node.shape = "box";
          node.color = "red";
        } else if (node.group === "OPT") {
          node.x = 900;
          node.fixed = { x: true, y: false };
          node.shape = "star";
          node.color = "gold";
        }
      });

      // Create network
      const container = document.getElementById('mynetwork');
      const graphData = {
        nodes: nodes,
        edges: edges
      };

      // Network options
      const options = {
        physics: {
          enabled: true,
          solver: 'forceAtlas2Based',
          stabilization: {
            iterations: 1000,
            updateInterval: 25
          }
        },
        edges: {
          arrows: {
            to: {
              enabled: true,
              type: 'arrow'
            }
          },
          smooth: {
            type: 'continuous'
          }
        },
        nodes: {
          shape: 'dot',
          size: 20,
          font: {
            size: 14,
            color: 'black'
          },
          borderWidth: 2
        }
      };

      // Initialize network
      const network = new vis.Network(container, graphData, options);
    })
    .catch(error => {
      console.error("Error loading JSON:", error);
    });
}

Group/Taxonomy Colors¶

Recommended color scheme for educational taxonomy groups:

const taxonomyColors = {
  "MATH": "#E74C3C",    // Red - Foundational
  "FFT": "#3498DB",     // Blue - Core algorithms
  "SIG": "#2ECC71",     // Green - Signal processing
  "ARM": "#9B59B6",     // Purple - Hardware
  "MEM": "#F39C12",     // Orange - Memory
  "FXP": "#1ABC9C",     // Teal - Numeric precision
  "BENCH": "#E67E22",   // Dark orange - Testing
  "LIB": "#95A5A6",     // Gray - Libraries
  "OPT": "#F1C40F"      // Yellow/Gold - Optimization
};

Validation Checklist¶

When generating learning graph JSON for vis.js, verify:

[ ] Top-level object has nodes array (not vertices)
[ ] Top-level object has edges array (not links)
[ ] Each node has id (number) and label (string)
[ ] Nodes use group property (not taxonomy or category)
[ ] Each edge has from (number) and to (number)
[ ] Edges use from/to (not source/target)
[ ] All from and to values reference valid node IDs
[ ] No self-loops (edge where from === to)
[ ] Graph forms valid DAG (no cycles) for learning paths
[ ] Optional: metadata object included for documentation

Common Mistakes to Avoid¶

Mistake	Issue	Solution
Using `links`	vis.js won't find edges	Use `edges`
Using `source`/`target`	Edges won't connect	Use `from`/`to`
Using `taxonomy`	Groups won't work	Use `group`
String IDs	Type mismatch errors	Use numeric IDs
Missing `label`	Blank nodes	Always include labels
Circular edges	Cycles in learning path	Validate DAG structure

File Naming Convention¶

Recommended: - learning-graph.json - Main graph file - concept-dependencies.csv - Source CSV file - convert-to-json.py - Conversion script

Not Recommended: - graph.json - Too generic - network.json - Ambiguous - data.json - Not descriptive

vis.js Documentation References¶

Official docs: https://visjs.github.io/vis-network/docs/network/
Node options: https://visjs.github.io/vis-network/docs/network/nodes.html
Edge options: https://visjs.github.io/vis-network/docs/network/edges.html
Physics: https://visjs.github.io/vis-network/docs/network/physics.html
Examples: https://visjs.github.io/vis-network/examples/

Summary for SKILL Generation¶

Quick Reference Card¶

For Learning Graph Generator Skill:

Array names: nodes and edges (not links/vertices)
Node structure: {id: number, label: string, group: string}
Edge structure: {from: number, to: number}
Group property: Use for taxonomy categories (enables coloring)
Metadata: Optional but recommended for documentation
Validation: Ensure DAG structure (no cycles)
Python template: Use provided converter code
Testing: Load in vis.js Network to verify rendering

Integration Workflow¶

CSV (concept-dependencies.csv)
    ↓
Python Script (convert-to-json.py)
    ↓
JSON (learning-graph.json) [vis.js format]
    ↓
HTML + JavaScript (vis.Network)
    ↓
Interactive Graph Visualization

Document Version: 1.0 Created: 2025-10-30 For Use With: Learning Graph Generator Skill Target Library: vis.js Network v9.x+ Status: Production-ready reference