GhJSON - A JSON Standard for Grasshopper

Grasshopper Developer
,
1

I’m excited to announce GhJSON, a new JSON-based standard for representing Grasshopper definitions. What started as an internal need for SmartHopper has evolved into a reusable, open-source library that hopefully will benefit others in the Grasshopper ecosystem.

The Problem

Working with LLMs and AI tools requires translating designs into text. Binary .gh files aren’t directly processable by language models, and .ghx files contain too much metadata for efficient AI understanding. I needed a format that captures the essential structure and logic of Grasshopper definitions while remaining lightweight, human-readable, and AI-friendly.

The Solution

GhJSON is a standardized JSON format for Grasshopper definitions, inspired by existing community efforts like GHPT and WolfParametric’s wolf-community-scripts. I have documented the specification, made some tweaks, optimized it for AI processing, and built comprehensive tooling around it.

What You Can Do With GhJSON

  • Serialize Grasshopper definitions to JSON for AI analysis, version control, and sharing
  • Deserialize JSON back to the canvas with full fidelity (not all components are compatible yet)
  • Validate definitions against the schema
  • Merge multiple definitions programmatically
  • Extend with custom handlers and serializers

Getting Started

GhJSON.NET is available as two NuGet packages:

  • GhJSON.Core: Platform-independent document model and operations (read, write, validate, fix, merge)
  • GhJSON.Grasshopper: Grasshopper integration (serialize from canvas, place on canvas, data type serializers)

Explore the full specification and documentation at:

Why This Matters

GhJSON is designed to be:

  • Human-readable code: While it is code, it is not (so) cryptic.
  • AI-friendly: Optimized for language model processing and understanding.
  • Extensible: Easy to add support for custom components and data types.
  • Reusable: A standalone library that any .NET project can leverage.
  • Community-driven: Open source and welcoming contributions.

Started in SmartHopper

GhJSON emerged as a natural evolution while building SmartHopper, the first open-source AI-powered Grasshopper plugin. Rather than enclosing this functionality within complex logic with mixed concerns, I separated it into a standalone library so that the entire community could benefit. SmartHopper now uses GhJSON as a core library, and it would be great to see that other plugins can benefit from it.

Building synergy begins with an open standard.

Happy designing! :artist_palette:

2

Amazing, this seems like a huge body of work with pretty amazing possibilities. I haven’t tried it out yet, but certainly will.

Thanks so much for sharing.

3

Nice work :slight_smile:

4

Very cool! This is super interesting for us working on Raven as well. We’ll definitely take a look at this!

5

Thank you all! If you try it, please share your thoughts and suggestions for improvements. I did some testing, but I am sure more issues will arise as GhJSON is implemented in other use cases.

Also, keep in mind that some components and data types need extensions to the schema, which are already planned in the standard but haven’t been made yet; it’s only a matter of time :slight_smile: