EN Editor Graphs

Operation graphs: documents, nodes and compilation

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

A graph is a versioned design document, not a separate runtime language. Supported nodes compile into ordinary Forge operation fragments, which still pass runtime schema and authorization checks.

Document structure

Root fields are $schema, schema_version, target_document, metadata, nodes and edges. The v0.5.1 graph schema version is 1. Targets must be direct config/*.json paths. Nodes use id/type/title/x/y/properties; edges use id/from_node/from_port/to_node/to_port.

Node/edge IDs must be unique, referenced targets must exist, and cycles or multiple connections to the same input are rejected. See the schema reference for size/node/edge limits. A visual cycle is rejected during validation rather than executed as an infinite backend loop.

Node support

UI concept / type	Compilation behavior
Request / request.input	At most one; method/input-schema context
Authorization / auth.policy	At most one; public access or permission
SQL Query / data.query	SQL statement; defaults to fetch_all
SQL Mutation / data.mutate	SQL statement; defaults to execute
Forge Operation / operation.call	Exactly one operation definition required
Python SDK / python.call	Adds a supplied hook to background_hooks
Response / response.output	At most one; current compiler supports only HTTP 200
Branch, Transform, Event, custom plugin nodes	Design-only; explicit compilation error

python.call does not evaluate arbitrary Python inline or automatically invoke a remote SDK. The current compiler emits a background-hook reference. Node labels do not imply additional runtime behavior.

Apply the compiled configuration

1. Use File → New operation graph… and select the target config path.
2. Create one Operation and at least one Query/Mutation node; connect the required request/auth/response nodes.
3. Set SQL bindings, permission and input schema explicitly in Properties.
4. Inspect the JSON through Compile preview.
5. Use Copy JSON and apply the output to the intended configuration document.
6. Check that unrelated operations were retained and routes were not duplicated.
7. Run forge validate, inspect routes/OpenAPI and test the actual operation.

Saving the graph does not automatically publish its compiled configuration. target_document metadata does not write a separate config file; the current UI provides preview/copy. Review graph and runtime-config versions together because they can diverge.

Compiler field coverage

SQL nodes propagate selected fields such as SQL, mode, params, result_name and max_rows. The visual compiler does not expose every runtime operation field. For rowcount guards, custom paths, cache/invalidation and other advanced options, inspect the generated fragment against the RPC model. Preserve manual additions when applying later compiler output.

Query-only graphs emit transaction=false; graphs with mutations emit a transaction. Idempotency selection applies in the mutation context. Design-only nodes are rejected explicitly, not silently omitted.

Remote graph documents

Remote writes require EDITOR_ALLOW_GRAPHS=true, appropriate project/document scopes and documents.graphs.write. Graph-save validation checks metadata/structural consistency, not runtime permission. Final configuration containing hooks remains subject to the hook trust boundary.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• Editor/editor/src/GraphModel.cpp
• Editor/editor/src/NodeGraphEditor.cpp
• Editor/editor/src/MainWindow.cpp
• main/framework/editor_api.py
• main/schemas/editor-graph.schema.json

---

English home · All English pages · Version maintenance