Mermaid ComponentDiagram Spec¶
Source: mermaid.component-diagram.json
This schema describes the ComponentDiagram spec for the Mermaid backend.
Properties¶
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Type of the diagram. Must be exactly ComponentDiagram. |
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": "ComponentDiagram",
"title": "Checkout API - Component Diagram",
"elements": [
{
"type": "Component",
"label": "Checkout Controller",
"alias": "checkout_controller",
"description": "Receives checkout requests and orchestrates payment flow.",
"technology": "FastAPI"
},
{
"type": "Component",
"label": "Payment Service",
"alias": "payment_service",
"description": "Creates payment intents and handles payment state updates.",
"technology": "Python"
},
{
"type": "ComponentDb",
"label": "Payment Store",
"alias": "payment_store",
"description": "Stores payment records and statuses.",
"technology": "PostgreSQL"
},
{
"type": "ComponentExt",
"label": "Payment Gateway API",
"alias": "payment_gateway_api",
"description": "External API for payment authorization and capture.",
"technology": "REST API"
}
],
"relationships": [
{
"type": "REL",
"from": "checkout_controller",
"to": "payment_service",
"label": "Calls",
"technology": "Python call"
},
{
"type": "REL",
"from": "payment_service",
"to": "payment_store",
"label": "Reads and writes",
"technology": "SQL"
},
{
"type": "REL",
"from": "payment_service",
"to": "payment_gateway_api",
"label": "Creates payments via",
"technology": "HTTPS/JSON"
}
]
}
Rendered Mermaid source
C4Component
title Checkout API - Component Diagram
Component(checkout_controller, "Checkout Controller", "FastAPI", "Receives checkout requests and orchestrates payment flow.")
Component(payment_service, "Payment Service", "Python", "Creates payment intents and handles payment state updates.")
ComponentDb(payment_store, "Payment Store", "PostgreSQL", "Stores payment records and statuses.")
Component_Ext(payment_gateway_api, "Payment Gateway API", "REST API", "External API for payment authorization and capture.")
Rel(checkout_controller, payment_service, "Calls", "Python call")
Rel(payment_service, payment_store, "Reads and writes", "SQL")
Rel(payment_service, payment_gateway_api, "Creates payments via", "HTTPS/JSON")
Rendered image
JSON source
{
"backend": "mermaid",
"type": "ComponentDiagram",
"title": "Order Processing API - Component Diagram",
"elements": [
{
"type": "Component",
"label": "Order Controller",
"alias": "order_controller",
"description": "HTTP entrypoint for order submission and status queries.",
"technology": "FastAPI"
},
{
"type": "Component",
"label": "Order Application Service",
"alias": "order_app_service",
"description": "Coordinates validation, payment, and order creation.",
"technology": "Python"
},
{
"type": "Component",
"label": "Inventory Checker",
"alias": "inventory_checker",
"description": "Verifies stock availability before an order is confirmed.",
"technology": "Python"
},
{
"type": "Component",
"label": "Payment Adapter",
"alias": "payment_adapter",
"description": "Wraps external payment provider calls.",
"technology": "Python"
},
{
"type": "ComponentDb",
"label": "Order Database",
"alias": "order_db",
"description": "Stores orders, line items, and order status history.",
"technology": "PostgreSQL"
},
{
"type": "ComponentExt",
"label": "Payment Gateway API",
"alias": "payment_gateway_api",
"description": "External provider API for payment authorization and capture.",
"technology": "REST API"
},
{
"type": "ComponentQueue",
"label": "Order Events Bus",
"alias": "order_events_bus",
"description": "Publishes order-created and order-paid events.",
"technology": "Kafka"
}
],
"relationships": [
{
"type": "REL",
"from": "order_controller",
"to": "order_app_service",
"label": "Invokes",
"technology": "Python call"
},
{
"type": "REL",
"from": "order_app_service",
"to": "inventory_checker",
"label": "Checks stock via",
"technology": "Python call"
},
{
"type": "REL",
"from": "order_app_service",
"to": "payment_adapter",
"label": "Requests payment through",
"technology": "Python call"
},
{
"type": "REL",
"from": "payment_adapter",
"to": "payment_gateway_api",
"label": "Authorizes payment via",
"technology": "HTTPS/JSON"
},
{
"type": "REL",
"from": "order_app_service",
"to": "order_db",
"label": "Reads and writes",
"technology": "SQL"
},
{
"type": "REL",
"from": "order_app_service",
"to": "order_events_bus",
"label": "Publishes events to",
"technology": "Kafka"
}
]
}
Rendered Mermaid source
C4Component
title Order Processing API - Component Diagram
Component(order_controller, "Order Controller", "FastAPI", "HTTP entrypoint for order submission and status queries.")
Component(order_app_service, "Order Application Service", "Python", "Coordinates validation, payment, and order creation.")
Component(inventory_checker, "Inventory Checker", "Python", "Verifies stock availability before an order is confirmed.")
Component(payment_adapter, "Payment Adapter", "Python", "Wraps external payment provider calls.")
ComponentDb(order_db, "Order Database", "PostgreSQL", "Stores orders, line items, and order status history.")
Component_Ext(payment_gateway_api, "Payment Gateway API", "REST API", "External provider API for payment authorization and capture.")
ComponentQueue(order_events_bus, "Order Events Bus", "Kafka", "Publishes order-created and order-paid events.")
Rel(order_controller, order_app_service, "Invokes", "Python call")
Rel(order_app_service, inventory_checker, "Checks stock via", "Python call")
Rel(order_app_service, payment_adapter, "Requests payment through", "Python call")
Rel(payment_adapter, payment_gateway_api, "Authorizes payment via", "HTTPS/JSON")
Rel(order_app_service, order_db, "Reads and writes", "SQL")
Rel(order_app_service, order_events_bus, "Publishes events to", "Kafka")
Rendered image
Elements¶
- PersonSchema
- PersonExtSchema
- SystemSchema
- SystemExtSchema
- SystemDbSchema
- SystemDbExtSchema
- SystemQueueSchema
- SystemQueueExtSchema
- ContainerSchema
- ContainerExtSchema
- ContainerDbSchema
- ContainerDbExtSchema
- ContainerQueueSchema
- ContainerQueueExtSchema
- ComponentSchema
- ComponentExtSchema
- ComponentDbSchema
- ComponentDbExtSchema
- ComponentQueueSchema
- ComponentQueueExtSchema
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. |
ComponentDbExtSchema¶
This schema describes the
ComponentDbExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ComponentDbExt. |
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. |
ComponentDbSchema¶
This schema describes the
ComponentDb
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ComponentDb. |
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. |
ComponentExtSchema¶
This schema describes the
ComponentExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ComponentExt. |
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. |
ComponentQueueExtSchema¶
This schema describes the
ComponentQueueExt
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ComponentQueueExt. |
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. |
ComponentQueueSchema¶
This schema describes the
ComponentQueue
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly ComponentQueue. |
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. |
ComponentSchema¶
This schema describes the
Component
diagram component.
Properties
| Field | Type | Description |
|---|---|---|
type(required) |
string |
Discriminator identifying the element type. Must be exactly Component. |
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. |
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. |