# Interop: worox-graph JSON and Graphenix `Graph`

How **worox-graph** graph JSON relates to the port-based `Graph` type in `@x12i/graphenix-core`.

## Two representations

| Area | worox-graph | Graphenix core `Graph` |
|------|-------------|------------------------|
| Topology | Task nodes, edges, `outputMapping`, finalizers | Nodes, edges, **ports**, `GraphInput` / `GraphOutput` |
| Execution shape | Engine-specific (tasks, DAG scheduling) | **Execution-agnostic** static description |
| I/O contracts | Often embedded in graph JSON and tooling | **Optional** `metadata.graphEntry` / `metadata.graphResponse` on the **document** |
| Planning (catalog) | Optional `metadata.catalogRequests`; per task node `metadata.catalogRequest` / `metadata.catalogBinding` | Same optional keys on **`GraphDocument.metadata`** and **node `metadata`** (execution unchanged) |

worox-graph focuses on runnable task graphs and visibility into execution paths. Graphenix describes a **static** graph layout (ports, graph-level inputs/outputs) without prescribing how the runtime schedules tasks.

Planning-only catalog fields do not alter execution. Graphenix exposes matching optional JSON Schema `$defs` for tooling that wants a single validator story.

## Where worox-graph JSON lives

- **Canonical for core:** optional **`GraphDocument.metadata.graphEntry`** and **`GraphDocument.metadata.graphResponse`**. These match worox contracts used when values are copied to `variables.__graphModel`.
- **Namespaced extensions:** worox-only payloads may also live under `metadata.extensions` when a profile namespace owns them.

Graphenix core does not change execution model: the `Graph` remains port-based.

## DAG nodes vs ports: is there a converter?

**Not in `@x12i/graphenix-core` today.** A future optional converter could map worox task nodes ↔ port graphs. Until such a tool exists, treat worox graph JSON and Graphenix `Graph` as related **documentation and planning** layers, not automatic transforms.

## See also

- [`../README.md`](../README.md) — graph-level summary contracts (I/O layers 01 / 08).
- `schema/graphenix-format-2.0.0.schema.json` — `$defs/GraphEntryContract`, `$defs/GraphResponseContract`, and optional worox planning `$defs`.