Mermaid DeploymentDiagram Spec¶

Source: mermaid.deployment-diagram.json

This schema describes the DeploymentDiagram spec for the Mermaid backend.

Properties¶

Properties

Field	Type	Description
`type(required)`	`string`	Type of the diagram. Must be exactly `DeploymentDiagram`.
`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

MinimalAdvanced

JSON source

{
  "backend": "mermaid",
  "type": "DeploymentDiagram",
  "title": "Web App Deployment",
  "elements": [
    {
      "type": "Person",
      "alias": "user",
      "label": "User",
      "description": "Uses the web application."
    }
  ],
  "boundaries": [
    {
      "type": "DeploymentNode",
      "alias": "web_node",
      "label": "Web Server",
      "description": "Hosts the frontend application.",
      "elements": [
        {
          "type": "Container",
          "alias": "web_app",
          "label": "Web App",
          "description": "Customer-facing web application.",
          "technology": "Next.js"
        }
      ]
    },
    {
      "type": "DeploymentNode",
      "alias": "db_node",
      "label": "Database Server",
      "description": "Hosts the application database.",
      "elements": [
        {
          "type": "ContainerDb",
          "alias": "app_db",
          "label": "App Database",
          "description": "Stores application data.",
          "technology": "PostgreSQL"
        }
      ]
    }
  ],
  "relationships": [
    {
      "type": "REL",
      "from": "user",
      "to": "web_app",
      "label": "Uses",
      "technology": "HTTPS"
    },
    {
      "type": "REL",
      "from": "web_app",
      "to": "app_db",
      "label": "Reads and writes",
      "technology": "TLS / SQL"
    }
  ]
}

Rendered Mermaid source

C4Deployment
title Web App Deployment

Person(user, "User", "Uses the web application.")

Deployment_Node(web_node, "Web Server", "Hosts the frontend application.") {
    Container(web_app, "Web App", "Next.js", "Customer-facing web application.")
}

Deployment_Node(db_node, "Database Server", "Hosts the application database.") {
    ContainerDb(app_db, "App Database", "PostgreSQL", "Stores application data.")
}

Rel(user, web_app, "Uses", "HTTPS")

Rel(web_app, app_db, "Reads and writes", "TLS / SQL")

Rendered image

JSON source

{
  "backend": "mermaid",
  "type": "DeploymentDiagram",
  "title": "Online Shop - Production Deployment",
  "elements": [
    {
      "type": "Person",
      "alias": "customer",
      "label": "Customer",
      "description": "Uses the online shop through a browser."
    },
    {
      "type": "ContainerExt",
      "alias": "payment_gateway",
      "label": "Payment Gateway",
      "description": "External service that processes card payments.",
      "technology": "HTTPS API"
    }
  ],
  "boundaries": [
    {
      "type": "Node",
      "alias": "aws_prod",
      "label": "AWS Production Account",
      "description": "Production cloud account for the online shop.",
      "properties": {
        "properties": [
          [
            "Environment",
            "Production"
          ],
          [
            "Region",
            "eu-central-1"
          ]
        ]
      },
      "boundaries": [
        {
          "type": "Node",
          "alias": "public_subnet",
          "label": "Public Subnet",
          "description": "Internet-facing network segment.",
          "boundaries": [
            {
              "type": "DeploymentNode",
              "alias": "alb",
              "label": "Application Load Balancer",
              "description": "Terminates TLS and routes requests to the web tier.",
              "elements": [
                {
                  "type": "Container",
                  "alias": "web_app",
                  "label": "Web Application",
                  "description": "Serves the storefront UI.",
                  "technology": "Next.js"
                }
              ]
            }
          ]
        },
        {
          "type": "Node",
          "alias": "private_subnet",
          "label": "Private Subnet",
          "description": "Internal network segment for application and data services.",
          "boundaries": [
            {
              "type": "DeploymentNode",
              "alias": "app_cluster",
              "label": "Kubernetes Cluster",
              "description": "Runs backend services and asynchronous workers.",
              "properties": {
                "properties": [
                  [
                    "Platform",
                    "EKS"
                  ],
                  [
                    "Autoscaling",
                    "Enabled"
                  ]
                ]
              },
              "elements": [
                {
                  "type": "Container",
                  "alias": "backend_api",
                  "label": "Backend API",
                  "description": "Handles catalog, checkout, and order processing.",
                  "technology": "Python / FastAPI"
                },
                {
                  "type": "ContainerQueue",
                  "alias": "order_events",
                  "label": "Order Events",
                  "description": "Internal asynchronous event stream.",
                  "technology": "Kafka"
                }
              ]
            },
            {
              "type": "DeploymentNode",
              "alias": "db_service",
              "label": "Managed PostgreSQL",
              "description": "Managed relational database service.",
              "properties": {
                "properties": [
                  [
                    "Service",
                    "RDS"
                  ],
                  [
                    "Mode",
                    "Multi-AZ"
                  ]
                ]
              },
              "elements": [
                {
                  "type": "ContainerDb",
                  "alias": "orders_db",
                  "label": "Orders Database",
                  "description": "Stores orders, payments, and fulfillment data.",
                  "technology": "PostgreSQL"
                }
              ]
            }
          ]
        }
      ]
    }
  ],
  "relationships": [
    {
      "type": "REL",
      "from": "customer",
      "to": "web_app",
      "label": "Uses",
      "technology": "HTTPS"
    },
    {
      "type": "REL",
      "from": "web_app",
      "to": "backend_api",
      "label": "Routes traffic to",
      "technology": "HTTPS"
    },
    {
      "type": "REL",
      "from": "backend_api",
      "to": "orders_db",
      "label": "Reads and writes",
      "technology": "TLS / SQL"
    },
    {
      "type": "REL",
      "from": "backend_api",
      "to": "payment_gateway",
      "label": "Calls",
      "technology": "HTTPS/JSON"
    },
    {
      "type": "REL",
      "from": "backend_api",
      "to": "order_events",
      "label": "Publishes events to",
      "technology": "Kafka"
    }
  ]
}

Rendered Mermaid source

C4Deployment
title Online Shop - Production Deployment

Person(customer, "Customer", "Uses the online shop through a browser.")

Container_Ext(payment_gateway, "Payment Gateway", "HTTPS API", "External service that processes card payments.")

Node(aws_prod, "AWS Production Account", "Production cloud account for the online shop.") {
    Node(public_subnet, "Public Subnet", "Internet-facing network segment.") {
        Deployment_Node(alb, "Application Load Balancer", "Terminates TLS and routes requests to the web tier.") {
            Container(web_app, "Web Application", "Next.js", "Serves the storefront UI.")
        }
    }
    Node(private_subnet, "Private Subnet", "Internal network segment for application and data services.") {
        Deployment_Node(app_cluster, "Kubernetes Cluster", "Runs backend services and asynchronous workers.") {
            Container(backend_api, "Backend API", "Python / FastAPI", "Handles catalog, checkout, and order processing.")
            ContainerQueue(order_events, "Order Events", "Kafka", "Internal asynchronous event stream.")
        }
        Deployment_Node(db_service, "Managed PostgreSQL", "Managed relational database service.") {
            ContainerDb(orders_db, "Orders Database", "PostgreSQL", "Stores orders, payments, and fulfillment data.")
        }
    }
}

Rel(customer, web_app, "Uses", "HTTPS")

Rel(web_app, backend_api, "Routes traffic to", "HTTPS")

Rel(backend_api, orders_db, "Reads and writes", "TLS / SQL")

Rel(backend_api, payment_gateway, "Calls", "HTTPS/JSON")

Rel(backend_api, order_events, "Publishes events to", "Kafka")

Rendered image

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.

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.

DeploymentNodeSchema¶

This schema describes the DeploymentNode diagram component.

Properties

Field	Type	Description
`type(required)`	`string`	Discriminator identifying the element type. Must be exactly `DeploymentNode`.
`elements`	`array[Element]`	Top-level elements.
`boundaries`	`array[Boundary]`	Top-level boundaries.
`relationships`	`array[RelationshipSchema]`	Top-level relationships.
`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.

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`.

MermaidNodeLeftSchema¶

Mermaid JSON schema for a left-aligned deployment node.

Properties

Field	Type	Description
`type(required)`	`string`	Discriminator identifying the element type. Must be exactly `NodeLeft`.
`elements`	`array[Element]`	Top-level elements.
`boundaries`	`array[Boundary]`	Top-level boundaries.
`relationships`	`array[MermaidRelationshipSchema]`	Top-level relationships.
`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.

