NodeFox

JSON Graph

In NodeFox, a workflow is not a diagram that later gets reinterpreted by hidden orchestration code. The graph itself is the runtime contract. What you design is what executes.

This matters because many production failures come from ambiguity, not missing features. One team assumes data arrival triggers execution; another assumes approval gates exist; responders cannot find one canonical source of truth. JSON graph contracts reduce that ambiguity by making behavior explicit and inspectable.

What JSON means here

JSON (JavaScript Object Notation) is a text format for structured data. In NodeFox, JSON is used because it is:

  • language-agnostic and portable
  • diffable in Git and code-review workflows
  • schema-validatable before runtime
  • easy to export/import across workspaces

What a JSON graph contract captures

A practical NodeFox graph artifact captures four classes of behavior together: node identity and variant selection, edge topology (including both data edges and activation edges), slot-level input/output contracts, and any attached schema or tool context that influences runtime decisions. Because these concerns are represented in one place, teams can reason about orchestration behavior as a system instead of piecing it together from scattered scripts, comments, and post-hoc run logs.

In operational terms, this means reviewers can ask concrete questions and get concrete answers from the artifact itself: which branch can trigger a high-impact write, where looping is bounded, what fallback path is expected after retries fail, and what typed output shape downstream nodes rely on. The graph stops being a visual convenience and becomes a governance surface.

Runtime lifecycle of a JSON graph

  1. Parse and validate graph structure.
  2. Hydrate initial run state and inputs.
  3. Evaluate node eligibility using edge, slot, and activation semantics.
  4. Execute eligible nodes and record transitions.
  5. Persist logs/snapshots tied to graph version for replay.

Each stage stays linked to the same JSON contract, so replay and post-incident analysis can reconstruct what actually happened.

Why teams rely on this in production

Teams that treat workflows as JSON graph contracts tend to move faster with less incident churn. They can diff behavior changes before deployment, tie release notes to specific route updates, and retain a reliable history of why control logic changed over time. That is especially important when multiple owners touch the same workflow family, or when legal, trust, support, and engineering need a shared explanation of runtime behavior.

The portability benefit is equally practical. A graph can be exported and shared as JSON or bundle artifacts, then imported into another workspace while preserving the core control model. That keeps collaboration disciplined and reduces copy-paste drift between environments.

Operational checklist

Before promoting a graph version:

  • review edge diffs, especially activation and Writer-adjacent branches
  • validate schema/tool contracts referenced by graph nodes
  • test loop bounds and fallback routes with failure-oriented inputs
  • pin the promoted graph version in rollout records
  • capture replay anchors for incident reconstruction

Common mistakes to avoid

  • treating JSON export as backup only instead of a review artifact
  • mixing multiple behavior changes in one graph revision
  • relying on undocumented slot conventions
  • promoting graph changes without replay and fallback-path verification

Read Architecture for deeper runtime context, Foundation and Future for the platform-level design posture, and Use Case Patterns for implementation examples that apply these graph-contract ideas under real workload conditions.