semantic-json

Files (4)

• SKILL.md
• advanced-workflows.md
• getting-started.md
• EXAMPLES.md · references/

SKILL.md (first lines)

# Semantic-JSON

*Canvas-to-structured-data anticompiler workflows for visual cognitive modeling.*

## Core Concepts

### The Anticompiler Philosophy

Semantic-JSON inverts traditional compilation:
- **Traditional compiler**: Human-legible → machine-legible (reduces ambiguity, increases constraints)
- **Anticompiler**: Machine-dense → human-legible (reduces opacity, increases semantic surface)

**Key insight**: Visual modeling preserves spatial semantics that linear text cannot capture. The anticompiler decompresses visual intent into stable, deterministic structure.

### Spatial Semantic Compilation

Canvas elements encode meaning through visual properties:
- **Position** (x, y coordinates) → Linear reading sequence (top-to-bottom, left-to-right)
- **Containment** (bounding boxes) → Hierarchical structure (depth-first traversal)
- **Color** (node/edge colors) → Semantic taxonomy and visual grouping
- **Directionality** (arrow endpoints) → Information flow topology and execution order

---

## Semantic-JSON Plugin

> The plugin is generally present in ZK's vaults. If absent, the compilation workflows below can be done manually by editing the `.canvas` JSON directly.

**Author:** Zach Battin — [github.com/SyntaxAsSpiral/Semantic-JSON](https://github.com/SyntaxAsSpiral/Semantic-JSON)  
**Version:** 0.3.0 · Desktop only · Requires Obsidian ≥ 1.5.0

### Commands

| Full command ID (for `executeCommandById`) | Name | Effect |
|---------------------------------------------|------|--------|
| `semantic-json:compile-active-canvas` | Compile active canvas | Reorders nodes/edges by spatial semantics and flow topology |
| `semantic-json:export-as-pure-json` | Export as pure JSON | Strips Canvas metadata, embeds labeled edges, outputs clean JSON |
| `semantic-json:import-json-to-canvas` | Import JSON to canvas | Scaffolds a `.canvas` from a pure JSON data structure |

Run via Obsidian command palette or bind to a hotkey.

### Settings (`data.json`)

| Setting | Default | Effect |
|---------|---------|--------|
| `autoCompile` | `true` | Compiles on every canvas save |
| `colorSortNodes` | `true` | Groups nodes by color value during compilation |
| `colorSortEdges` | `true` | Groups edges by color value |
| `flowSortNodes` | `true` | Applies flow topology ordering (depth-first from source nodes) |
| `semanticSortOrphans` | `false` | Semantically sorts nodes not contained by any group |
| `stripEdgesWhenFlowSorted` | `true` | Removes unlabeled edges from output when flow sort is active |

With `autoCompile: true` the canvas is recompiled on every save — manual invocation of `compile-active-canvas` is only needed to force a recompile without saving.

### Agent Workflow: Reading Complex Canvases

Raw Obsidian canvas JSON is scrambled on every save — node order is random, spatial metadata adds noise, and edge relationships are unembedded. For large or complex canvases, always export clean JSON before attempting to read or analyze.

```bash
# Open the canvas and export clean JSON via obsidian CLI
obsidian open path="path/to/canvas.canvas" silent
obsidian eval code="app.commands.executeCommandById('semantic-json:export-as-pure-json')"
```

The export writes a `.json` file alongside the canvas (same name, `.json` extension). Read that file instead of the raw `.canvas`.

**What you get:**
- Nodes in deterministic spatial order (top-to-bottom, left-to-right, depth-first through groups)
- Labeled edges embedded as `from`/`to` arrays on nodes — no need to cross-reference edge list
- Canvas metadata (coordinates, dimensions) stripped — just content and structure
- Flow topology resolved into sequential order when `flowSortNodes` is active

**When to use:** Any canvas with more than ~10 nodes, nested groups, or labeled edge relationships. For small flat canvases the raw JSON is readable; for anything complex the compiled export is significantly lower noise.

---

## Canvas JSON Spec

A `.canvas` file is JSON with two top-level arrays:

```json
{ "nodes": [], "edges": [] }
```

### Node Types

All nodes require: `id` (16-char hex), `type`, `x`, `y`, `width`, `height`.

| Type | Extra required field | Notes |
|------|----------------------|-------|
| `text` | `text` (string, Markdown) | Use `\n` for newlines — never `\\n` |
| `file` | `file` (vault-relative path) | Optional: `subpath` (`#heading` or `#^block`) |
| `link` | `url` | External URL |
| `group` | — | Optional: `label`, `background`, `backgroundStyle` |

Array order = z-index: first node is bottom layer.

### Edge Attributes

| Attribute | Required | Default | Values |
|-----------|----------|---------|--------|
| `id` | Yes | — | unique string |
| `fromNode` | Yes | — | node id |
| `toNode` | Yes | — | node id |
| `fromSide` | No | — | `top` `right` `bottom` `left` |
| `toSide` | No | — | `top` `right` `bottom` `left` |
| `fromEnd` | No | `none` | `none` `arrow` |
| `toEnd` | No | `arrow` | `none` `arrow` |
| `color` | No | — | preset or hex |
| `label` | No | — | string |

### IDs

Generate 16-character lowercase hex strings: `"6f0ad84f44ce9c17"`. IDs must be unique across both nodes and edges.

### Layout

- `x` increases right, `y` increases down; position is top-left corner
- Coordinates can be negative (infinite canvas)

From SyntaxAsSpiral/ConSensus, MIT.

More from SyntaxAsSpiral/ConSensus