Migration Guide: JSON → .wsl

This guide helps you translate existing JSON-based workflow definitions to the native .wsl syntax used by Kuetix Engine.

See also:

• WSL Specification — the authoritative WSL syntax, grammar, CST/AST, and validation rules
• Existing examples under runtime/workflows/wsl_hello_world/example.wsl

---

1) Field mapping

JSON field	Meaning	.wsl construct
name	Transition name	state <Name> { ... } or alias via as <Alias>
input[]	Input variables and types	State parameters: state <Name>(Param1, Param2) { ... }
output[]	Output variables and types	Capture with as <Alias> and pass to next state: Next(Alias)
next	Next transition name	on success -> <NextState>(...)
exceptions[]	Errors/exception handling	on error -> <ErrorState> or end error
from (WLSS)	Previous/allowed sources	Encode via preceding state transitions
to (WLSS)	Next step	on success -> <State> or separate branch
true / false	Conditional paths	Use on success / on error branches or explicit decision states
type	Step type (initial/normal/final)	start: <State> and terminal end ok / end error

---

2) Example: Token generation (JSON) → .wsl

JSON:

{
  "name": "GenerateToken",
  "input": [{ "name": "user", "type": "domain.User" }],
  "output": [{ "name": "loginResponse", "type": "responses.LoginResponse" }],
  "next": "EncryptedId",
  "exceptions": [
    { "name": "TokenGenerationFailed", "message": "Failed to generate access or refresh token", "code": 500 }
  ]
}

WSL:

state GenerateToken(User) {
  action login/GenerateToken(user: User) as Token
  on success -> EncryptedId(User)
  on error -> TokenGenerationFailed
}

state TokenGenerationFailed {
  action response/ResponseError(message: "Failed to generate access or refresh token", code: 500)
  end error
}

---

3) Example: Steps (WLSS) JSON → .wsl

JSON (excerpt):

{
  "from": ["workflow:repositorium/user/get"],
  "to": "login/CheckPassword",
  "type": "normal"
}

WSL:

state GetUser(Req) {
  action workflow/repositorium/user/get(id: "<<helpers.Id(Req.Email)>>") as User
  on success -> CheckPassword(Req, User)
}

---

4) Tips and patterns

• Use module and import at the top of your .wsl files to mirror namespaces used in JSON.
• Replace arrays of transitions with explicit state blocks connected with on success / on error.
• Use as <Alias> to capture output and pass it positionally to the next state: Next(Alias).
• Inline objects are supported as arguments: {response: $constants.event, statusCode: 202}.
• References start with $ (e.g., $User.ID, $constants.event).
• Built-in filters use | for value transformation (e.g., statusCode|int, or inside templates: "<<a|int>>").

---

5) Validation checklist

• There is exactly one start: <State> in each workflow.
• All states referenced by transitions exist.
• Argument counts match the target state parameters.
• end ok or end error appears only at the end of a state body.

---

6) Where to look for working examples

• Minimal Hello World: runtime/workflows/wsl_hello_world/example.wsl
• This guide and docs/WSL_SPEC.md for syntax nuances
• Tests under tests/workflows for patterns like assertions and responses