Mermaid ContainerDiagram Spec¶
Source: mermaid.container-diagram.json
This schema describes the ContainerDiagram spec for the Mermaid backend.
Properties¶
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Type of the diagram. Must be exactly ContainerDiagram. |
title |
string | null |
Optional diagram title. |
elements |
array[Element] |
Top-level elements. |
boundaries |
array[Boundary] |
Top-level boundaries. |
relationships |
array[MermaidRelationshipSchema] |
Top-level relationships. |
render_options |
MermaidRenderOptionsSchema |
Mermaid-specific render options. |
backend(required) |
string |
JSON schema backend. Must be exactly mermaid. |
Examples
JSON source
{
"backend": "mermaid",
"type": "ContainerDiagram",
"title": "Web App",
"elements": [
{
"type": "Person",
"alias": "user",
"label": "User"
}
],
"boundaries": [
{
"type": "SystemBoundary",
"alias": "system",
"label": "Simple System",
"elements": [
{
"type": "Container",
"alias": "web",
"label": "Web App",
"technology": "React"
},
{
"type": "Container",
"alias": "api",
"label": "API",
"technology": "Python"
},
{
"type": "ContainerDb",
"alias": "db",
"label": "Database",
"technology": "PostgreSQL"
}
]
}
],
"relationships": [
{
"type": "REL",
"from": "user",
"to": "web",
"label": "Uses"
},
{
"type": "REL",
"from": "web",
"to": "api",
"label": "Calls"
},
{
"type": "REL",
"from": "api",
"to": "db",
"label": "Reads/Writes"
}
]
}
Rendered Mermaid source
C4Container
title Web App
Person(user, "User")
System_Boundary(system, "Simple System") {
Container(web, "Web App", "React")
Container(api, "API", "Python")
ContainerDb(db, "Database", "PostgreSQL")
}
Rel(user, web, "Uses")
Rel(web, api, "Calls")
Rel(api, db, "Reads/Writes")
Rendered image
JSON source
{
"backend": "mermaid",
"type": "ContainerDiagram",
"title": "Online Shop - Container Diagram",
"elements": [
{
"type": "Person",
"alias": "customer",
"label": "Customer",
"description": "Browses products and places orders.",
"properties": {
"properties": [
[
"Channel",
"Web / Mobile"
]
]
}
},
{
"type": "PersonExt",
"alias": "support_agent",
"label": "Support Agent",
"description": "Investigates customer issues from an external support tool.",
"properties": {
"properties": [
[
"Organization",
"Support Vendor"
]
]
}
},
{
"type": "SystemExt",
"alias": "payment_provider",
"label": "Payment Provider",
"description": "Processes card payments and payment webhooks."
},
{
"type": "ContainerExt",
"alias": "recommendation_api",
"label": "Recommendation API",
"description": "Returns personalized product recommendations."
},
{
"type": "ContainerDbExt",
"alias": "fraud_db",
"label": "Fraud Signals DB",
"description": "External datastore containing fraud intelligence.",
"technology": "Vendor DB"
},
{
"type": "ContainerQueueExt",
"alias": "shipping_events",
"label": "Shipping Events Topic",
"description": "External topic used by logistics partner.",
"technology": "Kafka"
}
],
"boundaries": [
{
"type": "EnterpriseBoundary",
"alias": "acme",
"label": "Acme Corp",
"description": "Enterprise boundary for internal platforms.",
"properties": {
"properties": [
[
"Region",
"EU"
],
[
"Business Unit",
"Digital Commerce"
]
]
},
"boundaries": [
{
"type": "SystemBoundary",
"alias": "shop_boundary",
"label": "Online Shop Platform",
"description": "Main system boundary for the commerce platform.",
"properties": {
"properties": [
[
"Owner",
"Commerce Team"
],
[
"Environment",
"Production"
]
]
},
"elements": [
{
"type": "Container",
"alias": "web_app",
"label": "Web Application",
"description": "Serves the storefront and checkout UI.",
"technology": "React + Next.js",
"properties": {
"properties": [
[
"Runtime",
"Node.js"
],
[
"Team",
"Storefront"
]
]
}
},
{
"type": "Container",
"alias": "backend_api",
"label": "Backend API",
"description": "Handles catalog, carts, checkout, and order APIs.",
"technology": "Python / FastAPI",
"properties": {
"properties": [
[
"Runtime",
"Python 3.12"
],
[
"Team",
"Platform"
]
]
}
},
{
"type": "ContainerDb",
"alias": "orders_db",
"label": "Orders Database",
"description": "Stores orders, payments, and status transitions.",
"technology": "PostgreSQL",
"properties": {
"properties": [
[
"Engine",
"PostgreSQL 16"
],
[
"HA",
"Primary / Replica"
]
]
}
},
{
"type": "ContainerQueue",
"alias": "order_events",
"label": "Order Events Queue",
"description": "Publishes asynchronous order lifecycle events.",
"technology": "Kafka",
"properties": {
"properties": [
[
"Retention",
"7 days"
],
[
"Format",
"JSON"
]
]
}
}
],
"boundaries": [
{
"type": "ContainerBoundary",
"alias": "checkout_boundary",
"label": "Checkout Subsystem",
"description": "Groups checkout-related containers.",
"properties": {
"properties": [
[
"Owner",
"Checkout Team"
],
[
"Criticality",
"High"
]
]
},
"elements": [
{
"type": "Container",
"alias": "checkout_api",
"label": "Checkout API",
"description": "Handles checkout and payment orchestration.",
"technology": "Python / FastAPI"
},
{
"type": "ContainerDb",
"alias": "checkout_db",
"label": "Checkout DB",
"description": "Stores checkout sessions.",
"technology": "PostgreSQL"
}
],
"relationships": [
{
"type": "REL",
"from": "checkout_api",
"to": "checkout_db",
"label": "Reads and writes",
"technology": "SQL"
}
]
}
]
}
]
}
],
"relationships": [
{
"type": "REL",
"from": "customer",
"to": "web_app",
"label": "Uses",
"technology": "HTTPS"
},
{
"type": "REL",
"from": "web_app",
"to": "backend_api",
"label": "Calls",
"technology": "HTTPS/JSON"
},
{
"type": "REL",
"from": "backend_api",
"to": "orders_db",
"label": "Reads and writes",
"technology": "SQL"
},
{
"type": "REL",
"from": "backend_api",
"to": "order_events",
"label": "Publishes order events",
"technology": "Kafka"
},
{
"type": "REL",
"from": "backend_api",
"to": "payment_provider",
"label": "Creates payment intents",
"technology": "REST API"
},
{
"type": "REL",
"from": "backend_api",
"to": "recommendation_api",
"label": "Fetches recommendations",
"technology": "REST API"
},
{
"type": "REL",
"from": "backend_api",
"to": "fraud_db",
"label": "Checks fraud signals",
"technology": "JDBC"
},
{
"type": "REL",
"from": "shipping_events",
"to": "backend_api",
"label": "Delivers shipping updates",
"technology": "Kafka"
},
{
"type": "REL",
"from": "support_agent",
"to": "backend_api",
"label": "Queries order state",
"technology": "HTTPS"
}
]
}
Rendered Mermaid source
C4Container
title Online Shop - Container Diagram
Person(customer, "Customer", "Browses products and places orders.")
Person_Ext(support_agent, "Support Agent", "Investigates customer issues from an external support tool.")
System_Ext(payment_provider, "Payment Provider", "Processes card payments and payment webhooks.")
Container_Ext(recommendation_api, "Recommendation API", $descr="Returns personalized product recommendations.")
ContainerDb_Ext(fraud_db, "Fraud Signals DB", "Vendor DB", "External datastore containing fraud intelligence.")
ContainerQueue_Ext(shipping_events, "Shipping Events Topic", "Kafka", "External topic used by logistics partner.")
Enterprise_Boundary(acme, "Acme Corp", "Enterprise boundary for internal platforms.") {
System_Boundary(shop_boundary, "Online Shop Platform", "Main system boundary for the commerce platform.") {
Container(web_app, "Web Application", "React + Next.js", "Serves the storefront and checkout UI.")
Container(backend_api, "Backend API", "Python / FastAPI", "Handles catalog, carts, checkout, and order APIs.")
ContainerDb(orders_db, "Orders Database", "PostgreSQL", "Stores orders, payments, and status transitions.")
ContainerQueue(order_events, "Order Events Queue", "Kafka", "Publishes asynchronous order lifecycle events.")
Container_Boundary(checkout_boundary, "Checkout Subsystem", "Groups checkout-related containers.") {
Container(checkout_api, "Checkout API", "Python / FastAPI", "Handles checkout and payment orchestration.")
ContainerDb(checkout_db, "Checkout DB", "PostgreSQL", "Stores checkout sessions.")
Rel(checkout_api, checkout_db, "Reads and writes", "SQL")
}
}
}
Rel(customer, web_app, "Uses", "HTTPS")
Rel(web_app, backend_api, "Calls", "HTTPS/JSON")
Rel(backend_api, orders_db, "Reads and writes", "SQL")
Rel(backend_api, order_events, "Publishes order events", "Kafka")
Rel(backend_api, payment_provider, "Creates payment intents", "REST API")
Rel(backend_api, recommendation_api, "Fetches recommendations", "REST API")
Rel(backend_api, fraud_db, "Checks fraud signals", "JDBC")
Rel(shipping_events, backend_api, "Delivers shipping updates", "Kafka")
Rel(support_agent, backend_api, "Queries order state", "HTTPS")
Rendered image
Elements¶
- PersonSchema
- PersonExtSchema
- SystemSchema
- SystemExtSchema
- SystemDbSchema
- SystemDbExtSchema
- SystemQueueSchema
- SystemQueueExtSchema
- ContainerSchema
- ContainerExtSchema
- ContainerDbSchema
- ContainerDbExtSchema
- ContainerQueueSchema
- ContainerQueueExtSchema
Boundaries¶
Relationships¶
Definitions¶
About labels and aliases
label is a display name for the element.
alias is a unique identifier used for referencing elements
in relationships and layouts.
If omitted, it is generated automatically.
You can also use label for referencing elements in relationships and layouts, but each label must be unique within the diagram.
RelationshipType¶
Relationship types supported by Mermaid C4 diagrams.
Items
| Type | Description |
|---|---|
BI_REL |
A bidirectional relationship between two elements. |
REL |
A unidirectional relationship between two elements. |
REL_BACK |
A unidirectional relationship pointing backward. |
REL_D |
A unidirectional downward relationship. Shorthand for REL_DOWN. |
REL_DOWN |
A unidirectional downward relationship. |
REL_L |
A unidirectional leftward relationship. Shorthand for REL_LEFT. |
REL_LEFT |
A unidirectional leftward relationship. |
REL_R |
A unidirectional rightward relationship. Shorthand for REL_RIGHT. |
REL_RIGHT |
A unidirectional rightward relationship. |
REL_U |
A unidirectional upward relationship. Shorthand for REL_UP. |
REL_UP |
A unidirectional upward relationship. |
BoundarySchema¶
This schema describes the
Boundary
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly Boundary. |
elements |
array[Element] |
Elements may be nested arbitrarily. |
boundaries |
array[Boundary] |
Boundaries may be nested arbitrarily. |
relationships |
array[RelationshipSchema] |
Relationships declared inside the boundary. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
ContainerBoundarySchema¶
This schema describes the
ContainerBoundary
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ContainerBoundary. |
elements |
array[Element] |
Elements may be nested arbitrarily. |
boundaries |
array[Boundary] |
Boundaries may be nested arbitrarily. |
relationships |
array[RelationshipSchema] |
Relationships declared inside the boundary. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
ContainerDbExtSchema¶
This schema describes the
ContainerDbExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ContainerDbExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
Optional technology. |
ContainerDbSchema¶
This schema describes the
ContainerDb
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ContainerDb. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
Optional technology. |
ContainerExtSchema¶
This schema describes the
ContainerExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ContainerExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
Optional technology. |
ContainerQueueExtSchema¶
This schema describes the
ContainerQueueExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ContainerQueueExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
Optional technology. |
ContainerQueueSchema¶
This schema describes the
ContainerQueue
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ContainerQueue. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
Optional technology. |
ContainerSchema¶
This schema describes the
Container
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly Container. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
Optional technology. |
DiagramElementPropertiesSchema¶
JSON schema for tabular diagram element properties.
Properties
| Field | Type | Description |
|---|---|---|
header |
array[string] |
Header columns. Default: ["Property", "Value"]. |
properties(required) |
array[array[string]] |
List of rows (each row is a list of string values). |
show_header |
boolean |
Whether to display the header row. Default: true. |
EnterpriseBoundarySchema¶
This schema describes the
EnterpriseBoundary
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly EnterpriseBoundary. |
elements |
array[Element] |
Elements may be nested arbitrarily. |
boundaries |
array[Boundary] |
Boundaries may be nested arbitrarily. |
relationships |
array[RelationshipSchema] |
Relationships declared inside the boundary. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
MermaidRelationshipSchema¶
JSON schema for relationships supported by Mermaid C4 diagrams.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
RelationshipType |
Type of the relationship. |
description |
string | null |
Additional details about the relationship. |
from(required) |
string |
The source element alias (or unique label). For Mermaid, this must resolve to a concrete element, not a boundary. |
label(required) |
string |
The label shown on the relationship edge. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
The technology used in the communication. |
to(required) |
string |
The destination element alias (or unique label). For Mermaid, this must resolve to a concrete element, not a boundary. |
PersonExtSchema¶
This schema describes the
PersonExt diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly PersonExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
PersonSchema¶
This schema describes the Person
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly Person. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
RelationshipSchema¶
This schema describes the Relationship
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Type of the relationship. Must be exactly REL. |
description |
string | null |
Additional details about the relationship. |
from(required) |
string |
The source element alias (or unique label). |
label(required) |
string |
The label shown on the relationship edge. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
technology |
string | null |
The technology used in the communication. |
to(required) |
string |
The destination element alias (or unique label). |
SystemBoundarySchema¶
This schema describes the
SystemBoundary
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly SystemBoundary. |
elements |
array[Element] |
Elements may be nested arbitrarily. |
boundaries |
array[Boundary] |
Boundaries may be nested arbitrarily. |
relationships |
array[RelationshipSchema] |
Relationships declared inside the boundary. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
SystemDbExtSchema¶
This schema describes the
SystemDbExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly SystemDbExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
SystemDbSchema¶
This schema describes the
SystemDb
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly SystemDb. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
SystemExtSchema¶
This schema describes the
SystemExt diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly SystemExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
SystemQueueExtSchema¶
This schema describes the
SystemQueueExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly SystemQueueExt. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
SystemQueueSchema¶
This schema describes the
SystemQueue
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly SystemQueue. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
SystemSchema¶
This schema describes the
System diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly System. |
alias |
string | null |
Unique identifier for the element. If not provided, it is autogenerated from the label. |
description |
string | null |
Optional description text. |
label(required) |
string |
Display name for the element. |
properties |
DiagramElementPropertiesSchema |
Optional property table metadata. |
Mermaid Render Options¶
MermaidRenderOptionsSchema¶
Final layout configuration for rendering a Mermaid C4 diagram.
Encapsulates layout directives, macros, tag definitions, and visual styles applied at render time.
Properties
| Field | Type | Description |
|---|---|---|
styles |
array[ |
List of style update macro configurations. |
update_layout_config |
UpdateLayoutConfigSchema |
Configuration for updating default layout behavior. |
MermaidElementStyleSchema¶
Style update for an individual diagram element.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ElementStyle. |
bg_color |
string | null |
Background color. |
border_color |
string | null |
Border line color. |
element(required) |
string |
Alias of the element to style. |
font_color |
string | null |
Font/text color. |
MermaidRelStyleSchema¶
Style update for relationship lines.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly RelStyle. |
from_element(required) |
string |
Alias of the source element to style. |
line_color |
string | null |
Color of the relationship line. |
offset_x |
integer | null |
Optional horizontal offset for the label position. |
offset_y |
integer | null |
Optional vertical offset for the label position. |
text_color |
string | null |
Color of the relationship label text. |
to_element(required) |
string |
Alias of the target element to style. |
UpdateLayoutConfigSchema¶
Configuration for updating default layout behavior in Mermaid C4 diagrams.
Properties
| Field | Type | Description |
|---|---|---|
c4_boundary_in_row |
integer | null |
Maximum number of boundaries per row. |
c4_shape_in_row |
integer | null |
Maximum number of non-boundary elements (e.g. systems, containers, components) per row. |