@aravindc26/velu 0.10.0 → 0.11.1

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
                 }
               ]
@@ -73,33 +142,477 @@
       },
       "additionalProperties": false
     },
+    "languages": {
+      "type": "array",
+      "description": "Supported language codes (e.g. [\"en\", \"es\", \"ja\"]). The first is the default. Display labels are auto-derived.",
+      "items": {
+        "type": "string",
+        "description": "BCP 47 language code (e.g. en, es, fr, ja, zh)."
+      },
+      "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: tabs → groups → pages. Groups must belong to a tab.",
-      "required": ["tabs"],
+      "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. Each tab contains groups and/or pages.",
+          "description": "Top-level navigation tabs (single-language mode). Ignored when 'languages' is present.",
           "items": {
             "$ref": "#/definitions/tab"
           },
           "minItems": 1
+        },
+        "dropdowns": {
+          "type": "array",
+          "description": "Top-level dropdown containers. Each dropdown can include groups, pages, anchors, or links.",
+          "items": {
+            "$ref": "#/definitions/dropdown"
+          },
+          "minItems": 1
+        },
+        "groups": {
+          "type": "array",
+          "description": "Top-level sidebar groups when tabs/dropdowns are not used.",
+          "items": {
+            "$ref": "#/definitions/group"
+          },
+          "minItems": 1
+        },
+        "pages": {
+          "type": "array",
+          "description": "Top-level pages when tabs/dropdowns are not used.",
+          "items": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
+            ]
+          },
+          "minItems": 1
+        },
+        "languages": {
+          "type": "array",
+          "description": "Per-language navigation. Each entry defines tabs/groups/pages for one language. First entry is the default language (no URL prefix).",
+          "items": {
+            "$ref": "#/definitions/languageNav"
+          },
+          "minItems": 1
+        },
+        "products": {
+          "type": "array",
+          "description": "Multi-product navigation. Each product can define its own tabs or top-level pages.",
+          "items": {
+            "$ref": "#/definitions/productNav"
+          },
+          "minItems": 1
+        },
+        "versions": {
+          "type": "array",
+          "description": "Versioned navigation. Each version defines its own set of tabs.",
+          "items": {
+            "$ref": "#/definitions/versionNav"
+          },
+          "minItems": 1
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Prominent external links displayed in the navbar (e.g. GitHub, Discord).",
+          "items": {
+            "$ref": "#/definitions/anchor"
+          }
+        },
+        "global": {
+          "type": "object",
+          "description": "Cross-cutting navigation elements visible on every page.",
+          "properties": {
+            "tabs": {
+              "type": "array",
+              "description": "Global external tabs shown across all pages.",
+              "items": {
+                "$ref": "#/definitions/globalTab"
+              }
+            },
+            "anchors": {
+              "type": "array",
+              "description": "Global anchors shown across all tabs.",
+              "items": {
+                "$ref": "#/definitions/anchor"
+              }
+            }
+          },
+          "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"
+          ]
+        }
+      ],
       "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": "Reference to a markdown file relative to the docs directory (without .md extension). E.g. 'quickstart' → docs/quickstart.md, 'writing-content/page' → docs/writing-content/page.md."
