.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

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

defaultEdge

Standard Link – Connects steps with transitions and transitions with steps. Also for connections to simultaneous divergences.

actionEdge

Action Link – Horizontal connection between a step and its associated action.

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)

5. Compact Sharing Format (v2)

When sharing via link, grafcet.io uses a compact format with short keys. The data is compressed with Deflate and stored as Base64URL in the URL (?g=...). This reduces data size by approximately 40%.

Node Fields

Full	Compact
id	i
type	t
position	p ([x,y])
data.label	l
data.actionType	a
data.time	ti
data.condition	co
data.width	w
data.height	h
data.bottomLabel	bl
data.rotation	r
zIndex	z

Node Type Codes

Full	Compact
step	S
initialStep	I
transition	T
action	A
enclosingStep	E
enclosingInitialStep	EI
macroStep	M
andSplit	AS
andJoin	AJ
andNode	AN
text	X
endLoop	L
loopNode	LN
forcedCommandUp	FU
forcedCommandDown	FD
boxNode	B

Edge Fields

Full	Compact
id	i
source	s
target	t
sourceHandle	sh
targetHandle	th
type	y
data.waypoints	w ([[x,y],...])

Handle Codes

Full	Compact
top	T
bottom	B
left	L
right	R
handle-N	hN
source-N	sN

Positions are stored as [x,y] arrays with integers. Old v1 links remain compatible.

Try the Editor

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

Go to Editor