# BPMN diagram syntax
## Flow objects
Flow objects are the most basic building blocks in a BPMN diagram.
Flow object definitions consist of a name followed by a set of properties including the. `type` property which determines whether it is an `**activity**`, `**event**`, or `**gateway**`. If omitted, it defaults to `activity`.
```eraser
Place order[type: activity]
Shipped[type: event]
Approved?[type: gateway]
```
Flow object names are required to be unique.
Flow objects support `type`, `icon`, `color`, and `label` properties. More on properties below.
## Pools and Lanes
A **pool** is the top-level container which usually maps to organizations or departments. A pool can contain flow objects as well as lanes.
A **lane** is a sub container inside a pool which usually maps to roles or sub-organizations.
Pool and lane definitions consist of a name followed by `{ }`. The outermost brackets are assumed to be pools and any inner nested brackets are assumed to be lanes. For example, `Online store` is the name of the pool, which contains a `Warehouse` lane, which in turn contains the `Place order`, `Shipped`, and `Approved?` flow objects.
```eraser
Online store {
Warehouse {
Place order[type: activity]
Shipped[type: event]
Approved?[type: gateway]
}
}
```
Pools and lanes support `icon`, `color`, and `label` properties.
## Properties
Properties are key-value pairs enclosed in `[ ]` brackets that can be appended to definitions of flow objects, pools, and lanes. Properties are optional.
Here are the properties that are allowed:
| Property | Description | Value | Default Value |
| :---------- | :------------------------ | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :------------------------------ |
| `type` | Flow object type | `activity`, `event`, `gateway` | `activity` |
| `icon` | Icon | Icon names (e.g. `user`). See [Icons](/icons) page for full list. | |
| `color` | Stroke and fill color | Color name (e.g. `blue`) or hex code (e.g. `"#000000"`- note: must be wrapped in quotes) | |
| `label` | Text label | Any string. Enclose in double quotes (e.g. `"Acme Corp"`) if containing a space. Allows multiple flow objects, pools, and lanes to have the `label`. | Name of flow object, pool, lane |
| `link` | Internal or external link | A fully fledged URL. Enclose in double quotes (e.g. "[https://my-internal-docs.io/api-docs](https://my-internal-docs.io/api-docs)". Supports the full gamut of external links and Eraser-specific links: diagrams, headers, and files in Eraser. | |
| `colorMode` | Fill color lightness | `pastel`, `bold`, `outline` | `pastel` |
| `styleMode` | Embellishments | `shadow`, `plain`, `watercolor` | `shadow` |
| `typeface` | Text typeface | `rough`, `clean`, `mono` | `rough` |
Here are the lists of icon names:
* [General Icons](/icons#general-icons)
* [Tech Logos](/icons#tech-logos)
* [AWS Icons](/icons#aws-icons)
* [Google Cloud Icons](/icons#google-cloud-icons)
* [Azure Icons](/icons#azure-icons)
The `label` property is useful if you want multiple flow objects, pools, or lanes, to have the same label since names are required to be unique. By default, the `label` is set as the name.
```eraser
// Names need to be distinct, but labels can overlap
Employee_A [label: employee]
Employee_B [label: employee]
```
Refer to [Styling](/styling) for more details and examples on the `colorMode`, `styleMode`, and `typeface` properties.
It is possible to set multiple properties by separating them using `,` like shown below:
```eraser
Place order [type: activity, icon: flag]
```
## Connections
Connections represent show how work progresses, messages travel, or data links between elements in the process.
Here is an example of a connection between two activities:
```eraser
Open website > Place order
```
Here are the types of connectors:
| Connector | Syntax | Description |
| --- | --- | --- |
|  | `>` | Left-to-right arrow |
|  | `<` | Right-to-left arrow |
|  | `<>` | Bi-directional arrow |
|  | `-` | Line |
|  | `--` | Dotted line |
|  | `-->` | Dotted arrow |
### Connection label
It is possible to add a label to a connection. Here is an example:
```eraser
Open website > Place order: Browse
```
### Connection properties
Here are the properties that are allowed on connections (lines):
Property
Description
Example
`color`
Line color
`Open website > Place order: Browse[color: blue]\`
`Open website > Place order: [color: blue]`
## Icons
Here's a [list of all the icons you can use with diagram-as-code](/icons).
## Escape string
Certain characters are not allowed in names because they are reserved. To use these characters, you can wrap the entire flow object, pool, or lane name in quotes `" "`.
```eraser
Customer {
Open website [type: activity]
"Place / cancel order" [type: activity]
}
```
## Styling
Styles can be applied at the diagram level. Below is an overview of the options and syntax. Refer to [Styling](/styling) for more details and examples.
| Property | Values | Default value | Syntax example |
| :---------- | :------------------------------ | :------------ | :----------------- |
| `colorMode` | `pastel`, `bold`, `outline` | `pastel` | `colorMode bold` |
| `styleMode` | `shadow`, `plain`, `watercolor` | `shadow` | `styleMode shadow` |
| `typeface` | `rough`, `clean`, `mono` | `rough` | `typeface clean` |
## Legends
Legends map a swatch (connection, icon, shape, or color) to a label. Swatches are not tied to actual elements in the diagram.
```eraser
legend {
[connection: -->, label: Async]
[color: red, label: Error]
[icon: aws-lambda, label: Lambda]
[shape: diamond, label: Decision]
}
```
### Legend properties
| Property | Description | Value | Default Value |
| :------- | :----------------------------------- | :------------------------------------------ | :------------ |
| position | Position of the legend on the canvas | Position names (e.g. `top-left` or `right`) | `top-right` |
```eraser
legend [position: bottom-left] {
[color: red, label: Error]
}
```
Here is the list of positions:
`top-left`, `top-right` (default), `bottom-left`, `bottom-right`, `top`, `bottom`, `left`, `right`
### Legend item properties
Each legend item is enclosed in `[ ]` and must include a `label` and at least one swatch property.
| Property | Description | Value |
| :--------- | :---------------- | :------------------------------------------------------------ |
| label | Text label | Any string. Enclose in double quotes if containing a space. |
| connection | Connection swatch | Connection types (e.g. `-->` or `<>`). See Connections above. |
| color | Color swatch | Color name (e.g. `blue`) or hex code (e.g. `"#000000"`) |
| icon | Icon swatch | Icon names (e.g. `aws-ec2`). See Icons page for full list. |
| shape | Shape swatch | Shape names (e.g. `diamond` or `oval`). |
`color` can be combined with `connection` or `shape`. Other swatch types are mutually exclusive.
```eraser
legend {
[connection: -->, color: orange, label: Async backup]
[shape: rectangle, color: blue, label: Active]
}
```