Falcor JSON Graph

Falcor JSON Graph is a convention for representing graph-structured data as a single JSON document, developed by Netflix as part of the Falcor data-fetching framework (open-sourced in 2015). Its motivation is a well-known impedance mismatch: plain JSON models trees, whereas most application domains are graphs, and naively serializing a graph into a tree duplicates entities. JSON Graph instead gives every entity one canonical location, addressed by an "identity path," and links to it from elsewhere rather than copying it. This makes the format a lightweight, JSON-native alternative to heavier graph serializations such as GraphSON, PG-JSON, or RDF forms like JSON-LD, aimed at client-server data synchronization rather than whole-graph interchange.

The data model extends ordinary JSON with three special value types, collectively called sentinels: a Reference ({"$type":"ref","value":[...]}) is a symbolic link that stores a path array pointing to another location in the same document, enabling the graph structure; an Atom ({"$type":"atom","value":...}) boxes a primitive or array so metadata (such as expiry) can travel with it and so it is treated atomically on get/set; and an Error ({"$type":"error","value":...}) marks a failed value in place. Data is addressed by paths, which are arrays of keys traversed from the root; when traversal hits a Reference with keys remaining, the runtime concatenates the reference target with those keys ("path optimization") to follow the link transparently.

Falcor exposes three abstract operations over this model: get and set on primitive values (both idempotent), and call for function invocation and multi-value transactions. Every operation returns a JSON Graph "envelope" containing only the requested subset, so a client cache and a server can merge partial responses into a shared virtual model without a schema. This partial, mergeable design and its collapsing of round-trips positioned Falcor as a contemporary of GraphQL.

Honest limitations: JSON Graph is edge-poor by graph standards. References model directed pointers between map-like entities but carry no first-class notion of typed, attributed edges, so property-graph or RDF triple semantics do not map cleanly, and it is not designed as a general graph-exchange format. It is also tied to Falcor's model/router runtime and JSON key-map conventions, and Netflix has not actively developed Falcor for years, so it is best read as a historical, JSON-friendly graph representation rather than a current interchange standard. Tooling is minimal, centered on the falcor-json-graph factory library and falcor-json-graph.