{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://bare-os.local/man-page.schema.json",
  "title": "Bare OS manual page",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name",
    "section",
    "title",
    "synopsis",
    "description",
    "options",
    "keywords"
  ],
  "properties": {
    "name": { "type": "string", "minLength": 1 },
    "section": { "type": "integer", "minimum": 1, "maximum": 8 },
    "title": { "type": "string", "minLength": 1 },
    "synopsis": {
      "type": "array",
      "items": { "type": "string" },
      "minItems": 1
    },
    "description": { "type": "string", "minLength": 1 },
    "options": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["flag", "meaning"],
        "properties": {
          "flag": { "type": "string" },
          "meaning": { "type": "string" }
        }
      }
    },
    "environment": {
      "type": "array",
      "items": { "type": "string" }
    },
    "files": {
      "type": "array",
      "items": { "type": "string" }
    },
    "exitStatus": {
      "type": "array",
      "items": { "type": "string" }
    },
    "diagnostics": {
      "type": "array",
      "items": { "type": "string" }
    },
    "seeAlso": {
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "section"],
        "properties": {
          "name": { "type": "string" },
          "section": { "type": "integer", "minimum": 1 }
        }
      }
    },
    "bareOsNotes": { "type": "string" },
    "descriptionMode": {
      "description": "wrap (default): reflow DESCRIPTION as prose; preserve: keep line breaks (handbook)",
      "type": "string",
      "enum": ["wrap", "preserve"]
    },
    "listCategory": {
      "description": "Merged DB only: group for man -l (coreutils, extra, handbook, devguide, docs, usersmanual)",
      "type": "string",
      "enum": ["coreutils", "extra", "handbook", "devguide", "docs", "usersmanual"]
    },
    "keywords": {
      "type": "array",
      "items": { "type": "string" }
    },
    "aliases": {
      "type": "array",
      "items": { "type": "string" }
    },
    "stub": { "type": "boolean" },
    "examples": {
      "description": "Cheat-sheet style snippets: caption + shell command(s)",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["code"],
        "properties": {
          "caption": { "type": "string" },
          "code": { "type": "string", "minLength": 1 }
        }
      }
    },
    "builtins": {
      "type": "array",
      "description": "Per-builtin sections for bare-os-shell(1)",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": ["name", "description"],
        "properties": {
          "name": { "type": "string" },
          "synopsis": {
            "type": "array",
            "items": { "type": "string" }
          },
          "description": { "type": "string" },
          "options": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["flag", "meaning"],
              "properties": {
                "flag": { "type": "string" },
                "meaning": { "type": "string" }
              }
            }
          },
          "examples": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": ["code"],
              "properties": {
                "caption": { "type": "string" },
                "code": { "type": "string", "minLength": 1 }
              }
            }
          }
        }
      }
    }
  }
}