MachineSpec v2 Format

Understanding the JSON format exported by the Process Editor.

Table of contents

  1. Overview
  2. Basic Structure
    1. Root Properties
  3. State Definitions
    1. State Properties
  4. Transitions
    1. Transition Formats
    2. Transition Properties
  5. Timers
    1. Timer Properties
    2. Duration Format (ISO 8601)
  6. Metadata
    1. Metadata Properties
  7. Complete Example

Overview

The Process Editor exports processes as MachineSpec v2 JSON, a format designed for executable state machines in insurance applications.

Basic Structure 

1
2
3
4
5
6
7

{
  "id": "quote",
  "version": 1,
  "initial": "created",
  "metadata": { /* optional metadata */ },
  "states": { /* state definitions */ }
}

Root Properties

Property Type Required Description
id string ✅ Process identifier
version number ✅ Definition version
initial string ✅ Initial state name
metadata object ❌ Process metadata
states object ✅ State definitions

State Definitions

Each state in the states object represents a Task or End Event:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

{
  "states": {
    "created": {
      "id": "task_created",
      "type": "task",
      "on": { /* transitions */ },
      "timers": [ /* timer definitions */ ],
      "metadata": { /* custom data */ }
    },
    "completed": {
      "id": "end_completed", 
      "type": "end"
    }
  }
}

State Properties

Property Type Required Description
id string ❌ Stable element ID
type string ❌ "task" or "end"
on object ❌ Event transitions
timers array ❌ Timer definitions
metadata object ❌ Custom state data

Transitions

Transitions define how the process moves between states:

1
2
3
4
5
6
7
8
9
10
11

{
  "on": {
    "APPROVE": {
      "id": "flow_approve",
      "target": "approved",
      "guard": "isReviewer",
      "actions": ["recordApproval", "sendNotification"]
    },
    "REJECT": "rejected"
  }
}

Transition Formats

Simple Transition (string):

1

"COMPLETE": "completed"

Complex Transition (object):

1
2
3
4
5
6

"APPROVE": {
  "id": "flow_approve",
  "target": "approved", 
  "guard": "isReviewer",
  "actions": ["recordApproval"]
}

Transition Properties

Property Type Required Description
target string ✅ Target state name
id string ❌ Stable flow ID
guard string ❌ Guard function name
actions array ❌ Side effect function names
condition string ❌ Future: expression conditions

Timers

Timers trigger automatic transitions after time periods:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

{
  "timers": [
    {
      "id": "collection_timeout",
      "type": "DURATION",
      "iso": "P14D",
      "event": "COLLECTION_EXPIRED"
    },
    {
      "id": "deadline",
      "type": "DATE", 
      "at": "2024-12-31T23:59:59Z",
      "event": "DEADLINE_REACHED"
    }
  ]
}

Timer Properties

Property Type Required Description
id string ✅ Unique timer ID
type string ✅ "DURATION" or "DATE"
event string ✅ Event to trigger
iso string ⚠️ ISO duration (required for DURATION)
at string ⚠️ ISO datetime (required for DATE)

Duration Format (ISO 8601)

Format Description Example
PnD n days P14D (14 days)
PTnH n hours PT2H (2 hours)
PTnM n minutes PT30M (30 minutes)
PTnS n seconds PT45S (45 seconds)
Combined Multiple units P1DT2H30M (1 day, 2 hours, 30 minutes)

Metadata

Optional metadata for documentation and tooling:

1
2
3
4
5
6
7
8
9
10

{
  "metadata": {
    "documentation": "Insurance quote lifecycle process",
    "lanes": {
      "Customer": ["created", "submitted"],
      "Reviewer": ["under_review", "approved"], 
      "Finance": ["payment_pending", "paid"]
    }
  }
}

Metadata Properties

Property Type Description
documentation string Process description
lanes object Responsibility groupings

Complete Example

Here’s a complete MachineSpec for an insurance quote process:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57

{
  "id": "quote",
  "version": 1,
  "initial": "created",
  "metadata": {
    "documentation": "Insurance quote lifecycle",
    "lanes": {
      "Customer": ["created"],
      "Reviewer": ["approved"],
      "Finance": ["ready_for_collection", "paid_full"]
    }
  },
  "states": {
    "created": {
      "id": "task_created",
      "type": "task",
      "on": {
        "APPROVE": {
          "id": "flow_approve",
          "target": "approved",
          "guard": "isReviewer"
        }
      }
    },
    "approved": {
      "id": "task_approved",
      "type": "task", 
      "on": {
        "READY_FOR_COLLECTION": {
          "target": "ready_for_collection"
        }
      },
      "timers": [
        {
          "id": "timer_collection",
          "type": "DURATION",
          "iso": "P14D",
          "event": "COLLECTION_EXPIRED"
        }
      ]
    },
    "ready_for_collection": {
      "id": "task_ready",
      "type": "task",
      "on": {
        "PAY_FULL": {
          "target": "paid_full",
          "actions": ["recordPayment"]
        }
      }
    },
    "paid_full": {
      "id": "end_paid",
      "type": "end"
    }
  }
}

This example shows:

  • 4 states: 3 tasks + 1 end event
  • 3 transitions: With different configurations
  • 1 timer: 14-day collection timeout
  • 1 action: Payment recording
  • 1 guard: Reviewer authorization
  • Lane organization: By responsibility

Copyright © 2025 Etherisc. Distributed under the MIT License.