Skip to content

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

ContainerDiagram minimal example

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

ContainerDiagram advanced example

Elements

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[MermaidElementStyleSchema|MermaidRelStyleSchema] 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.