MermaidNodeRightSchema¶

Mermaid JSON schema for a right-aligned deployment node.

Properties

Field	Type	Description
`type(required)`	`string`	Discriminator identifying the element type. Must be exactly `NodeRight`.
`elements`	`array[Element]`	Top-level elements.
`boundaries`	`array[Boundary]`	Top-level boundaries.
`relationships`	`array[MermaidRelationshipSchema]`	Top-level relationships.
`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.

NodeSchema¶

This schema describes the Node diagram component.

Properties

Field	Type	Description
`type(required)`	`string`	Discriminator identifying the element type. Must be exactly `Node`.
`elements`	`array[Element]`	Top-level elements.
`boundaries`	`array[Boundary]`	Top-level boundaries.
`relationships`	`array[RelationshipSchema]`	Top-level relationships.
`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.

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).

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.

Mermaid DeploymentDiagram Spec¶

Properties¶

Elements¶

Boundaries¶

Relationships¶

Definitions¶

RelationshipType¶

ContainerDbExtSchema¶

ContainerDbSchema¶

ContainerExtSchema¶

ContainerQueueExtSchema¶

ContainerQueueSchema¶

ContainerSchema¶

DeploymentNodeSchema¶

DiagramElementPropertiesSchema¶

MermaidNodeLeftSchema¶

MermaidNodeRightSchema¶

MermaidRelationshipSchema¶

NodeSchema¶

PersonExtSchema¶

PersonSchema¶

RelationshipSchema¶

SystemDbExtSchema¶

SystemDbSchema¶

SystemExtSchema¶

SystemQueueExtSchema¶

SystemQueueSchema¶

SystemSchema¶

Mermaid Render Options¶

MermaidRenderOptionsSchema¶

MermaidElementStyleSchema¶

MermaidRelStyleSchema¶

UpdateLayoutConfigSchema¶