D2 Extensions¶

D2-specific metadata should be passed with the d2= constructor kwarg in Python code. The data is normalized into element.extensions["d2"] and is consumed only by the D2 renderer.

from c4 import Container, ContainerDiagram, Rel

with ContainerDiagram("Orders") as diagram:
    api = Container(
        "API",
        "Handles requests",
        "Python",
        d2={
            "shape": "hexagon",
            "tooltip": "Public HTTP API",
            "link": "https://example.com/api",
            "style": {"fill": "#edf7ff", "stroke": "#2d6f9f"},
        },
    )
    db = Container(
        "Database",
        "Stores orders",
        "PostgreSQL",
        d2={"shape": "cylinder"},
    )

    api >> Rel("Reads and writes", d2={"style": {"stroke_dash": 3}}) >> db

extensions={"d2": {...}} also works and normalizes to the same structure. Prefer d2={...} for new Python authoring, and keep extensions= for multi-backend payloads or advanced escape hatches.

Supported Fields¶

direction is useful on containers because D2 supports local layout direction inside container blocks.

These fields map to D2-native concepts:

• shape selects a D2 shape. See the upstream D2 shapes documentation.
• style emits nested D2 style.* attributes. See D2 styles.
• icon emits a D2 icon reference. See D2 icons.
• near emits a D2 positioning hint. See D2 positions.
• tooltip and link emit D2 interactive fields. See D2 interactive diagrams.
• classes emits D2 class references. See D2 classes.
• direction emits a local D2 direction for element-like containers. See D2 layouts.

Style Fields¶

The style mapping uses Python-friendly keys and renders D2 style attributes:

Unknown extension or style keys fail D2 validation by default.

Properties¶

Properties are portable C4 model data, not D2 extension data. Add them with the Properties API, then enable D2 property rendering with D2RenderOptions(include_properties=True).