diff --git a/schema.json b/schema.json
index dd645e15..2c1f7cb1 100644
--- a/schema.json
+++ b/schema.json
@@ -287,6 +287,16 @@
             }
           ],
           "default": null,
+          "description": "Additional header connections you define yourself. Each item has a `placeholder` (the displayed text), an optional `url`, and the Font Awesome icon name to render (from https://fontawesome.com/search).",
+          "examples": [
+            [
+              {
+                "fontawesome_icon": "calendar-days",
+                "placeholder": "Book a call",
+                "url": "https://cal.com/johndoe"
+              }
+            ]
+          ],
           "title": "Custom Connections"
         },
         "sections": {
diff --git a/src/rendercv/schema/models/cv/cv.py b/src/rendercv/schema/models/cv/cv.py
index 7e729f9c..3c9e7d27 100644
--- a/src/rendercv/schema/models/cv/cv.py
+++ b/src/rendercv/schema/models/cv/cv.py
@@ -74,6 +74,20 @@ class Cv(BaseModelWithExtraKeys):
     )
     custom_connections: list[CustomConnection] | None = pydantic.Field(
         default=None,
+        description=(
+            "Additional header connections you define yourself. Each item has a"
+            " `placeholder` (the displayed text), an optional `url`, and the Font"
+            " Awesome icon name to render (from https://fontawesome.com/search)."
+        ),
+        examples=[
+            [
+                {
+                    "placeholder": "Book a call",
+                    "url": "https://cal.com/johndoe",
+                    "fontawesome_icon": "calendar-days",
+                }
+            ],
+        ],
     )
     sections: dict[str, Section] | None = pydantic.Field(
         default=None,