---
position: 3
title: GraphJSON
---

# GraphJSON: Overview

Alchemy.js takes a simple data format called GraphJSON.  GraphJSON is similiar to GeoJSON in many ways, and is a standardized way to represent connected data in applications.  In the future, Alchemy.js will use GraphJSON for the transfer and storage of attributes that will allow for more robust visual representations of the underlying graph data.  For now, GraphJSON serves as a lightweight and flexible representation of graph data, easily consumed locally or over the web.

## The Format
GraphJSON is a JSON object that contains two objects, **nodes** and **edges**:

~~~json
{
    "nodes": [...],
    "edges": [...]

}
~~~

The **nodes** and **edges** objects are arrays of the individual nodes and edges that will be represented in the Graph visualization.   

## Nodes and Edges
The only requirement for node objects is that they receive an **id** key that is unique (in the scope of the GraphJSON). The only requirement for edge objects is that they receive a **source** and **target** key that correspond to the source and target nodes. If there are multiple edges with identical source and targets, those edges MUST have a unique id.

## Features
Alchemy.js has a number of features that rely on the underlying data.  Most of the below features are supported by the example GraphJSON that follows.

### Captions  
Captions are the text that displays in the graph visualization.  By default, the captions will display on search active, on node hover, and when filtering.  In the configuration, [nodeCaption](#nodecaption) defaults to "caption" which means that Alchemy.js will look for a "caption" key on each node.

### Clustering 
Clustering can be enabled in the configuration be setting [cluster](#cluster) to `true`.  Alchemy.js will then look for a "cluster" key on the nodes, which will enable a clustering algorithm that colors and positions to nodes.  This is especially useful for social network analysis and any form of exploratory data analysis.

### Defining Root Nodes
Any node containing a root key that is truthy will be considered a root node.  For example:

~~~json
{
  "nodes": [
    {
      "id": 1,
      "root": true
    },
    ...
  ],
  ...
}
~~~

See the "Charlize" node below or any of the GraphJSON in our [examples gallery](/#/examples) for an example in context.

### nodeTypes and edgeTypes
Node and edge types are used for a number of tasks, including styling and filtering.  By default, [nodeTypes](#nodetypes) and [edgeTypes](#edgetypes) are not defined. In the GraphJSON example [below](#sample-graphjson), **nodeTypes** might look as follows 

~~~
  {"nodeTypes": {"type": ["award", "actor", "movie"...]}
~~~

while **edgeTypes** might look like this 

~~~"edgeTypes": {"caption": ["ACTED_IN", "DIRECTED", "NOMINATED", etc.]}~~~.

To include nodeTypes and edgeTypes to your application, add them into your script tag where you defined your dataset. 

*Note*: Attributes in the GraphJSON can serve multiple purposes.  **caption** on the edges is used for categorizing nodes as well as the text that will display on hover interactions.

## Sample GraphJSON
Below is sample GraphJSON which contains all of the movies, awards, and other people that Charlize Theron is connected to.

~~~json
{
  "nodes": [
    {
      "caption": "Screen Actors Guild Award for Outstanding Performance by a Female Actor in a Miniseries or Television Movie",
      "type": "award",
      "id": 595472
    },
    {
      "caption": "Children of the Corn III: Urban Harvest",
      "type": "movie",
      "id": 626470
    },
    {
      "caption": "Sleepwalking",
      "type": "movie",
      "id": 795744
    },
    {
      "caption": "That Thing You Do!",
      "type": "movie",
      "id": 692946
    },
    {
      "caption": "Trapped",
      "type": "movie",
      "id": 689794
    },
    {
      "caption": "Head in the Clouds",
      "type": "movie",
      "id": 709577
    },
    {
      "caption": "Waking Up in Reno",
      "type": "movie",
      "id": 635905
    },
    {
      "caption": "Battle in Seattle",
      "type": "movie",
      "id": 734583
    },
    {
      "caption": "Mighty Joe Young",
      "type": "movie",
      "id": 662595
    },
    {
      "caption": "Academy Award for Actress in a Leading Role",
      "type": "award",
      "id": 593781
    },
    {
      "caption": "The Devil's Advocate",
      "type": "movie",
      "id": 740763
    },
    {
      "caption": "Screen Actors Guild Award for Outstanding Performance by a Cast in a Motion Picture",
      "type": "award",
      "id": 595440
    },
    {
      "caption": "Silver Bear for Best Actress",
      "type": "award",
      "id": 601507
    },
    {
      "caption": "The Curse of the Jade Scorpion",
      "type": "movie",
      "id": 649461
    },
    {
      "caption": "MTV Movie Award for Best Female Performance",
      "type": "award",
      "id": 595074
    },
    {
      "caption": "15 Minutes",
      "type": "movie",
      "id": 634248
    },
    {
      "caption": "The Burning Plain",
      "type": "movie",
      "id": 670704
    },
    {
      "caption": "The Life and Death of Peter Sellers",
      "type": "movie",
      "id": 794982
    },
    {
      "caption": "Prometheus",
      "type": "movie",
      "id": 608746
    },
    {
      "caption": "Teen Choice Award for Choice Summer Movie Star: Female",
      "type": "award",
      "id": 599909
    },
    {
      "caption": "Chicago Film Critics Association Award for Best Actress",
      "type": "award",
      "id": 623686
    },
    {
      "caption": "Golden Globe Award for Best Supporting Actress - Series, Miniseries or Television Film",
      "type": "award",
      "id": 598027
    },
    {
      "caption": "Golden Globe Award for Best Actress - Musical or Comedy Film",
      "type": "award",
      "id": 595206
    },
    {
      "caption": "Mad Max: Fury Road",
      "type": "movie",
      "id": 804341
    },
    {
      "caption": "In the Valley of Elah",
      "type": "movie",
      "id": 621675
    },
    {
      "caption": "Screen Actors Guild Award for Outstanding Performance by a Female Actor in a Leading Role",
      "type": "award",
      "id": 593954
    },
    {
      "caption": "Golden Raspberry Award for Worst Actress",
      "type": "award",
      "id": 594134
    },
    {
      "caption": "East of Havana",
      "type": "movie",
      "id": 609415
    },
    {
      "caption": "The Road",
      "type": "movie",
      "id": 627715
    },
    {
      "caption": "Golden Globe Award for Best Actress - Drama Film",
      "type": "award",
      "id": 593776
    },
    {
      "caption": "Charles Jacobus Theron",
      "type": "person",
      "id": 314008
    },
    {
      "caption": "Jackson Theron",
      "type": "person",
      "id": 314009
    },
    {
      "caption": "Primetime Emmy Award for Outstanding Supporting Actress in a Miniseries or a Movie",
      "type": "award",
      "id": 595684
    },
    {
      "caption": "The Cider House Rules",
      "type": "movie",
      "id": 801237
    },
    {
      "caption": "The Astronaut's Wife",
      "type": "movie",
      "id": 657006
    },
    {
      "caption": "Broadcast Film Critics Association Award for Best Actress",
      "type": "award",
      "id": 601849
    },
    {
      "caption": "Hancock",
      "type": "movie",
      "id": 652245
    },
    {
      "caption": "Charlize Theron",
      "root": true,
      "id": 314003
    },
    {
      "caption": "Stuart Townsend",
      "type": "person",
      "id": 314004
    },
    {
      "caption": "Stephan Jenkins",
      "type": "person",
      "id": 314005
    },
    {
      "caption": "Benoni, Gauteng",
      "type": "person",
      "id": 314006
    },
    {
      "caption": "Gerda Jacoba Aletta Maritz",
      "type": "person",
      "id": 314007
    },
    {
      "caption": "Æon Flux",
      "type": "movie",
      "id": 663286
    },
    {
      "caption": "Snow White and the Huntsman",
      "type": "movie",
      "id": 599907
    },
    {
      "caption": "Young Adult",
      "type": "movie",
      "id": 661733
    },
    {
      "caption": "Reindeer Games",
      "type": "movie",
      "id": 761000
    },
    {
      "caption": "Monster",
      "type": "movie",
      "id": 729778
    },
    {
      "caption": "The Legend of Bagger Vance",
      "type": "movie",
      "id": 804616
    },
    {
      "caption": "Teen Choice Award for Choice Hissy Fit: Film",
      "type": "award",
      "id": 599908
    },
    {
      "caption": "The Yards",
      "type": "movie",
      "id": 781638
    },
    {
      "caption": "MTV Movie Award for Best Kiss",
      "type": "award",
      "id": 595095
    },
    {
      "caption": "Celebrity",
      "type": "movie",
      "id": 611629
    },
    {
      "caption": "Astro Boy",
      "type": "movie",
      "id": 818608
    },
    {
      "caption": "North Country",
      "type": "movie",
      "id": 784437
    },
    {
      "caption": "2 Days in the Valley",
      "type": "movie",
      "id": 615556
    },
    {
      "caption": "Satellite Award for Best Actress – Motion Picture",
      "type": "award",
      "id": 595704
    },
    {
      "caption": "Trial and Error",
      "type": "movie",
      "id": 799574
    },
    {
      "caption": "National Society of Film Critics Award for Best Actress",
      "type": "award",
      "id": 595702
    },
    {
      "caption": "Independent Spirit Award for Best Female Lead",
      "type": "award",
      "id": 595703
    },
    {
      "caption": "Two Eyes Staring",
      "type": "movie",
      "id": 788889
    },
    {
      "caption": "Sweet November",
      "type": "movie",
      "id": 811358
    },
    {
      "caption": "Teen Choice Movie Award: Villain",
      "type": "award",
      "id": 595082
    },
    {
      "caption": "Satellite Award for Best Supporting Actress – Drama",
      "type": "award",
      "id": 602151
    },
    {
      "caption": "San Francisco Film Critics Circle Award for Best Actress",
      "type": "award",
      "id": 669827
    },
    {
      "caption": "Independent Spirit Award for Best First Feature",
      "type": "award",
      "id": 599387
    },
    {
      "caption": "The Italian Job",
      "type": "movie",
      "id": 817380
    },
    {
      "caption": "Hollywood Confidential",
      "type": "movie",
      "id": 711550
    },
    {
      "caption": "Men of Honor",
      "type": "movie",
      "id": 682763
    },
    {
      "caption": "BAFTA Award for Best Actress in a Leading Role",
      "type": "award",
      "id": 594478
    }
  ],
  "edges": [
    {
      "source": 314003,
      "target": 621675,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 818608,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 601849,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 649461,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 669827,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 608746,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 593954,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 595702,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 601849,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 595095,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 729778,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 595703,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 811358,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 595472,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 661733,
      "caption": "PRODUCED"
    },
    {
      "source": 314003,
      "target": 784437,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 634248,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 662595,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 804616,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 595703,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 626470,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 599387,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 599908,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 682763,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 595702,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 788889,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 657006,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 795744,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 593781,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 594478,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 594134,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 595074,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 692946,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 740763,
      "caption": "ACTED_IN"
    },
    {
      "source": 314005,
      "target": 314003,
      "caption": "PARTNER_OF"
    },
    {
      "source": 314003,
      "target": 711550,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 595440,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 801237,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 599907,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 761000,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 781638,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 670704,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 609415,
      "caption": "PRODUCED"
    },
    {
      "source": 314003,
      "target": 314009,
      "caption": "PARENT_OF"
    },
    {
      "source": 314003,
      "target": 652245,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 661733,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 602151,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 635905,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 799574,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 593781,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 817380,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 611629,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 729778,
      "caption": "PRODUCED"
    },
    {
      "source": 314003,
      "target": 709577,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 804341,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 627715,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 794982,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 623686,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 595082,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 689794,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 788889,
      "caption": "PRODUCED"
    },
    {
      "source": 314007,
      "target": 314003,
      "caption": "PARENT_OF"
    },
    {
      "source": 314003,
      "target": 593776,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 734583,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 598027,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 601507,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 599909,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 314004,
      "caption": "PARTNER_OF"
    },
    {
      "source": 314003,
      "target": 663286,
      "caption": "ACTED_IN"
    },
    {
      "source": 314003,
      "target": 314006,
      "caption": "BORN_AT"
    },
    {
      "source": 314003,
      "target": 615556,
      "caption": "ACTED_IN"
    },
    {
      "source": 314004,
      "target": 314003,
      "caption": "PARTNER_OF"
    },
    {
      "source": 314008,
      "target": 314003,
      "caption": "PARENT_OF"
    },
    {
      "source": 314003,
      "target": 314005,
      "caption": "PARTNER_OF"
    },
    {
      "source": 314003,
      "target": 795744,
      "caption": "PRODUCED"
    },
    {
      "source": 314003,
      "target": 595704,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 670704,
      "caption": "EXEC_PRODUCED"
    },
    {
      "source": 314003,
      "target": 593954,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 595206,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 593776,
      "caption": "RECEIVED"
    },
    {
      "source": 314003,
      "target": 595704,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 595684,
      "caption": "NOMINATED"
    },
    {
      "source": 314003,
      "target": 599387,
      "caption": "NOMINATED"
    }
  ]
}
~~~

_____