+      "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."
+    },
+    "href": {
+      "type": "string",
+      "description": "Navigation link target. Supports absolute URLs and internal paths (for example '/changelog' or 'guides/intro').",
+      "anyOf": [
+        {
+          "format": "uri"
+        },
+        {
+          "pattern": "^/[^\\s]*$"
+        },
+        {
+          "pattern": "^(?![a-zA-Z][a-zA-Z\\d+.-]*:)[^\\s]+$"
+        }
+      ]
+    },
+    "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", "slug", "pages"],
+      "required": [
+        "group"
+      ],
       "properties": {
         "group": {
           "type": "string",
@@ -114,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."
@@ -123,47 +640,113 @@
           "description": "Whether the group is expanded by default. Defaults to true.",
           "default": true
         },
+        "description": {
+          "type": "string",
+          "description": "Optional description displayed below the group name."
+        },
+        "hidden": {
+          "type": "boolean",
+          "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 or nested groups within this group.",
+          "description": "Pages, nested groups, separators, or external links within this group.",
           "items": {
             "oneOf": [
-              { "$ref": "#/definitions/page" },
-              { "$ref": "#/definitions/group" }
+              {
+                "$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", "slug"],
+      "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": "URL slug prefix for pages in this tab. Used as the route prefix: /<slug>/<page-basename>.",
+          "description": "Optional URL slug prefix for pages in this tab. If omitted, Velu derives one from the tab label.",
           "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
         },
         "icon": {
           "type": "string",
           "description": "Icon identifier for the tab."
         },
-        "href": {
+        "iconType": {
           "type": "string",
-          "description": "External link URL. When set, the tab links externally instead of showing pages.",
-          "format": "uri"
+          "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 directly under this tab.",
+          "description": "Standalone pages, separators, or external links directly under this tab.",
           "items": {
-            "$ref": "#/definitions/page"
+            "oneOf": [
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
+            ]
           }
         },
         "groups": {
@@ -172,27 +755,1278 @@
           "items": {
             "$ref": "#/definitions/group"
           }
+        },
+        "menu": {
+          "type": "array",
+          "description": "Optional menu items for this tab. Each menu item is normalized into a sidebar group.",
+          "items": {
+            "$ref": "#/definitions/menuItem"
+          }
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Anchors nested under this tab.",
+          "items": {
+            "$ref": "#/definitions/anchor"
+          }
+        },
+        "dropdowns": {
+          "type": "array",
+          "description": "Dropdowns nested under this tab.",
+          "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": [
+                  "pages"
+                ]
+              },
+              {
+                "required": [
+                  "groups"
+                ]
+              },
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "required": [
+                  "anchors"
+                ]
+              },
+              {
+                "required": [
+                  "dropdowns"
+                ]
+              }
             ]
           }
         },
         {
-          "not": { "required": ["href"] },
+          "not": {
+            "required": [
+              "href"
+            ]
+          },
           "anyOf": [
-            { "required": ["pages"] },
-            { "required": ["groups"] }
-          ]
-        }
+            {
+              "required": [
+                "pages"
+              ]
+            },
+            {
+              "required": [
+                "groups"
+              ]
+            },
+            {
+              "required": [
+                "menu"
+              ]
+            },
+            {
+              "required": [
+                "anchors"
+              ]
+            },
+            {
+              "required": [
+                "dropdowns"
+              ]
+            },
+            {
+              "required": [
+                "openapi"
+              ]
+            },
+            {
+              "required": [
+                "asyncapi"
+              ]
+            }
+          ]
+        }
       ]
