@aravindc26/velu 0.11.0 → 0.11.3

package/schema/velu.schema.json

@@ -4,7 +4,9 @@
   "title": "Velu Configuration",
   "description": "Configuration schema for velu.json — the core config file for Velu documentation sites.",
   "type": "object",
-  "required": ["navigation"],
+  "required": [
+    "navigation"
+  ],
   "properties": {
     "$schema": {
       "type": "string",
@@ -13,9 +15,43 @@
     "theme": {
       "type": "string",
       "description": "Named theme preset that controls the overall look and feel. Supports Fumadocs presets and legacy Velu aliases.",
-      "enum": ["neutral", "black", "vitepress", "dusk", "catppuccin", "ocean", "emerald", "ruby", "purple", "solar", "aspen", "violet", "maple", "palm", "willow", "linden", "almond"],
+      "enum": [
+        "neutral",
+        "black",
+        "vitepress",
+        "dusk",
+        "catppuccin",
+        "ocean",
+        "emerald",
+        "ruby",
+        "purple",
+        "solar",
+        "aspen",
+        "violet",
+        "maple",
+        "palm",
+        "willow",
+        "linden",
+        "almond"
+      ],
       "default": "neutral"
     },
+    "name": {
+      "type": "string",
+      "description": "Site name shown in metadata and brand text."
+    },
+    "title": {
+      "type": "string",
+      "description": "Legacy alias for site name. Used when `name` is not provided."
+    },
+    "favicon": {
+      "$ref": "#/definitions/themeAsset",
+      "description": "Favicon path or light/dark favicon object."
+    },
+    "logo": {
+      "$ref": "#/definitions/logoAsset",
+      "description": "Brand logo path or light/dark logo object."
+    },
     "colors": {
       "type": "object",
       "description": "Override the theme's accent colors.",
@@ -41,9 +77,33 @@
     "appearance": {
       "type": "string",
       "description": "Controls light/dark mode behavior.",
-      "enum": ["system", "light", "dark"],
+      "enum": [
+        "system",
+        "light",
+        "dark"
+      ],
       "default": "system"
     },
+    "icons": {
+      "type": "object",
+      "description": "Icon settings compatible with Mint-style configuration.",
+      "properties": {
+        "library": {
+          "type": "string",
+          "description": "Icon library used for named icon strings.",
+          "enum": [
+            "fontawesome",
+            "lucide",
+            "tabler"
+          ],
+          "default": "fontawesome"
+        }
+      },
+      "required": [
+        "library"
+      ],
+      "additionalProperties": false
+    },
     "styling": {
       "type": "object",
       "description": "Fine-grained styling options.",
@@ -55,14 +115,23 @@
             "theme": {
               "description": "Shiki theme for syntax highlighting. Use a string for a single theme, or an object with light/dark keys.",
               "oneOf": [
-                { "type": "string" },
+                {
+                  "type": "string"
+                },
                 {
                   "type": "object",
                   "properties": {
-                    "light": { "type": "string" },
-                    "dark": { "type": "string" }
+                    "light": {
+                      "type": "string"
+                    },
+                    "dark": {
+                      "type": "string"
+                    }
                   },
-                  "required": ["light", "dark"],
+                  "required": [
+                    "light",
+                    "dark"
+                  ],
                   "additionalProperties": false
                 }
               ]
@@ -82,10 +151,143 @@
       },
       "minItems": 1
     },
+    "openapi": {
+      "$ref": "#/definitions/openapiSource",
+      "description": "Default OpenAPI source used by API pages."
+    },
+    "api": {
+      "type": "object",
+      "description": "API playground and MDX endpoint settings.",
+      "properties": {
+        "baseUrl": {
+          "type": "string",
+          "description": "Base API URL used by generated examples."
+        },
+        "playground": {
+          "type": "object",
+          "description": "Global playground display settings.",
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "show",
+                "hide",
+                "none"
+              ]
+            },
+            "display": {
+              "type": "string",
+              "enum": [
+                "interactive",
+                "simple",
+                "none",
+                "auth"
+              ]
+            },
+            "proxy": {
+              "type": "boolean",
+              "description": "Whether to send playground requests through the proxy endpoint. Defaults to true.",
+              "default": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "examples": {
+          "type": "object",
+          "description": "Autogenerated API code sample settings.",
+          "properties": {
+            "languages": {
+              "type": "array",
+              "description": "Enabled API example languages.",
+              "items": {
+                "type": "string"
+              },
+              "minItems": 1
+            },
+            "defaults": {
+              "type": "string",
+              "enum": [
+                "required",
+                "all"
+              ],
+              "description": "Whether examples should prioritize required-only or all parameters."
+            },
+            "prefill": {
+              "type": "boolean",
+              "description": "Whether to prefill playground fields from schema examples.",
+              "default": false
+            },
+            "autogenerate": {
+              "type": "boolean",
+              "description": "Whether to autogenerate API code samples from OpenAPI operations.",
+              "default": true
+            }
+          },
+          "additionalProperties": true
+        },
+        "mdx": {
+          "type": "object",
+          "description": "Defaults for manually-authored MDX API endpoint pages.",
+          "properties": {
+            "server": {
+              "description": "Server URL prepended to relative `api` frontmatter paths. Supports one server URL or multiple server URLs.",
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "minItems": 1
+                }
+              ]
+            },
+            "auth": {
+              "type": "object",
+              "properties": {
+                "method": {
+                  "type": "string",
+                  "enum": [
+                    "bearer",
+                    "basic",
+                    "key",
+                    "none"
+                  ]
+                },
+                "name": {
+                  "type": "string",
+                  "description": "Header name when `method` is `key`."
+                }
+              },
+              "additionalProperties": false
+            }
+          },
+          "additionalProperties": true
+        }
+      },
+      "additionalProperties": true
+    },
+    "seo": {
+      "$ref": "#/definitions/seoConfig",
+      "description": "SEO configuration for metadata and indexing behavior."
+    },
+    "redirects": {
+      "type": "array",
+      "description": "Permanent or temporary redirects for moved pages.",
+      "items": {
+        "$ref": "#/definitions/redirect"
+      }
+    },
     "navigation": {
       "type": "object",
       "description": "Defines the site navigation hierarchy. Use 'tabs' for single-language sites, or 'languages' for per-language navigation (like Mintlify).",
       "properties": {
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by tabs/groups/pages in this navigation section."
+        },
         "tabs": {
           "type": "array",
           "description": "Top-level navigation tabs (single-language mode). Ignored when 'languages' is present.",
@@ -115,9 +317,15 @@
           "description": "Top-level pages when tabs/dropdowns are not used.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           },
           "minItems": 1
@@ -173,23 +381,180 @@
             }
           },
           "additionalProperties": false
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by tabs/groups/pages in this navigation section."
         }
       },
       "anyOf": [
-        { "required": ["tabs"] },
-        { "required": ["dropdowns"] },
-        { "required": ["groups"] },
-        { "required": ["pages"] },
-        { "required": ["languages"] },
-        { "required": ["products"] },
-        { "required": ["versions"] },
-        { "required": ["anchors"] }
+        {
+          "required": [
+            "tabs"
+          ]
+        },
+        {
+          "required": [
+            "dropdowns"
+          ]
+        },
+        {
+          "required": [
+            "groups"
+          ]
+        },
+        {
+          "required": [
+            "pages"
+          ]
+        },
+        {
+          "required": [
+            "languages"
+          ]
+        },
+        {
+          "required": [
+            "products"
+          ]
+        },
+        {
+          "required": [
+            "versions"
+          ]
+        },
+        {
+          "required": [
+            "anchors"
+          ]
+        }
       ],
       "additionalProperties": false
