JSONWF is a compact execution model for provisioning and operational applications.
Its purpose is not to become a universal workflow language, a visual process designer, or a replacement for every workflow engine. Its purpose is narrower and more practical:
JSONWF provides one persistent workflow state and one slot-based execution semantics for human, Web, batch, JSON, AI-generated, and diagnostic input.
The model is designed for provisioning systems in which work progresses through a sequence of meaningful operational contexts. As a concrete example, we will use IP VPN network service provisioning, then return later to its provisioning semantics and Slot-Contextual CLI:
location
→ device
→ VRF
→ interface
→ IP range
→ IP address
→ assignment
→ commit
Each context is represented as a slot.
The active slot determines:
This makes JSONWF particularly suitable for hybrid provisioning in which humans and AI both propose actions, while a deterministic runtime validates, executes, records, and, when necessary, rolls them back.
JSONWF is:
a persistent provisioning document
+ a remaining execution sequence
+ slot-contextual input semantics
+ a sequential interpreter
+ an orchestrator
+ stable execution history
A JSONWF document contains the state required to continue one provisioning flow.
{
"orderid": "CUST_A-20260802-1",
"process": "l3vpn_provisioning",
"status": "active",
"location": {
"name": "DLLSTXB1"
},
"device": {
"ne_name": "R1",
"model": "MX204"
},
"vrf": null,
"interface": null,
"ip_range": null,
"ip_address": null,
"assignment": null,
"fn": [
"create_vrf",
"select_interface",
"create_ip_range",
"allocate_ip_address",
"assign_ip_to_interface",
"commit"
],
"fn_completed": [
{
"select_loc": {
"s": "260802110015",
"c": "260802110017"
}
},
{
"select_device": {
"s": "260802110020",
"c": "260802110022"
}
}
],
"fn_exception": null,
"rolledback": []
}
The document combines four things that are often separated across several frameworks:
current domain state
remaining execution
completed history
current operational condition
This makes the workflow directly inspectable and recoverable.
JSONWF is designed for provisioning and operational workflows with the following characteristics:
Typical examples include:
network provisioning
IP address allocation
inventory operations
service activation
order fulfillment
resource selection
back-office operational workflows
human-in-the-loop automation
The design is strongest where a real operator can naturally say:
I am now selecting the device.
I am now defining the VRF.
I am now assigning the IP address.
Those statements correspond directly to active slots.
JSONWF is not positioned as:
This boundary is deliberate.
JSONWF does not attempt to model every possible control-flow pattern. It focuses on a narrower class of operational workflows and tries to make that class substantially simpler to implement, observe, and validate.
The value of JSONWF is not maximum theoretical expressiveness.
The value is:
one compact execution semantics shared by every interface and every command producer.
A traditional CLI repeats context in every command:
find location DLLSTX*
set location DLLSTXB1
find device R1
set vrf myvrf rd=100 rt=101
JSONWF already knows the current workflow step, so the interface can expose it as the prompt:
loc>
dev>
vrf>
intf>
ip range>
ip address>
Input is interpreted inside the active slot:
loc> DLLSTXB1
dev> R1
vrf> myvrf rd=100 rt=101
The slot provides the semantic context that the command line no longer needs to repeat.
A slot defines:
prompt
fields
accepted verbs
implicit verb
validation
function mapping
completion rule
rollback rule
Web representation
AI command schema
This creates a direct relationship between the workflow and its interfaces.
active JSONWF slot
|
+--> CLI prompt
+--> Web panel
+--> batch statement
+--> JSON command
+--> AI tool schema
+--> diagnostic view
The same slot contract can be used by every client.
SLOT_REGISTRY = {
"vrf": {
"step": "create_vrf",
"prompt": "vrf>",
"target": "vrf",
"implicit_verb": "set",
"fields": {
"name": {"type": "string", "required": True},
"rd": {"type": "string", "required": True},
"rt": {"type": "string", "required": True}
},
"verbs": {
"find": "find_vrf",
"set": "select_or_create_vrf",
"create": "create_vrf",
"clear": "clear_vrf",
"rollback": "__rollback__"
},
"completion": {
"required": ["name", "rd", "rt"]
}
}
}
From this one definition, the system can derive:
vrf> myvrf rd=100 rt=101
VRF name: [ myvrf ]
RD: [ 100 ]
RT: [ 101 ]
vrf>myvrf rd=100 rt=101;
{
"slot": "vrf",
"value": "myvrf",
"attributes": {
"rd": "100",
"rt": "101"
}
}
{
"slot": "vrf",
"verb": "set",
"value": "string",
"attributes": {
"rd": "string",
"rt": "string"
}
}
The interfaces differ in presentation, not in meaning.
Every input source is normalized into the same internal object.
SlotCommand(
slot="vrf",
verb="set",
value="myvrf",
attributes={
"rd": "100",
"rt": "101"
},
source="cli"
)
Possible sources include:
human CLI
Web form
batch file
JSON integration
AI-generated plan
Jupyter support action
Every command then follows the same path:
input adapter
→ SlotCommand
→ active-slot check
→ slot-context validation
→ mapped function
→ patch or controlled error
→ JSONWF update
→ persistence
→ next active slot
┌─────────────────────────────────────────────────────────────┐
│ Input sources │
│ │
│ Human CLI Web form Batch JSON AI Jupyter │
└──────┬─────────┬─────────┬──────┬─────┬──────┬─────────────┘
│ │ │ │ │ │
└─────────┴─────────┴──────┴─────┴──────┘
|
v
┌───────────────────┐
│ SlotCommand │
└─────────┬─────────┘
|
v
┌───────────────────┐
│ Sequential │
│ interpreter │
└─────────┬─────────┘
|
v
┌───────────────────┐
│ Orchestrator │
│ single writer │
└──────┬───────┬────┘
│ │
v v
JSONWF external systems
|
v
history store
JSONWF processes commands one at a time.
command 1
→ validate
→ execute
→ persist stable state
command 2
→ validate against the new state
→ execute
→ persist stable state
This remains true even when the input arrives as:
The system does not bulk-apply the entire plan.
This matters because provisioning is state-dependent.
A device cannot be validated before the location context exists.
An interface cannot be selected before the device exists.
An IP address should not be assigned before the range and target interface are known.
Sequential interpretation preserves:
ordering
validation context
error position
auditability
rollback boundaries
reproducibility
There are no explicit navigation commands such as:
next
done
continue
close_slot
A slot advances when:
required fields are present
AND validation succeeds
AND the mapped operation succeeds
The orchestrator then:
removes the completed step from fn
adds a completion record
merges returned data
persists the stable document
derives the next active slot
The interface simply reflects the new workflow state.
loc> DLLSTXB1
dev>
dev> is not printed because a next command was executed.
It appears because the active slot became dev.
This same rule applies to the Web interface. A checkbox, Tab, field blur, or action button may submit the current slot, but the orchestrator decides whether the workflow advances.
JSONWF supports two rollback forms:
When no target is supplied, rollback selects the most recent completed slot that is eligible for rollback.
dev> rollback
This is a convenience form for interactive use. It does not mean that rollback is limited to generic backward navigation.
A target slot may be named explicitly:
intf> rollback device
The orchestrator reverts the workflow to the specified slot and cascades the rollback through every dependent slot. For example, rolling back device may invalidate and remove the downstream vrf, interface, ip_range, ip_address, and assignment state.
rollback(device) → clear or compensate device → discover dependent slots → clear or compensate dependents → reinsert affected functions into fn[] → persist rollback history → derive the new active slot
For a selection-only slot, rollback may only clear stored values and reconstruct the remaining sequence. For a slot that changed an external system, rollback may invoke a compensation function.
create_vrf → compensate with delete_vrf allocate_ip_address → compensate with release_ip_address
JSONWF therefore treats rollback as:
targeted workflow-state revision + dependency cascade + optional external compensation + recorded history
It does not claim transactional undo across all external systems.
JSONWF rollback is a controlled, auditable return to a selected slot, with cascading invalidation or compensation of dependent state.
JSONWF separates input errors from execution errors.
These occur before a domain operation starts:
unknown_slot
slot_out_of_sequence
unknown_verb
unknown_attribute
missing_value
invalid_assignment
invalid_value
These occur after the orchestrator calls the mapped function:
operation_failed
timeout
exception
ambiguous_result
external_system_unavailable
Example:
{
"status": "waiting",
"fn_exception": {
"fn": "select_device",
"reason": "device unreachable",
"s": "260802111030",
"f": "260802111035"
}
}
The active slot remains:
dev>
The workflow does not advance merely because more commands exist in a batch or AI plan.
JSONWF is moving toward a hybrid model in which humans and AI can both propose provisioning actions.
The AI does not receive unrestricted access to domain functions.
It generates the same command language used by the human operator.
vrf> myvrf rd=100 rt=101
{
"slot": "vrf",
"value": "myvrf",
"attributes": {
"rd": "100",
"rt": "101"
}
}
Both become the same internal command.
SlotCommand(
slot="vrf",
verb="set",
value="myvrf",
attributes={
"rd": "100",
"rt": "101"
}
)
The deterministic runtime then checks:
Is this the active slot?
Is the action allowed?
Are the attributes known?
Are required values present?
Do values pass domain validation?
Did the external operation succeed?
May the workflow advance?
This creates a clear boundary:
Human or AI
→ proposes an action
JSONWF runtime
→ validates legality
→ executes
→ records
→ handles failure
→ decides completion
The AI can assist with selection, planning, and command generation.
The runtime remains responsible for procedural legality and execution state.
JSONWF does not claim that structural validation guarantees perfect domain decisions.
A syntactically valid command can still contain a poor operational choice.
For example:
the selected device may be technically reachable
but operationally unsuitable for the service
JSONWF therefore distinguishes several levels:
syntactic validity
slot validity
workflow-order validity
domain validation
policy validation
external confirmation
human approval where required
The hybrid direction is not:
AI produces commands and the system assumes they are correct.
It is:
AI proposes commands inside a constrained slot model, and deterministic plus human validation decides whether they may be executed.
The Web interface uses the same slot registry.
slot
→ fields
→ required attributes
→ validators
→ allowed operations
→ completion behavior
The browser submits a slot command.
{
"slot": "vrf",
"verb": "set",
"value": "myvrf",
"attributes": {
"rd": "100",
"rt": "101"
}
}
The Web application does not implement a parallel workflow.
It is a visual client for the same slot semantics.
This creates a near-direct mapping:
CLI prompt ↔ Web panel
CLI value ↔ Web field value
CLI attributes ↔ Web form fields
slot validator ↔ form validation
slot completion↔ panel completion
rollback ↔ rollback control
A batch file is a saved dialogue:
loc>DLLSTXB1;
dev>R1;
vrf>myvrf rd=100 rt=101;
intf>ge-0/0/1;
JSON is a structured version of the same dialogue:
{
"commands": [
{"slot": "loc", "value": "DLLSTXB1"},
{"slot": "dev", "value": "R1"},
{
"slot": "vrf",
"value": "myvrf",
"attributes": {
"rd": "100",
"rt": "101"
}
}
]
}
Both are executed one command at a time through the same interpreter.
This provides deterministic replay and exact failure location.
Jupyter Notebook is used as a diagnostic and support interface.
It can:
The notebook must call the same runtime API.
runtime.execute(
order_id,
SlotCommand(
slot="dev",
verb="rollback",
source="jupyter"
)
)
It should not directly modify:
doc["fn"]
doc["status"]
database rows
This keeps diagnostics inside the same audit and validation path.
history store
|
v
support runtime
|
v
Jupyter notebook
|
+--> inspect
+--> compare
+--> retry
+--> rollback
+--> validate AI output
The slot is the common unit for:
workflow
CLI
Web
batch
JSON
AI
validation
rollback
diagnostics
No client bypasses the interpreter.
The JSONWF document holds the recoverable process state.
Input and execution failures are represented consistently.
Every interface invokes the same controlled rollback or compensation path.
Both produce the same command model and are validated by the same runtime.
The current process can be understood by reading the JSONWF document and its history.
A production implementation should version:
process definition
slot schema
function mapping
document schema
For example:
{
"process": "l3vpn_provisioning",
"process_version": "1.3",
"slot_schema_version": "1.2",
"mapping_version": "2026.08"
}
This prevents an old persisted workflow from being resumed against incompatible execution semantics.
All document updates should pass through the orchestrator, which remains the single writer.
Readable JSON must not be confused with unrestricted direct mutation.
JSONWF is especially valuable when the application needs several of these properties at once:
sequential provisioning
human interaction
AI assistance
Web and CLI parity
partial completion
external-system errors
rollback or compensation
persistent diagnostics
support intervention
auditability
A conventional API plus forms can implement each property separately.
JSONWF makes them share one execution model.
┌────────────────────────────────────────────────────────────┐
│ Humans, AI, Web, batch, JSON, Jupyter │
└───────────────────────────┬────────────────────────────────┘
|
v
┌─────────────────────┐
│ SlotCommand │
└──────────┬──────────┘
|
v
┌─────────────────────┐
│ Slot-context │
│ interpreter │
└──────────┬──────────┘
|
v
┌─────────────────────┐
│ Orchestrator │
│ validation │
│ function mapping │
│ error processing │
│ rollback │
│ persistence │
└──────┬────────┬─────┘
│ │
v v
JSONWF external systems
|
v
history
jsonwf(contains, provisioning_state).
jsonwf(contains, remaining_execution).
jsonwf(contains, completion_history).
jsonwf(contains, current_error).
jsonwf(contains, rollback_history).
slot(defines, interaction_context).
slot(defines, validation).
slot(defines, function_mapping).
slot(defines, completion).
slot(defines, rollback).
slot(defines, cli_prompt).
slot(defines, web_form).
slot(defines, ai_command_schema).
human(proposes, slot_command).
ai(proposes, slot_command).
web(produces, slot_command).
batch(produces, slot_command_sequence).
json(produces, slot_command_sequence).
jupyter(produces, controlled_diagnostic_action).
interpreter(processes, commands, sequentially).
orchestrator(validates, commands).
orchestrator(executes, mapped_functions).
orchestrator(processes, errors).
orchestrator(updates, jsonwf).
orchestrator(persists, stable_snapshots).
JSONWF is a compact slot-contextual execution model for provisioning and operational workflows.
Its main contribution is not a new workflow notation. It is a unified semantics for several command producers and several interfaces.
A human operator, a Web form, a batch script, a JSON integration, an AI model, and a Jupyter support notebook all interact through the same slot contract and the same sequential interpreter.
This creates a practical foundation for hybrid human + AI provisioning:
AI proposes
human reviews where required
runtime validates
orchestrator executes
JSONWF records
Jupyter diagnoses
The system remains small because the workflow state, interaction context, validation path, execution history, and rollback semantics are kept in one coherent model.
The direction is clear:
hybrid provisioning in which humans and AI share one constrained operational language, while deterministic validation and persistent workflow state remain in control.