ERD syntax

Entities

Entities correspond to database tables or similar. Entities contain attributes.

Entity definitions consist of a name followed by { }. For example, users is the name of the below entity and it contains attributes id and displayName.

users {
id string
displayName string
}

Entity relationship diagram rendered from the code above, with an entity “users” and attributes id and displayName.

It is possible for entities to contain nothing like the below.

users { }

Entity relationship diagram rendered from the code above, with an empty entity “users”.

Entity names are required to be unique.

Attributes

Attributes correspond to database table columns or similar.

Attribute definitions occur within an entity definition. They consist of a name, type (optional), and metadata (optional) delimited by the space character. Here is an example:

users {
id string pk
}

Entity relationship diagram rendered from the code above, with an entity “users” and the attribute id string pk.

Everything after the type is metadata, shown as written: for example pk, fk or unique not null. Wrap a type in double quotes when it contains a space:

products {
  id int pk
  format "enum(DVD, Blu-ray)"
  price decimal(10,2)
}

Outside of a definition (e.g. in a relationship statement), attributes are referred to following the entity that they belong to, separated by a .. Here is an example:

users.teamId > teams.id

Properties

Properties are key-value pairs enclosed in [ ] brackets that can be appended to entity definitions. Properties are optional.

It is possible to set multiple properties like shown below:

users [icon: user, color: blue] {
 // ...rows
}

Entity relationship diagram with a blue “users” entity with a user icon, connected from its teamId attribute to the id attribute of a “teams” entity.

Here are the properties that are allowed:

Property	Description	Value	Default value
`icon`	Attached icons	Icon names (e.g. `aws-ec2`). See Icons page for full list.
`color`	Stroke and fill color, when possible	Color name (e.g. `blue`) or hex code (e.g. `#000000`)
`colorMode`	Fill color lightness	`pastel`, `bold`, `outline`	`pastel`
`styleMode`	Embellishments	`shadow`, `plain`, `watercolor`	`shadow`
`typeface`	Text typeface	`rough`, `clean`, `mono`	`rough`
`textSize`	Text size	`small`, `medium`, `large`	`small`

Here are the lists of icon names:

Refer to Styling for more details and examples on the colorMode, styleMode, typeface, and textSize properties.

Relationships

Relationships show the attribute-level relations between entities.

Here is an example:

users.teamId > teams.id

Entity relationship diagram rendered from the code above, with 1 connection.

It is possible to omit the attribute-level and simply show entity-level relations like this:

users > teams

The type of connecting line represents the cardinality between the two entities. Here are the types:

Connector	Syntax	Description
	`<`	One-to-many
	`>`	Many-to-one
	`-`	One-to-one
	`<>`	Many-to-many

If a relationship statement contains a name that has not been previously defined as an entity or attribute, an entity or attribute with that name will be created.

Here are the properties that are allowed on relationships (lines):

Property	Description	Example
`color`	Line color	`users.teamId > teams.id: [color: green]`

The : before the [ ] is required. Without it, the relationship is dropped.

Icons

Here’s a list of all the icons you can use with diagram-as-code.

Escape string

Certain reserved characters are not allowed in entity or attribute names. However, you can still use these characters by wrapping the entire entity or attribute name in quotes " ".

"CI/CD" [icon: gear] {
    id string pk
}

A name whose first word is a diagram keyword is read as that keyword instead: title, legend, colorMode, styleMode, typeface, textSize and notation, in any case. Wrap such names in quotes too:

"legend" {
    id string pk
}

Comments

Text after // is a comment and is ignored.

// This line is a comment

Title

A title line sets the diagram’s title, the same one you can edit from the property bar.

title Billing data model

Styling

Styles can be applied at the diagram level. Below is an overview of the options and syntax. Refer to 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`
`notation`	`chen`, `crows-foot`	`chen`	`notation crows-foot`
`textSize`	`small`, `medium`, `large`	`small`	`textSize medium`

Legends

Legends map a swatch (connection, icon, shape, or color) to a label. Swatches are not tied to actual elements in the diagram.

 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`

  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 it contains a comma, colon or bracket.
connection	Connection swatch	Arrow types (e.g. `-->` or `<>`).
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.

legend {  
    [connection: -->, color: orange, label: Async backup]  
    [shape: rectangle, color: blue, label: Active]  
}