+    },
+    "asyncapi": {
+      "$ref": "#/definitions/openapiSource",
+      "description": "Default AsyncAPI source used by API pages."
     }
   },
   "additionalProperties": false,
   "definitions": {
+    "themeAsset": {
+      "description": "Theme-aware asset path. Supports a string or an object with light/dark variants.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "light": {
+              "type": "string"
+            },
+            "dark": {
+              "type": "string"
+            },
+            "default": {
+              "type": "string",
+              "description": "Fallback used when a mode-specific value is not provided."
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "logoAsset": {
+      "description": "Logo asset config. Same as themeAsset, with optional logo link target.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "light": {
+              "type": "string"
+            },
+            "dark": {
+              "type": "string"
+            },
+            "default": {
+              "type": "string",
+              "description": "Fallback used when a mode-specific value is not provided."
+            },
+            "href": {
+              "$ref": "#/definitions/href",
+              "description": "Optional link target when clicking the logo."
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "seoConfig": {
+      "type": "object",
+      "description": "SEO settings including global metatags and indexing policy.",
+      "properties": {
+        "metatags": {
+          "type": "object",
+          "description": "Global metatags applied to page metadata. Keys are tag names (for example 'og:title' or 'twitter:card').",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "indexing": {
+          "type": "string",
+          "description": "Controls which pages are included in generated indexing outputs like sitemap and llms files.",
+          "enum": [
+            "navigable",
+            "all"
+          ],
+          "default": "navigable"
+        }
+      },
+      "additionalProperties": false
+    },
+    "openapiSource": {
+      "description": "OpenAPI source value. Supports a spec URL/path, a list of sources, or an object form.",
+      "oneOf": [
+        {
+          "type": "string"
+        },
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "minItems": 1
+        },
+        {
+          "type": "object",
+          "required": [
+            "source"
+          ],
+          "properties": {
+            "source": {
+              "oneOf": [
+                {
+                  "type": "string"
+                },
+                {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  },
+                  "minItems": 1
+                }
+              ]
+            },
+            "directory": {
+              "type": "string",
+              "description": "Optional directory for generated OpenAPI pages."
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
     "page": {
       "type": "string",
       "description": "Explicit markdown file path relative to the docs directory (without .md extension). No automatic language fallback is applied. Example: 'quickstart' → docs/quickstart.md, 'ja/quickstart' → docs/ja/quickstart.md, 'writing-content/page' → docs/writing-content/page.md."
@@ -209,10 +574,45 @@
         }
       ]
     },
+    "redirect": {
+      "type": "object",
+      "description": "Redirect rule for moved, renamed, or deleted pages.",
+      "required": [
+        "source",
+        "destination"
+      ],
+      "properties": {
+        "source": {
+          "type": "string",
+          "description": "Source path to match. Query params and anchors are not supported.",
+          "pattern": "^/[^?#]*$"
+        },
+        "destination": {
+          "type": "string",
+          "description": "Destination path or absolute URL. Query params and anchors are not supported.",
+          "anyOf": [
+            {
+              "format": "uri"
+            },
+            {
+              "pattern": "^/[^?#]*$"
+            }
+          ]
+        },
+        "permanent": {
+          "type": "boolean",
+          "description": "Whether to use a permanent redirect status. Defaults to true.",
+          "default": true
+        }
+      },
+      "additionalProperties": false
+    },
     "group": {
       "type": "object",
       "description": "A group of pages, optionally nested.",
-      "required": ["group", "pages"],
+      "required": [
+        "group"
+      ],
       "properties": {
         "group": {
           "type": "string",
@@ -227,6 +627,10 @@
           "type": "string",
           "description": "Icon identifier for the group."
         },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        },
         "tag": {
           "type": "string",
           "description": "Optional badge/tag label displayed next to the group name."
@@ -245,30 +649,69 @@
           "description": "Whether the group is hidden from navigation. Defaults to false.",
           "default": false
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by page entries in this group."
+        },
         "pages": {
           "type": "array",
           "description": "Pages, nested groups, separators, or external links within this group.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/group" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/group"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by page entries in this group."
         }
       },
+      "anyOf": [
+        {
+          "required": [
+            "pages"
+          ]
+        },
+        {
+          "required": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
+      ],
       "additionalProperties": false
     },
     "tab": {
       "type": "object",
       "description": "A top-level navigation tab.",
-      "required": ["tab"],
+      "required": [
+        "tab"
+      ],
       "properties": {
         "tab": {
           "type": "string",
           "description": "Display name for the tab."
         },
+        "version": {
+          "type": "string",
+          "description": "Optional version label inherited by generated OpenAPI operation pages under this tab."
+        },
         "slug": {
           "type": "string",
           "description": "Optional URL slug prefix for pages in this tab. If omitted, Velu derives one from the tab label.",
@@ -278,17 +721,31 @@
           "type": "string",
           "description": "Icon identifier for the tab."
         },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        },
         "href": {
           "$ref": "#/definitions/href"
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by groups/pages in this tab."
+        },
         "pages": {
           "type": "array",
           "description": "Standalone pages, separators, or external links directly under this tab.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -319,30 +776,127 @@
           "items": {
             "$ref": "#/definitions/dropdown"
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by groups/pages in this tab."
         }
       },
       "additionalProperties": false,
+      "allOf": [
+        {
+          "not": {
+            "allOf": [
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "required": [
+                      "groups"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "pages"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "anchors"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "dropdowns"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "oneOf": [
         {
-          "required": ["href"],
+          "required": [
+            "href"
+          ],
           "not": {
             "anyOf": [
-              { "required": ["pages"] },
-              { "required": ["groups"] },
-              { "required": ["menu"] },
-              { "required": ["anchors"] },
-              { "required": ["dropdowns"] }
+              {
+                "required": [
+                  "pages"
+                ]
+              },
+              {
+                "required": [
+                  "groups"
+                ]
+              },
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "required": [
+                  "anchors"
+                ]
+              },
+              {
+                "required": [
+                  "dropdowns"
+                ]
+              }
             ]
           }
         },
         {
-          "not": { "required": ["href"] },
+          "not": {
+            "required": [
+              "href"
+            ]
+          },
           "anyOf": [
-            { "required": ["pages"] },
-            { "required": ["groups"] },
-            { "required": ["menu"] },
-            { "required": ["anchors"] },
-            { "required": ["dropdowns"] }
+            {
+              "required": [
+                "pages"
+              ]
+            },
+            {
+              "required": [
+                "groups"
+              ]
+            },
+            {
+              "required": [
+                "menu"
+              ]
+            },
+            {
+              "required": [
+                "anchors"
+              ]
+            },
+            {
+              "required": [
+                "dropdowns"
+              ]
+            },
+            {
+              "required": [
+                "openapi"
+              ]
+            },
+            {
+              "required": [
+                "asyncapi"
+              ]
+            }
           ]
         }
       ]
@@ -350,7 +904,9 @@
     "dropdown": {
       "type": "object",
       "description": "A dropdown navigation container.",
-      "required": ["dropdown"],
+      "required": [
+        "dropdown"
+      ],
       "properties": {
         "dropdown": {
           "type": "string",
@@ -365,17 +921,31 @@
           "type": "string",
           "description": "Icon identifier for the dropdown."
         },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        },
         "href": {
           "$ref": "#/definitions/href"
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by groups/pages in this dropdown."
+        },
         "pages": {
           "type": "array",
           "description": "Pages directly under this dropdown.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -399,28 +969,112 @@
           "items": {
             "$ref": "#/definitions/anchor"
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by groups/pages in this dropdown."
         }
       },
       "additionalProperties": false,
+      "allOf": [
+        {
+          "not": {
+            "allOf": [
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "required": [
+                      "groups"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "pages"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "anchors"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "oneOf": [
         {
-          "required": ["href"],
+          "required": [
+            "href"
+          ],
           "not": {
             "anyOf": [
-              { "required": ["pages"] },
-              { "required": ["groups"] },
-              { "required": ["menu"] },
-              { "required": ["anchors"] }
+              {
+                "required": [
+                  "pages"
+                ]
+              },
+              {
+                "required": [
+                  "groups"
+                ]
+              },
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "required": [
+                  "anchors"
+                ]
+              }
             ]
           }
         },
         {
-          "not": { "required": ["href"] },
+          "not": {
+            "required": [
+              "href"
+            ]
+          },
           "anyOf": [
-            { "required": ["pages"] },
-            { "required": ["groups"] },
-            { "required": ["menu"] },
-            { "required": ["anchors"] }
+            {
+              "required": [
+                "pages"
+              ]
+            },
+            {
+              "required": [
+                "groups"
+              ]
+            },
+            {
+              "required": [
+                "menu"
+              ]
+            },
+            {
+              "required": [
+                "anchors"
+              ]
+            },
+            {
+              "required": [
+                "openapi"
+              ]
+            },
+            {
+              "required": [
+                "asyncapi"
+              ]
+            }
           ]
         }
       ]
@@ -428,7 +1082,9 @@
     "menuItem": {
       "type": "object",
       "description": "A named menu item within a tab. Normalized into a sidebar group.",
-      "required": ["item"],
+      "required": [
+        "item"
+      ],
       "properties": {
         "item": {
           "type": "string",
@@ -438,14 +1094,28 @@
           "type": "string",
           "description": "Icon identifier for the menu item."
         },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by groups/pages in this menu item."
+        },
         "pages": {
           "type": "array",
           "description": "Pages directly under this menu item.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -455,18 +1125,42 @@
           "items": {
             "$ref": "#/definitions/group"
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by groups/pages in this menu item."
         }
       },
       "additionalProperties": false,
       "anyOf": [
-        { "required": ["pages"] },
-        { "required": ["groups"] }
+        {
+          "required": [
+            "pages"
+          ]
+        },
+        {
+          "required": [
+            "groups"
+          ]
+        },
+        {
+          "required": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
       ]
     },
     "separator": {
       "type": "object",
       "description": "A visual separator/label in the sidebar navigation.",
-      "required": ["separator"],
+      "required": [
+        "separator"
+      ],
       "properties": {
         "separator": {
           "type": "string",
@@ -478,7 +1172,10 @@
     "link": {
       "type": "object",
       "description": "An external link displayed in the sidebar.",
-      "required": ["href", "label"],
+      "required": [
+        "href",
+        "label"
+      ],
       "properties": {
         "href": {
           "$ref": "#/definitions/href"
@@ -490,6 +1187,10 @@
         "icon": {
           "type": "string",
           "description": "Icon identifier for the link."
+        },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
         }
       },
       "additionalProperties": false
@@ -497,15 +1198,25 @@
     "anchor": {
       "type": "object",
       "description": "A prominent navigation anchor. Can be an external link or a container of tabs.",
-      "required": ["anchor"],
+      "required": [
+        "anchor"
+      ],
       "properties": {
         "anchor": {
           "type": "string",
           "description": "Display name for the anchor."
         },
+        "version": {
+          "type": "string",
+          "description": "Optional version label inherited by generated OpenAPI operation pages under this anchor."
+        },
         "href": {
           "$ref": "#/definitions/href"
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by tabs/groups/pages in this anchor."
+        },
         "tabs": {
           "type": "array",
           "description": "Optional tabs promoted to top-level navigation under this anchor.",
@@ -525,9 +1236,15 @@
           "description": "Pages nested under this anchor.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -556,6 +1273,10 @@
           "type": "string",
           "description": "Icon identifier for the anchor."
         },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        },
         "color": {
           "type": "object",
           "description": "Optional light/dark color hints for displaying this anchor.",
@@ -571,38 +1292,151 @@
               "pattern": "^#[0-9a-fA-F]{6}$"
             }
           },
-          "required": ["light", "dark"],
+          "required": [
+            "light",
+            "dark"
+          ],
           "additionalProperties": false
         },
         "hidden": {
           "type": "boolean",
           "description": "Whether the anchor is hidden. Defaults to false.",
           "default": false
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by tabs/groups/pages in this anchor."
         }
       },
+      "allOf": [
+        {
+          "not": {
+            "allOf": [
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "required": [
+                      "tabs"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "groups"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "pages"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "anchors"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "dropdowns"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "oneOf": [
         {
-          "required": ["href"],
+          "required": [
+            "href"
+          ],
           "not": {
             "anyOf": [
-              { "required": ["tabs"] },
-              { "required": ["groups"] },
-              { "required": ["pages"] },
-              { "required": ["menu"] },
-              { "required": ["anchors"] },
-              { "required": ["dropdowns"] }
+              {
+                "required": [
+                  "tabs"
+                ]
+              },
+              {
+                "required": [
+                  "groups"
+                ]
+              },
+              {
+                "required": [
+                  "pages"
+                ]
+              },
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "required": [
+                  "anchors"
+                ]
+              },
+              {
+                "required": [
+                  "dropdowns"
+                ]
+              }
             ]
           }
         },
         {
-          "not": { "required": ["href"] },
+          "not": {
+            "required": [
+              "href"
+            ]
+          },
           "anyOf": [
-            { "required": ["tabs"] },
-            { "required": ["groups"] },
-            { "required": ["pages"] },
-            { "required": ["menu"] },
-            { "required": ["anchors"] },
-            { "required": ["dropdowns"] }
+            {
+              "required": [
+                "tabs"
+              ]
+            },
+            {
+              "required": [
+                "groups"
+              ]
+            },
+            {
+              "required": [
+                "pages"
+              ]
+            },
+            {
+              "required": [
+                "menu"
+              ]
+            },
+            {
+              "required": [
+                "anchors"
+              ]
+            },
+            {
+              "required": [
+                "dropdowns"
+              ]
+            },
+            {
+              "required": [
+                "openapi"
+              ]
+            },
+            {
+              "required": [
+                "asyncapi"
+              ]
+            }
           ]
         }
       ],
@@ -611,7 +1445,9 @@
     "productNav": {
       "type": "object",
       "description": "Navigation definition for a product docs area.",
-      "required": ["product"],
+      "required": [
+        "product"
+      ],
       "properties": {
         "product": {
           "type": "string",
@@ -621,6 +1457,10 @@
           "type": "string",
           "description": "Icon identifier for the product."
         },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        },
         "name": {
           "type": "string",
           "description": "Optional display name for the product."
@@ -652,9 +1492,16 @@
               "pattern": "^#[0-9a-fA-F]{6}$"
             }
           },
-          "required": ["light", "dark"],
+          "required": [
+            "light",
+            "dark"
+          ],
           "additionalProperties": false
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by tabs/groups/pages in this product."
+        },
         "tabs": {
           "type": "array",
           "description": "Tabs within this product.",
@@ -681,9 +1528,15 @@
           "description": "Pages directly under this product when tabs are not needed.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -700,23 +1553,109 @@
           "items": {
             "$ref": "#/definitions/anchor"
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by tabs/groups/pages in this product."
         }
       },
       "additionalProperties": false,
+      "allOf": [
+        {
+          "not": {
+            "allOf": [
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "required": [
+                      "tabs"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "dropdowns"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "groups"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "pages"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "anchors"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "anyOf": [
-        { "required": ["href"] },
-        { "required": ["tabs"] },
-        { "required": ["dropdowns"] },
-        { "required": ["groups"] },
-        { "required": ["pages"] },
-        { "required": ["menu"] },
-        { "required": ["anchors"] }
+        {
+          "required": [
+            "href"
+          ]
+        },
+        {
+          "required": [
+            "tabs"
+          ]
+        },
+        {
+          "required": [
+            "dropdowns"
+          ]
+        },
+        {
+          "required": [
+            "groups"
+          ]
+        },
+        {
+          "required": [
+            "pages"
+          ]
+        },
+        {
+          "required": [
+            "menu"
+          ]
+        },
+        {
+          "required": [
+            "anchors"
+          ]
+        },
+        {
+          "required": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
       ]
     },
     "versionNav": {
       "type": "object",
       "description": "Navigation definition for a specific docs version.",
-      "required": ["version"],
+      "required": [
+        "version"
+      ],
       "properties": {
         "version": {
           "type": "string",
@@ -735,6 +1674,10 @@
         "href": {
           "$ref": "#/definitions/href"
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by tabs/groups/pages in this version."
+        },
         "tabs": {
           "type": "array",
           "description": "Tabs for this version.",
@@ -761,9 +1704,15 @@
           "description": "Pages for this version.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -780,23 +1729,110 @@
           "items": {
             "$ref": "#/definitions/anchor"
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by tabs/groups/pages in this version."
         }
       },
+      "allOf": [
+        {
+          "not": {
+            "allOf": [
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "required": [
+                      "tabs"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "dropdowns"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "groups"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "pages"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "anchors"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "anyOf": [
-        { "required": ["href"] },
-        { "required": ["tabs"] },
-        { "required": ["dropdowns"] },
-        { "required": ["groups"] },
-        { "required": ["pages"] },
-        { "required": ["menu"] },
-        { "required": ["anchors"] }
+        {
+          "required": [
+            "href"
+          ]
+        },
+        {
+          "required": [
+            "tabs"
+          ]
+        },
+        {
+          "required": [
+            "dropdowns"
+          ]
+        },
+        {
+          "required": [
+            "groups"
+          ]
+        },
+        {
+          "required": [
+            "pages"
+          ]
+        },
+        {
+          "required": [
+            "menu"
+          ]
+        },
+        {
+          "required": [
+            "anchors"
+          ]
+        },
+        {
+          "required": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
       ],
       "additionalProperties": false
     },
     "globalTab": {
       "type": "object",
       "description": "Global external tab shown in the navbar across all pages.",
-      "required": ["tab", "href"],
+      "required": [
+        "tab",
+        "href"
+      ],
       "properties": {
         "tab": {
           "type": "string",
@@ -808,6 +1844,10 @@
         "icon": {
           "type": "string",
           "description": "Icon identifier for the global tab."
+        },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
         }
       },
       "additionalProperties": false
@@ -815,7 +1855,9 @@
     "languageNav": {
       "type": "object",
       "description": "Per-language navigation entry. Defines the full tab/group/page structure for one language.",
-      "required": ["language"],
+      "required": [
+        "language"
+      ],
       "properties": {
         "language": {
           "type": "string",
@@ -834,6 +1876,10 @@
         "href": {
           "$ref": "#/definitions/href"
         },
+        "openapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default OpenAPI source inherited by tabs/groups/pages in this language entry."
+        },
         "tabs": {
           "type": "array",
           "description": "Navigation tabs for this language.",
@@ -860,9 +1906,15 @@
           "description": "Pages for this language.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/separator" },
-              { "$ref": "#/definitions/link" }
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
             ]
           }
         },
@@ -879,16 +1931,100 @@
           "items": {
             "$ref": "#/definitions/anchor"
           }
+        },
+        "asyncapi": {
+          "$ref": "#/definitions/openapiSource",
+          "description": "Default AsyncAPI source inherited by tabs/groups/pages in this language entry."
         }
       },
+      "allOf": [
+        {
+          "not": {
+            "allOf": [
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "anyOf": [
+                  {
+                    "required": [
+                      "tabs"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "dropdowns"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "groups"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "pages"
+                    ]
+                  },
+                  {
+                    "required": [
+                      "anchors"
+                    ]
+                  }
+                ]
+              }
+            ]
+          }
+        }
+      ],
       "anyOf": [
-        { "required": ["href"] },
-        { "required": ["tabs"] },
-        { "required": ["dropdowns"] },
-        { "required": ["groups"] },
-        { "required": ["pages"] },
-        { "required": ["menu"] },
-        { "required": ["anchors"] }
+        {
+          "required": [
+            "href"
+          ]
+        },
+        {
+          "required": [
+            "tabs"
+          ]
+        },
+        {
+          "required": [
+            "dropdowns"
+          ]
+        },
+        {
+          "required": [
+            "groups"
+          ]
+        },
+        {
+          "required": [
+            "pages"
+          ]
+        },
+        {
+          "required": [
+            "menu"
+          ]
+        },
+        {
+          "required": [
+            "anchors"
+          ]
+        },
+        {
+          "required": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
       ],
       "additionalProperties": false
     }