Skip to main content

Work with GhJSON

GhJSON (.ghjson) and GhPatch (.ghpatch) are open, human-readable JSON formats for Grasshopper definitions and diffs. SmartHopper uses them for every canvas read, placement, diff, and patch operation, and the format specification lives at ghjson-spec.

Why GhJSON exists​

  • .gh is binary — Git cannot diff it and language models cannot read it.
  • .ghx is verbose XML — even a small definition takes thousands of tokens.
  • GhJSON is compact JSON — components, wires, groups, parameter modifiers, internalized values, and component state (sliders, panels, scripts) in clean, readable text.
{
"schema": "1.0",
"components": [
{
"name": "Number Slider",
"id": 1,
"componentState": {
"extensions": {
"gh.numberslider": { "value": "5<0~10>" }
}
}
},
{
"name": "Addition",
"id": 2
}
],
"connections": [
{
"from": { "id": 1, "paramName": "Number" },
"to": { "id": 2, "paramName": "A" }
}
]
}

Key rules when generating or editing GhJSON​

  • Omit GUIDs and coordinates for new components: When writing or generating new components, provide "name" and "id" and omit componentGuid, instanceGuid, and pivot. SmartHopper resolves the component by name, assigns fresh instance GUIDs, and computes a clean layout automatically.
  • Include instanceGuid only to reference or update an existing canvas object: When a component in a GhJSON document carries an instanceGuid matching an object already on your canvas, Place GhJSON (GhPut) updates that object in place and keeps its external wires intact.
  • Supplied pivot coordinates are preserved: When loading a saved .ghjson file that already has pivot coordinates, SmartHopper places components at their saved positions.

Components for working with GhJSON & GhPatch​

All canvas and file operations live in SmartHopper → D. GhJSON (see Canvas & GhJSON Components):

TaskComponent
Export canvas (or selection/filters) to GhJSONGet GhJSON (GhGet), or Canvas to AI (GhJSON2AI in B. Input)
Place or update GhJSON on the canvasPlace GhJSON (GhPut)
Validate a GhJSON document (Minimal / Standard / Strict)Validate GhJSON (GhValidate)
Compare two GhJSON documents into a .ghpatch diffDiff GhJSON (GhDiff)
Merge two GhJSON documents (Target wins on GUID conflicts)Merge GhJSON (GhMerge)
Apply a .ghpatch diff to a GhJSON document or directly to the canvasApply GhPatch (GhPatchApply), Apply GhPatch to Canvas (GhPatchApplyCanvas)
Open or save .ghjson and .ghpatch files on diskOpen GhJSON, Save GhJSON, Open GhPatch, Save GhPatch