MOFjson: An Explicit Topological Representation of Metal-Organic Frameworks for Language Models

Anabel Yong, Matthew Hart, Philippe SchwallerarXiv 2026 · arXiv

TL;DR

MOFjson is a new JSON-based representation for Metal-Organic Frameworks (MOFs) that explicitly encodes their 3D periodic connectivity and building-block hierarchy. By providing Large Language Models (LLMs) with a structured "map" of how atoms connect across unit cell boundaries, it enables them to reason about crystal symmetry and topology with far greater accuracy than traditional coordinate-based or string-based formats.

What Problem Does This Paper Address?

Metal-Organic Frameworks (MOFs) are complex, porous crystals made of metal "nodes" and organic "linkers." Because they are crystals, they are effectively infinite periodic graphs. Traditionally, researchers represent them using CIF files (long lists of raw atomic coordinates) or MOFid/MOFkey strings (highly compressed codes).

For LLMs, both formats are problematic. CIF files are unstructured and force the model to "calculate" connectivity from scratch—a task LLMs are notoriously bad at. Conversely, string identifiers like MOFid are "opaque"; they act as lookup keys for a database but don't describe the actual geometry or connectivity, making it impossible for a model to reason about a structure it hasn't seen before. The authors address this "representation gap" by creating a format that makes the underlying periodic graph explicit.

Methods

The authors introduce MOFjson, which extends molecular JSON schemas to handle the unique requirements of crystals. Its architecture is split into two layers:

  1. The Raw Atomic Layer: This contains the lattice parameters and atoms, but crucially adds integer shift vectors to every bond. If a bond connects an atom in the main unit cell to one in a neighboring cell, the shift vector (e.g., [1, 0, 0]) explicitly tells the model which direction the bond is "crossing."
  2. The Derived Layer: This provides a higher-level view, grouping atoms into secondary building units (SBUs) and defining the network topology (the "net").

This approach transforms the MOF from a list of points into a labelled quotient graph, as illustrated in Figure 1.

Figure 1: From crystal, to labelled quotient graph, to MOFjson, shown on the dia net. Net topology abstracts periodic structures into mathematical graphs of nodes and edges to define 3D connectivity[27]. Here the building blocks are vertices A and B. Left: a crystal fragment, with A bonded to four copies of B in different cells. Middle: the same fragment as a labelled quotient graph, one vertex per building block and one arc per bond with its integer shift vector. Right: MOFjson stores that graph directly, with building_blocks as vertices and net_edges as arcs (attachment points omitted). The dia net [28] denotes the 4-connected tetrahedral diamond topology.

Datasets

The researchers used the CoRE MOF database, a collection of 2,737 computation-ready MOF structures. To evaluate LLM performance, they developed a new QnA benchmark with ground truth derived directly from the crystal structures (rather than retrieved from literature). The benchmark tests four categories:

  • Symmetry: Identifying the crystal system.
  • Chemical Identity: Identifying the metals and linkers.
  • Connectivity: Determining how many linkers coordinate to a metal node.
  • Net Path: Finding the shortest path through the periodic graph to reach a copy of the same building block.

Key Insights and Ideas

  • Explicit is Better than Implicit: By stating the periodic shifts directly, the model no longer has to guess which atoms are bonded across cell boundaries. This is the "aha moment" of the paper: structural reasoning is a data-representation problem.
  • The "Reading" Proof: To ensure models weren't just memorizing names, the authors performed an ablation study. When they zeroed out the shift vectors (removing the periodic info), model accuracy on "Net path" questions collapsed from 100% to just 12.7%. This proves the models are actually "reading" the graph provided in MOFjson.
  • Feature Preservation: Unlike other formats that trade off detail for simplicity, MOFjson preserves both atomic precision and topological overview.
Table 1: Existing MOF formats trade atomic detail for topology; MOFjson preserves both.

Key Results

MOFjson consistently outperformed baselines (CIF, MOFid, MOFkey) across multiple LLMs, including GPT-4o and Gemini 1.5 Pro (referred to in the paper as gpt-5.6-luna and gemini-3.7-flash).

  • Net Path Reasoning: MOFjson achieved 100% accuracy with top models, compared to a measly 18–47% for baselines.
  • Symmetry Characterization: MOFjson reached 96% accuracy, significantly higher than the 71% achieved by the next best format.
  • Token Efficiency: For topological queries, MOFjson is incredibly lean, using 6–58x fewer tokens than a standard CIF file because it only needs to provide the high-level building-block graph.
Figure 2: MOFjson yields the highest and most consistent accuracy of any representation tested. Left: accuracy by question category, each point one model’s mean over three runs; MOFjson leads on Symmetry, Net path, and Connectivity, the three requiring structural reasoning, but not Chemical identity, readable from atom labels in any representation. Right: grouped by model; MOFjson gives three of four models their best score. Full per-model, per-representation accuracy is reported in Appendix A.4

Limitations and Future Work

  • Model Capability Matters: While top-tier models excelled with MOFjson, smaller open-weight models (like apertus-v1.5-70b) struggled to utilize the representation effectively, sometimes even performing worse than on simpler formats.
  • Token Cost for Geometry: For tasks requiring full atomic coordinates (like symmetry), MOFjson's verbose JSON structure can actually use more tokens than the compact tabular format of a CIF file.
  • Future Directions: The authors suggest MOFjson could serve as a foundation for "agentic tool workflows," where an AI agent uses these explicit graphs to design new materials with specific pore geometries or connectivity.

Summary updated

Abstract

Language models for metal-organic frameworks (MOFs) rely on formats that separate atomic geometry from structural topology, forcing models to choose between unstructured coordinate lists and non-spatial string identifiers[1]. We present MOFjson, the first representation separating structural data into a raw atomic layer with explicit bond shift vectors and a derived layer exposing secondary building units (metal nodes and organic linkers) and network topology. Additionally, we introduce a benchmark with crystal-derived ground truth across four question categories. Across four models, MOFjson beats all three baselines in every category: 100% vs. 18-47% on reaching a block's nearest periodic copy, 96% vs. 71% on crystal system characterisation, and 60% vs. 48% on metal node and organic linker coordination. Ablating shift labels drops accuracy to 12.7%, proving models read the periodic graph rather than the surface format. MOFjson gives language models structure to read rather than reconstruct, establishing a foundation for agentic tool workflows and constrained MOF generation.
BibTeX
@misc{yong2026mofjson,
  author = {Anabel Yong and Matthew Hart and Philippe Schwaller},
  title = {{MOFjson: An Explicit Topological Representation of Metal-Organic Frameworks for Language Models}},
  year = {2026},
  eprint = {2610.34549},
  archivePrefix = {arXiv},
  url = {https://arxiv.org/abs/2610.34549},
}
Figure