+    },
+    "dropdown": {
+      "type": "object",
+      "description": "A dropdown navigation container.",
+      "required": [
+        "dropdown"
+      ],
+      "properties": {
+        "dropdown": {
+          "type": "string",
+          "description": "Display label for the dropdown."
+        },
+        "slug": {
+          "type": "string",
+          "description": "Optional URL slug for this dropdown.",
+          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+        },
+        "icon": {
+          "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"
+              }
+            ]
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups nested under this dropdown.",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        },
+        "menu": {
+          "type": "array",
+          "description": "Menu items nested under this dropdown.",
+          "items": {
+            "$ref": "#/definitions/menuItem"
+          }
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Anchors nested under this dropdown.",
+          "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"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "pages"
+                ]
+              },
+              {
+                "required": [
+                  "groups"
+                ]
+              },
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "required": [
+                  "anchors"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "not": {
+            "required": [
+              "href"
+            ]
+          },
+          "anyOf": [
+            {
+              "required": [
+                "pages"
+              ]
+            },
+            {
+              "required": [
+                "groups"
+              ]
+            },
+            {
+              "required": [
+                "menu"
+              ]
+            },
+            {
+              "required": [
+                "anchors"
+              ]
+            },
+            {
+              "required": [
+                "openapi"
+              ]
+            },
+            {
+              "required": [
+                "asyncapi"
+              ]
+            }
+          ]
+        }
+      ]
+    },
+    "menuItem": {
+      "type": "object",
+      "description": "A named menu item within a tab. Normalized into a sidebar group.",
+      "required": [
+        "item"
+      ],
+      "properties": {
+        "item": {
+          "type": "string",
+          "description": "Display label for the menu item."
+        },
+        "icon": {
+          "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"
+              }
+            ]
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups nested under this menu item.",
+          "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": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
+      ]
+    },
+    "separator": {
+      "type": "object",
+      "description": "A visual separator/label in the sidebar navigation.",
+      "required": [
+        "separator"
+      ],
+      "properties": {
+        "separator": {
+          "type": "string",
+          "description": "Label text for the separator."
+        }
+      },
+      "additionalProperties": false
+    },
+    "link": {
+      "type": "object",
+      "description": "An external link displayed in the sidebar.",
+      "required": [
+        "href",
+        "label"
+      ],
+      "properties": {
+        "href": {
+          "$ref": "#/definitions/href"
+        },
+        "label": {
+          "type": "string",
+          "description": "Display text for the link."
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon identifier for the link."
+        },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "anchor": {
+      "type": "object",
+      "description": "A prominent navigation anchor. Can be an external link or a container of tabs.",
+      "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.",
+          "items": {
+            "$ref": "#/definitions/tab"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups nested under this anchor.",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        },
+        "pages": {
+          "type": "array",
+          "description": "Pages nested under this anchor.",
+          "items": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
+            ]
+          }
+        },
+        "menu": {
+          "type": "array",
+          "description": "Menu items nested under this anchor.",
+          "items": {
+            "$ref": "#/definitions/menuItem"
+          }
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Anchors nested under this anchor.",
+          "items": {
+            "$ref": "#/definitions/anchor"
+          }
+        },
+        "dropdowns": {
+          "type": "array",
+          "description": "Dropdowns nested under this anchor.",
+          "items": {
+            "$ref": "#/definitions/dropdown"
+          }
+        },
+        "icon": {
+          "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.",
+          "properties": {
+            "light": {
+              "type": "string",
+              "description": "Color used in light mode (hex).",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            },
+            "dark": {
+              "type": "string",
+              "description": "Color used in dark mode (hex).",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            }
+          },
+          "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"
+          ],
+          "not": {
+            "anyOf": [
+              {
+                "required": [
+                  "tabs"
+                ]
+              },
+              {
+                "required": [
+                  "groups"
+                ]
+              },
+              {
+                "required": [
+                  "pages"
+                ]
+              },
+              {
+                "required": [
+                  "menu"
+                ]
+              },
+              {
+                "required": [
+                  "anchors"
+                ]
+              },
+              {
+                "required": [
+                  "dropdowns"
+                ]
+              }
+            ]
+          }
+        },
+        {
+          "not": {
+            "required": [
+              "href"
+            ]
+          },
+          "anyOf": [
+            {
+              "required": [
+                "tabs"
+              ]
+            },
+            {
+              "required": [
+                "groups"
+              ]
+            },
+            {
+              "required": [
+                "pages"
+              ]
+            },
+            {
+              "required": [
+                "menu"
+              ]
+            },
+            {
+              "required": [
+                "anchors"
+              ]
+            },
+            {
+              "required": [
+                "dropdowns"
+              ]
+            },
+            {
+              "required": [
+                "openapi"
+              ]
+            },
+            {
+              "required": [
+                "asyncapi"
+              ]
+            }
+          ]
+        }
+      ],
+      "additionalProperties": false
+    },
+    "productNav": {
+      "type": "object",
+      "description": "Navigation definition for a product docs area.",
+      "required": [
+        "product"
+      ],
+      "properties": {
+        "product": {
+          "type": "string",
+          "description": "Product label (used for route prefix derivation)."
+        },
+        "icon": {
+          "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."
+        },
+        "description": {
+          "type": "string",
+          "description": "Optional description for the product."
+        },
+        "hidden": {
+          "type": "boolean",
+          "description": "Whether this product is hidden from navigation. Defaults to false.",
+          "default": false
+        },
+        "href": {
+          "$ref": "#/definitions/href"
+        },
+        "color": {
+          "type": "object",
+          "description": "Optional light/dark color hints for this product.",
+          "properties": {
+            "light": {
+              "type": "string",
+              "description": "Color used in light mode (hex).",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            },
+            "dark": {
+              "type": "string",
+              "description": "Color used in dark mode (hex).",
+              "pattern": "^#[0-9a-fA-F]{6}$"
+            }
+          },
+          "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.",
+          "items": {
+            "$ref": "#/definitions/tab"
+          }
+        },
+        "dropdowns": {
+          "type": "array",
+          "description": "Dropdowns within this product.",
+          "items": {
+            "$ref": "#/definitions/dropdown"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups directly within this product.",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        },
+        "pages": {
+          "type": "array",
+          "description": "Pages directly under this product when tabs are not needed.",
+          "items": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
+            ]
+          }
+        },
+        "menu": {
+          "type": "array",
+          "description": "Menu items directly within this product.",
+          "items": {
+            "$ref": "#/definitions/menuItem"
+          }
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Anchors directly within this product.",
+          "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": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
+      ]
+    },
+    "versionNav": {
+      "type": "object",
+      "description": "Navigation definition for a specific docs version.",
+      "required": [
+        "version"
+      ],
+      "properties": {
+        "version": {
+          "type": "string",
+          "description": "Version label (used for route prefix derivation)."
+        },
+        "default": {
+          "type": "boolean",
+          "description": "Whether this is the default version.",
+          "default": false
+        },
+        "hidden": {
+          "type": "boolean",
+          "description": "Whether this version is hidden from navigation. Defaults to false.",
+          "default": false
+        },
+        "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.",
+          "items": {
+            "$ref": "#/definitions/tab"
+          }
+        },
+        "dropdowns": {
+          "type": "array",
+          "description": "Dropdowns for this version.",
+          "items": {
+            "$ref": "#/definitions/dropdown"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups for this version.",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        },
+        "pages": {
+          "type": "array",
+          "description": "Pages for this version.",
+          "items": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
+            ]
+          }
+        },
+        "menu": {
+          "type": "array",
+          "description": "Menu items for this version.",
+          "items": {
+            "$ref": "#/definitions/menuItem"
+          }
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Anchors for this version.",
+          "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": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
+      ],
+      "additionalProperties": false
+    },
+    "globalTab": {
+      "type": "object",
+      "description": "Global external tab shown in the navbar across all pages.",
+      "required": [
+        "tab",
+        "href"
+      ],
+      "properties": {
+        "tab": {
+          "type": "string",
+          "description": "Display name for the global tab."
+        },
+        "href": {
+          "$ref": "#/definitions/href"
+        },
+        "icon": {
+          "type": "string",
+          "description": "Icon identifier for the global tab."
+        },
+        "iconType": {
+          "type": "string",
+          "description": "Icon style hint (primarily for Font Awesome)."
+        }
+      },
+      "additionalProperties": false
+    },
+    "languageNav": {
+      "type": "object",
+      "description": "Per-language navigation entry. Defines the full tab/group/page structure for one language.",
+      "required": [
+        "language"
+      ],
+      "properties": {
+        "language": {
+          "type": "string",
+          "description": "BCP 47 language code (e.g. en, es, ja)."
+        },
+        "default": {
+          "type": "boolean",
+          "description": "Whether this is the default language.",
+          "default": false
+        },
+        "hidden": {
+          "type": "boolean",
+          "description": "Whether this language is hidden from navigation. Defaults to false.",
+          "default": false
+        },
+        "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.",
+          "items": {
+            "$ref": "#/definitions/tab"
+          }
+        },
+        "dropdowns": {
+          "type": "array",
+          "description": "Dropdowns for this language.",
+          "items": {
+            "$ref": "#/definitions/dropdown"
+          }
+        },
+        "groups": {
+          "type": "array",
+          "description": "Groups for this language.",
+          "items": {
+            "$ref": "#/definitions/group"
+          }
+        },
+        "pages": {
+          "type": "array",
+          "description": "Pages for this language.",
+          "items": {
+            "oneOf": [
+              {
+                "$ref": "#/definitions/page"
+              },
+              {
+                "$ref": "#/definitions/separator"
+              },
+              {
+                "$ref": "#/definitions/link"
+              }
+            ]
+          }
+        },
+        "menu": {
+          "type": "array",
+          "description": "Menu items for this language.",
+          "items": {
+            "$ref": "#/definitions/menuItem"
+          }
+        },
+        "anchors": {
+          "type": "array",
+          "description": "Anchors for this language.",
+          "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": [
+            "openapi"
+          ]
+        },
+        {
+          "required": [
+            "asyncapi"
+          ]
+        }
+      ],
+      "additionalProperties": false
     }
   }
 }