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
.ghis binary — Git cannot diff it and language models cannot read it..ghxis 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 omitcomponentGuid,instanceGuid, andpivot. SmartHopper resolves the component by name, assigns fresh instance GUIDs, and computes a clean layout automatically. - Include
instanceGuidonly to reference or update an existing canvas object: When a component in a GhJSON document carries aninstanceGuidmatching an object already on your canvas, Place GhJSON (GhPut) updates that object in place and keeps its external wires intact. - Supplied
pivotcoordinates are preserved: When loading a saved.ghjsonfile that already haspivotcoordinates, 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):
| Task | Component |
|---|---|
| Export canvas (or selection/filters) to GhJSON | Get GhJSON (GhGet), or Canvas to AI (GhJSON2AI in B. Input) |
| Place or update GhJSON on the canvas | Place GhJSON (GhPut) |
Validate a GhJSON document (Minimal / Standard / Strict) | Validate GhJSON (GhValidate) |
Compare two GhJSON documents into a .ghpatch diff | Diff 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 canvas | Apply GhPatch (GhPatchApply), Apply GhPatch to Canvas (GhPatchApplyCanvas) |
Open or save .ghjson and .ghpatch files on disk | Open GhJSON, Save GhJSON, Open GhPatch, Save GhPatch |