# Interop: worox-graph JSON and graphenix-format `Graph`

This note clarifies how **worox-graph** graph JSON relates to the **port-based** `Graph` type in graphenix-format. It applies to authors using both `@woroces/worox-graph` and `graphenix-format` validation.

## Two representations

| Area | worox-graph | graphenix-format 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`** in this package’s schema (execution unchanged) |

worox-graph focuses on runnable task graphs and visibility into execution paths. graphenix-format 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; canonical shapes live in `@woroces/worox-graph` (`refs.ts`). graphenix-format exposes matching optional JSON Schema `$defs` (`WoroxCatalogRequest`, `WoroxCatalogBinding`, `WoroxCatalogRequests`) for tooling that wants a single validator story.

## Where worox-graph JSON lives

- **Canonical for this package:** optional **`GraphDocument.metadata.graphEntry`** and **`GraphDocument.metadata.graphResponse`** (first-class optional fields). These match the worox contracts used when values are copied to `variables.__graphModel` and keep a single place for validation and docs.
- **`extensions`:** you may still place namespaced worox-only payloads under `extensions` (e.g. legacy or engine-specific blobs). That does **not** replace `metadata.graphEntry` / `metadata.graphResponse` when you want graphenix-format schema and types to validate the same shapes as worox-graph.

FR-GXF-1 does **not** change graphenix-format’s execution model: the core `Graph` remains port-based.

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

**Not in graphenix-format today.** A future **optional** converter could map worox task nodes ↔ port graphs; nothing in the entry/response metadata requires or implies that mapping. Until such a tool exists, treat worox graph JSON and graphenix `Graph` as related **documentation and planning** layers, not automatic transforms of each other.

## See also

- README: **Worox-graph alignment** (I/O layers 01 / 08).
- `schema/graphenix-format-1.0.0.schema.json`: `$defs/GraphEntryContract`, `$defs/GraphResponseContract`, and optional worox planning `$defs` (`WoroxCatalogRequest`, `WoroxCatalogBinding`, `WoroxCatalogRequests`).