GraphSON

GraphSON is a JSON-based serialization format for graph data developed by Apache TinkerPop, the open-source graph computing framework that also defines the Gremlin traversal language. It serves two roles: a file format for persisting and exchanging whole graphs, and the wire format used by Gremlin Server to return arbitrary query results (vertices, edges, properties, paths, traversal metrics, and Gremlin bytecode) to remote clients. Because it is plain JSON, it can be parsed by libraries on virtually any platform, which is a large part of its appeal.

The format has three major versions. Version 1.0 (TinkerPop 3.0.0) leaned on Jackson-style type hints and was largely untyped for broad compatibility. Version 2.0 (3.2.2) reduced Jackson dependence and made typing explicit and less lossy. Version 3.0 (3.3.0, and the current default) refined the type system further, notably adding first-class typed encodings for collections. In 3.0 every value is a "complex object" carrying an @type and @value pair, where the type id is a namespaced name such as g:Int32, g:Double, g:UUID, or g:List (the g namespace covers core TinkerPop types, gx covers extended ones like BigDecimal and the Java 8 temporal classes). GraphSON 3.0 specifically added distinctly typed g:Map, g:List, and g:Set because Gremlin uses these in ways plain JSON objects and arrays cannot express; maps, for example, are encoded as a flat key/value array so that non-string keys survive.

For whole-graph documents GraphSON uses an adjacency-list layout rather than an edge list: each vertex is one JSON object embedding its incident edges, and the file is typically newline-delimited (one vertex per line) so it can be split for distributed loading in systems like Apache Spark, or optionally wrapped in a single array. This vertex-centric structure contrasts with the element-list, schema-driven approach of GraphML and the property-graph JSON conventions of PG-JSON, Cytoscape JSON, and Neo4j JSON.

Its main strengths are ubiquity of JSON tooling, a rich type system that avoids the numeric-precision loss of untyped JSON, and a splittable form suited to distributed processing. Limitations include verbosity (typed values roughly triple in size versus raw JSON), a fragmented MIME situation where all versions share application/json and are hard to distinguish, an adjacency-list model that complicates interchange with edge-list tools, and gaps where some TinkerPop constructs are unsupported. It is read and written by GraphInOut and the wider TinkerPop stack (Gremlin-enabled stores such as Neo4j and JanusGraph); for a more compact binary alternative TinkerPop offers GraphBinary.