.nsg.json Schema
The portable graph document format used by NSG Studio, CLI, API, SDK, and embedded viewers.
Overview
.nsg.json describes graph structure, layers, nodes, edges, stack compositions, metadata, and visual hints.
It does not expose NSG's proprietary rendering engine, scanner heuristics, layout algorithms, or internal runtime.
Key principle: .nsg.json tells NSG what the graph is. The NSG runtime decides how to render it.
Minimal Example
example.nsg.json
{
"nsgVersion": "1.0",
"id": "example",
"name": "Example Graph",
"theme": "quantum",
"mode": "nested",
"entry": {
"layerId": "root"
},
"layers": {
"root": {
"id": "root",
"name": "Root",
"layoutMode": "grid",
"archetype": "default",
"nodes": [
{
"id": "node-1",
"label": "Node 1",
"shape": "cube"
}
],
"edges": []
}
}
}Root Properties
| Property | Type | Description |
|---|---|---|
nsgVersion | string | Schema version (e.g., "1.0") |
id | string | Unique identifier for the graph |
name | string | Display name |
theme | string | Visual theme (e.g., "quantum", "dark") |
mode | string | Rendering mode ("nested", "flat") |
entry | object | Entry point configuration |
layers | object | Map of layer ID to layer definition |
Layer Properties
| Property | Type | Description |
|---|---|---|
id | string | Unique layer identifier |
name | string | Display name |
layoutMode | string | "grid", "force", "flow", "tree", "radial" |
archetype | string | Visual archetype for rendering |
nodes | array | Array of node objects |
edges | array | Array of edge objects |
Node Properties
| Property | Type | Description |
|---|---|---|
id | string | Unique node identifier |
label | string | Display label |
shape | string | "cube", "sphere", "folder", "file", etc. |
childLayerId | string? | Makes node a portal to another layer |
metadata | object? | Custom metadata for inspection |