.grafcetio File Format

Technical Documentation

The .grafcetio format is a JSON-based file format for storing and exchanging GRAFCET diagrams. This documentation describes the structure and all available elements.

1. File Structure

A .grafcetio file is a JSON file with the following basic structure:

{
  "version": "1.0",
  "createdWith": "grafcet.io",
  "createdAt": "2024-01-15T10:30:00.000Z",
  "nodes": [...],
  "edges": [...],
  "counter": 5
}

versionVersion number of the file format (currently always "1.0")
createdWithName of the application that created the file
createdAtCreation timestamp in ISO 8601 format
nodesArray containing all GRAFCET symbols (steps, transitions, actions, etc.)
edgesArray containing all directed links (connections between symbols)
counterInternal counter for assigning unique element IDs

2. GRAFCET Symbols

All symbols are stored in the "nodes" array. Each symbol has the following basic structure:

{
  "id": "step-1",
  "type": "step",
  "position": { "x": 400, "y": 240 },
  "data": { "label": "1" }
}

idUnique identifier of the symbol (e.g., "step-1", "transition-2")
typeType of symbol (see symbol types below)
positionPosition on the canvas in pixels (x/y coordinates)
dataSymbol-specific data such as label, action type, etc.

Available Symbol Types

stepStep

Represents a state in the sequence diagram. Displayed as a rectangle with step number.

Stores: Step number (e.g., "1", "2", "10")

initialStepInitial Step

The start state of the GRAFCET, automatically activated on initialization. Displayed as a rectangle with double border.

Stores: Step number (typically "0")

transitionTransition

Defines the transition condition between steps. Displayed as a horizontal line with condition text.

Stores: Transition condition (e.g., "a", "a AND b", "!x", "*" for always true)

actionAction

Describes an output or action executed when the step is active. Placed to the right of the associated step.

Stores: Action name, action type, time value, additional condition

andNodeSimultaneous Divergence

Enables parallel sequences in GRAFCET. Displayed as a double horizontal line. Can have multiple incoming and outgoing connections.

Stores: Width (default: 240px), optional label

loopNodeLoop

Feedback symbol in GRAFCET. Displayed as a vertical line with an upward-pointing triangle arrow. Two symbols with matching reference markers replace a long feedback line.

Stores: Reference marker (e.g., "*", "A")

textText Annotation

Free text field for comments and annotations in the diagram. Not part of the GRAFCET logic.

Stores: Display text, font size, bold

enclosingStepEnclosing Step

Step that contains a partial sequence (enclosure). Displayed as a rectangle with two vertical lines.

Stores: Step number

macroStepMacro Step

References a partial GRAFCET (macro expansion). Displayed as a rectangle with two horizontal lines.

Stores: Macro number

startTransitionSource Transition

Transition without a preceding step that is always enabled (IEC 60848).

Stores: Transition condition

pitTransitionSink Transition

Transition without a following step; deactivates the preceding step.

Stores: Transition condition

forcedCommandForcing Command

Forces a state in another GRAFCET. Displayed as a box with a double border.

Stores: Label, action type, time value, additional condition

orNodeAlternative Divergence

Selection between alternative branches (OR divergence/convergence). Displayed as a single horizontal line.

Stores: Width, optional label

boxNodeComment Frame

Frame for grouping or annotating areas. Not part of the GRAFCET logic.

Stores: Width, height, top label (number), bottom label (name)

startLoopFeedback (Start)

Start symbol of a jump/feedback; references the jump target via a shared reference marker.

Stores: Reference marker

endLoopFeedback (Target)

Target symbol of a jump/feedback.

Stores: Reference marker

Action:

{
  "id": "action-1",
  "type": "action",
  "position": { "x": 500, "y": 230 },
  "data": {
    "label": "Motor ein",
    "actionType": "continuous"
  }
}

{
  "id": "action-2",
  "type": "action",
  "position": { "x": 500, "y": 350 },
  "data": {
    "label": "Ventil öffnen",
    "actionType": "delayed",
    "time": "5s",
    "condition": "p1"
  }
}

3. Action Types (IEC 60848)

Actions can have different types that determine their behavior. The action type is represented graphically:

Action Type	Representation	Description
`continuous`	Simple box	Action is active as long as the associated step is active
`set`	Box with arrow ↑	Action is turned on and remains active after the step is deactivated
`reset`	Box with arrow ↓	Action is turned off (resets a previously set action)
`delayed`	Box with time annotation	Action starts only after the specified time has elapsed
`limited`	Box with time limit	Action automatically ends after the specified time
`pulse`	Box with pulse symbol	Single short pulse when the step is activated
`conditional`	Box with condition line	Action is only executed if the additional condition is met

4. Directed Links

Directed links connect GRAFCET symbols and define the flow. They are stored in the "edges" array.

{
  "id": "e-step-1-transition-1",
  "source": "step-1",
  "sourceHandle": "bottom",
  "target": "transition-1",
  "targetHandle": "top",
  "type": "defaultEdge"
}

idUnique identifier of the connection
sourceID of the source symbol (where the line starts)
targetID of the target symbol (where the line ends)
sourceHandleConnection point on the source symbol
targetHandleConnection point on the target symbol
typeType of directed link

Link Types

labeledEdge

Standard Directed Link – Standard connection with a label. Connects steps with transitions and transitions with steps (default type).

defaultEdge

Simple Directed Link – Simple connection without a label.

loopEdge

Feedback Link – Curved line for feedbacks and jumps.

Connection Points

Each symbol has defined connection points for directed links:

"top" - Input from above
"bottom" - Output downward
"left" - Input from left (for actions)
"right" - Output to right (for action links)
For simultaneous divergences: "handle-0", "handle-1", ... (top) and "source-0", "source-1", ... (bottom)

Try the Editor

Create your own GRAFCET diagram and export it as a .grafcetio file!

Go to Editor