pgraphs tools

pgraphs is a command-line application and JavaScript library that parses and serializes labeled property graphs, converting between a wide range of graph exchange formats and databases. It is the reference implementation of the Property Graph Exchange Format (PG), a specification originally proposed by Hirokazu Chiba, Ryota Yamanaka, and Shota Matsumoto (2019, 2022) and subsequently developed with Jakob Voss, who maintains the pg-format project on GitHub. The tool is distributed as an NPM package and Docker image under an MIT license and requires Node.js 18 or newer; a companion Python package (pgformat) and a browser-based validator/visualizer (pg-formatter) cover the same model in other environments.

The underlying data model is the labeled property graph: nodes and edges each carry zero or more labels and an arbitrary set of key-value properties, with values following JSON scalar conventions (strings, numbers, booleans) and supporting multiple values per key. The native PG serialization is a compact, line-based text format in which each line describes one entity. A node is written as an identifier followed by optional :Label tokens and key: value properties; an edge is written as a source identifier, a direction operator (-> for directed, -- for undirected), a target identifier, then optional labels and properties. Identifiers, keys, and values may be plain (no spaces or special characters) or quoted, and # introduces comments. Alongside this text form the specification defines two JSON serializations, PG-JSON and the newline-delimited PG-JSONL, which pgraphs uses as its default output.

Beyond the native PG family, pgraphs reads and writes formats such as format:graphml, format:gexf-1.3, format:dot, format:mermaid, format:ocif-0.6 (JSON Canvas), format:tgf, format:ncol, format:pg-json, Graphology JSON, and YARS-PG, and it can emit Cypher CREATE statements or CYPHERL and connect directly to a tool:neo4j database over the Bolt protocol (with untested compatibility for Memgraph and Kuzu). This positions PG as a neutral interchange hub between property-graph databases and visualization or interchange tooling, complementing broader converters like tool:networkx and tool:graphinout.

The main strength is a clean, human-writable model with lossless round-tripping across property-graph formats and a documented formal specification. Limitations follow from that scope: it targets labeled property graphs rather than RDF or the many domain-specific scientific formats, conversions to visual or simplified targets can be lossy, database support beyond Neo4J is unverified, and the project remains small and specification-driven rather than a large production ecosystem.