The JSON format is still experimental and not part of a release. Please refer to nightly builds to try it.

The JSON Graph Format

JSON (JavaScript Object Notation) is an open standard format that is widely used and accepted as interchange format on the web. JSON consists of arbitrary key-value pairs. We specify some conventions to represent a graph within this format.

The JSON graph format comprises of four basic elements - Nodes, Ports, Labels, and Edges.

Each element has an 'id' that identifies it uniquely.
The first three elements can hold a position and dimension.
Edges on the contrary can hold bend points specifying where the edge changes direction.
Nodes can contain child nodes and hold ports that specify attachment points of edges.
Multiple edges can be attached to the same port, the port is attached to the node itself.
All elements can hold labels (despite the label itself).
All elements can hold properties which represent additional information to the layout algorithm.

Examples

Below are some example graphs in the JSON graph format. You can hop to the Live section of our web service and try them! If you use SVG as output format the graph will be rendered as an SVG image directly within your browser.

Minimal

The following example shows a very simple graph consisting of two nodes connected by one edge. Each node owns a width and height as well as a label.

{
    id: "root",  // root node
    children: [{
        id: "n1",  // node n1
        labels: [ { text: "n1" } ],
        width: 100, 
        height: 100,
    },{
        id: "n2",  // node n2
        labels: [ { text: "n2" } ],
        width: 100,
        height: 50
    }],
    edges: [{
        id: "e1",  // edge n1 -> n2
        source: "n1",
        target: "n2"
    }]
}

Hierarchy and Ports

This example illustrates nesting of nodes to establish hierarchy. The node n2 serves as parent node for nodes n3 and n4. The latter two nodes are connected via edge e2. Furthermore, edge e1 is connected to port n2_p1 of node n2.

{
    id: "root",  
    children: [{
        id: "n1",  
        labels: [ { text: "n1" } ],
        width: 100, 
        height: 100
    },{
        id: "n2", 
        labels: [ { text: "n2" } ],
        width: 100,
        height: 50,
        ports: [{
            id: "n2_p1",
            width: 10,
            height: 10
        }],
        children: [{  
            id: "n3",  
            labels: [ { text: "n3" } ],
            width: 20,
            height: 20
        },{
            id: "n4", 
            labels: [ { text: "n4" } ],
            width: 20,
            height: 20}
        ],
        edges: [{
            id: "e2",  
            source: "n3",
            target: "n4"
        }]
    }],
    edges: [{
        id: "e1",  
        labels: [ { text: "e1" } ],
        source: "n1",
        target: "n2",
        targetPort: "n2_p1"
    }]
}

Element Properties

All graph elements can hold further properties that specify certain behavior. In the example below, the both nodes have FIXED_SIDE portConstraints, indicating that the ports may also be moved on their respective side. The side of each port is specified using the portSide property.

Note that properties might be coupled with a certain layout algorithm and hence are not always available. The two properties used in this example are only available for our Klay Layered algorithm.

{
  id: "root",  // root node
  children: [{
    id: "n1",  // node n1
    labels: [ { text: "n1" } ],
    // node n1 has fixed port constraints
    properties: {de.cau.cs.kieler.portConstraints: "FIXED_SIDE"},
    width: 100, 
    height: 100,
    ports: [{
      id: "p1",
      width: 10,
      height: 10,
      // port p1 should be located on the north side
      properties: {de.cau.cs.kieler.portSide: "NORTH"}
    }]
  },{
    id: "n2",  // node n2
    labels: [ { text: "n2" } ],
    properties: {de.cau.cs.kieler.portConstraints: "FIXED_SIDE"},
    width: 100,
    height: 50,
    ports: [{
      id: "p2",
      width: 10,
      height: 10,
      properties: {de.cau.cs.kieler.portSide: "SOUTH"}
    }]
  }],
  // children end
  edges: [{
    id: "e1",  // edge n1 -> n2
    source: "n1",
    target: "n2",
    sourcePort: "p1", // p1 -> p2
    targetPort: "p2"
  }]
}