Repository files navigation

A proposal for representing graph structures in JSON.

Jan 2020 - Updated to Version 2 byTravis Giggy

• Major change - nodes changed from a Array/List to a Map/Dictionary
• Minor changes - updated JSONSchema reference, added the top-level id attribute back
• Cleaned up the JSONSchema definitions taking advantage of updates to JSONSchema

Jan 2021 - Updated with hypergraph support bymohawk2

• Added hyperedges to specification

• Document graph structure
• Use meaningful property names that reflect the semantic type of the value.
• Property names should not be excessively long.
• Property names should be plural when value is an array.
• Properties that allow anull value can be omitted.
• Define aJSON graph schemafor content validation purposes.

A nodes object/Map represents nodes in a graph. Each key in the nodes object is the unique identifier for the node. Thenode object is the value the Map key.

• label property provides a text display for an object. Its value is defined as aJSON string.
• metadata property allows for custom data on an object. Its values is defined as a JSON object.

Edges are an array of objects, each of which represents an edge in the graph.

• source property references the key value of the source [node object](#node object). Its value isdefined as aJSON string.
• relation property provides the interaction between source and target nodes. Its value is definedas aJSON string.
• target property references the key value of the target node object. Its value is defined as aJSON string.
• directed property provides the edge mode (e.g. directed or undirected). Its value isJSON truefor directed andJSON false for undirected. The edge direction is determined bygraph.directedproperty if not present.
• metadata property allows for custom data on an object. Its values is defined as a JSON object.

Hyperedges are either undirected - i.e. a set of nodes - or directed with a set of source nodes, and a set of target nodes

• nodes property is an array of key values of nodes from the nodes array
• source property is an array of the key values of the source nodes.
• relation property provides the interaction between source and target nodes. Its value is definedas aJSON string.
• target property is an array of the key values of the target nodes.
• metadata property allows for custom data on an object. Its values is defined as a JSON object.

A graph object represents a single conceptual graph.

• id (optional) property provides an identifier for this graph object
• type property provides a classification for an object. Its value is defined as aJSON string.
• label property provides a text display for an object. Its value is defined as aJSON string.
• directed property provides the graph mode (e.g. directed or undirected). Its value isJSONtrue for directed andJSON false for undirected. This property default toJSON trueindicating a directed graph.
• nodes property provides the nodes in the graph. Its value is an Map/Dictionary of node objects - the Map key being the node identifier.
• edges property provides the edges in the graph. Its value is an array of edge objects.
• hyperedges property provides the hyperedges in the graph. Its value is an array of hyperedge objects.
• metadata property allows for custom data on an object. Its values is defined as a JSON object.

Current restriction on havingone of edges, undirected hyperedges or directed hyperedges. If this is not a useful restriction,please post a use case in the Issues.

A graphs object groups zero or more graph objects into one JSON document.

• The graphs object is defined as aJSON array.

Additional examples

{"graph": {}}

{"graphs": []}

{"graph": {"nodes": {"A": {},"B": {}    }  }}

{"graph": {"nodes": {"A": {},"B": {}    },"edges": [      {"source":"A","target":"B"      }    ]  }}

{"graph": {"nodes": {"A": {},"B": {}    },"hyperedges": [      {"nodes": ["A","B"],"relation":"associated","metadata": {}      }    ]  }}

{"graph": {"directed":false,"type":"graph type","label":"graph label","metadata": {"user-defined":"values"    },"nodes": {"0": {"label":"node label(0)","metadata": {"type":"node type","user-defined":"values"        }      },"1": {"label":"node label(1)","metadata": {"type":"node type","user-defined":"values"        }      }    },"edges": [      {"source":"0","relation":"edge relationship","target":"1","directed":false,"label":"edge label","metadata": {"user-defined":"values"        }      }    ]  }}

{"graphs": [    {"directed":true,"type":"graph type","label":"graph label","metadata": {"user-defined":"values"      },"nodes": {"0": {"label":"node label(0)","metadata": {"type":"node type","user-defined":"values"          }        },"1": {"label":"node label(1)","metadata": {"type":"node type","user-defined":"values"          }        }      },"edges": [        {"source":"0","relation":"edge relationship","target":"1","directed":true,"label":"edge label","metadata": {"user-defined":"values"          }        }      ]    },    {"directed":true,"type":"graph type","label":"graph label","metadata": {"user-defined":"values"      },"nodes": {"0": {"label":"node label(0)","metadata": {"user-defined":"values"          }        },"1": {"label":"node label(1)","metadata": {"user-defined":"values"          }        }      },"edges": [        {"source":"1","relation":"edge relationship","target":"0","directed":true,"label":"edge label","metadata": {"user-defined":"values"          }        }      ]    }  ]}

TheJSON graph schema(version 2)is provided for the json graph format.

The media type to describe JSON Graph Format isapplication/vnd.jgf+json. The approach to use amedia type suffix like+json is described byRFC 6839.

In addition to the media type aprofile media type parameter MUST be set to a URL thatdereferences to the JSON schema for JSON Graph Format. The expected usage of theprofile mediatype parameter is defined byRFC 6906. For example tocommunicate plain JSON Graph Format content theContent-Type header could be set as:

Content-Type: application/vnd.jgf+json

A child schema of JSON Graph Format can communicate its JSON schema using additionalprofile mediatype parameters. Eachprofile media type parameter MUST dereference a JSON schema. For example theBEL JSON Graph Format could be communicated as:

Content-Type: application/vnd.jgf+json;profile=http://jsongraphformat.info/schema.json;profile=http://jsongraphformat.info/child-schemas/bel-json-graph.schema.json

You can import the schema into your JS projects by installing it via NPM and requiring it.

npm install --save json-graph-specification

varJSONGraph=require('json-graph-specification')

1. jay-gee-eff - An npm package for manipulating JGFfiles in nodejs.
2. jay-gee-eff-for-web - An npm package forusing JGF graphs with OOP in the web, i.e. web browsers, without capabilities of file handling,but a fully fledged JGF feature set.

SeeTESTING.

Graph data in JSON is usually modelled in application-specific ad-hoc formats. In addition there areseveral text-based graph formats:

• Graph Modelling Language (GML)
• DOT (graphviz syntax)
• Pajekt NET format
• Netdraw VNA format
• UCINET DL Format
• Trivial Graph Format (TGF)
• GUESS format (GDF)
• Tulip TLP format

and XML-based graph formats:

• Directed Graph Markup Language (DGML)
• Graph Exchange XML Format (GEXF)
• Graph eXchange Language (GXL)
• GraphML
• DotML (XML representation of DOT)
• XGMML (XML representation of GML)

Several semi-standardized JSON-based graph formats are found in applications, for instanceCytoscape JSON. Simple graphs can also beexpressedin CSV format.

• JSON schema