json_graph

The json_graph library provides predicates for parsing and generating JSON Graph Format (JGF) version 2 graphs:

https://jsongraphformat.info

The library main object, json_graph, converts between JGF JSON and a canonical list of terms:

  • graph(GraphId, Properties)

  • node(GraphId, NodeId, Properties)

  • edge(GraphId, EdgeId, Source, Target, Properties)

  • hyperedge(GraphId, HyperedgeId, Nodes, Properties)

  • hyperedge(GraphId, HyperedgeId, Sources, Targets, Properties)

Canonical graph, node, source, target, and edge identifiers are always atoms. When the library needs to generate missing graph, edge, or hyperedge identifiers while parsing JGF input, it uses atoms in the gN, eN, and heN formats. Node identifiers are not generated because JGF nodes are stored as object members keyed by their identifiers.

Undirected hyperedges use hyperedge/4 and require their graph to have a directed(false) property. Directed hyperedges use hyperedge/5 and preserve the JGF source and target node sets as separate lists. A graph uses either ordinary edges or hyperedges, matching the JGF schema shape.

It also supports object-backed sources and sinks using the json_graph_data_protocol protocol. Objects used as sinks should implement that protocol and locally declare the graph/2, node/3, edge/5, hyperedge/4, and hyperedge/5 predicates as dynamic.

API documentation

Open the ../../apis/library_index.html#json_graph link in a web browser.

Loading

To load all entities in this library, load the loader.lgt file:

| ?- logtalk_load(json_graph(loader)).

Testing

To test this library predicates, load the tester.lgt file:

| ?- logtalk_load(json_graph(tester)).

To run the performance benchmark suite, load the tester_performance.lgt file:

| ?- logtalk_load(json_graph(tester_performance)).

Usage

A JSON graph can be parsed into a list of canonical terms:

| ?- json_graph::parse(atom('{"graph":{"id":"g","label":"Example","nodes":{"n1":{"label":"one"}},"edges":[{"source":"n1","target":"n1"}]}}'), Terms).

An object-backed graph can be exported by implementing the json_graph_data_protocol protocol and defining graph/2, node/3, edge/5, hyperedge/4, and hyperedge/5 predicates.

Roundtrip and fixture coverage

The test suite includes roundtrip checks for generated single-graph and multi-graph term representations, file sink roundtrips, and public JGF example files saved under the test_files/ directory.

The bundled public fixtures are sourced from the upstream JGF specification examples repository:

  • test_files/car_graphs.json

  • test_files/empty_test.json

  • test_files/hyper-directed.json

  • test_files/hyper-undirected.json

  • test_files/les_miserables.json

  • test_files/test.network.json

  • test_files/usual_suspects.json