knowledge-base/contract/kb-docs.schema.json at master · AbsaOSS/knowledge-base · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "$id": "https://raw.githubusercontent.com/AbsaOSS/knowledge-base/master/contract/kb-docs.schema.json",
  "title": "kb-docs.json",
  "description": "Manifest at the root of a kb-docs.tar.gz release artifact. Describes every app the archive publishes. See contract/ARTIFACT.md.",
  "type": "object",
  "required": ["kbVersion", "apps"],
  "additionalProperties": false,
  "properties": {
    "kbVersion": {
      "type": "string",
      "enum": ["1"],
      "description": "Contract version. Must be '1'."
    },
    "apps": {
      "type": "array",
      "minItems": 1,
      "description": "One entry per app in the archive. A packaged documentation site is a list of one.",
      "items": { "$ref": "#/definitions/app" }
    }
  },
  "definitions": {
    "app": {
      "type": "object",
      "required": ["slug", "name", "description"],
      "additionalProperties": false,
      "properties": {
        "slug": {
          "type": "string",
          "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$",
          "minLength": 2,
          "maxLength": 32,
          "description": "Names the app's directory in the archive and its public URL prefix /knowledge-base/{slug}/. Must be unique across the whole knowledge base — prefix it with your service name."
        },
        "name": {
          "type": "string",
          "minLength": 2,
          "maxLength": 64,
          "description": "Human-readable app name, shown on the catalog card and in the masthead."
        },
        "description": {
          "type": "string",
          "minLength": 10,
          "maxLength": 280,
          "description": "One sentence, shown on the catalog card."
        },
        "entryPoint": {
          "type": "string",
          "default": "index.html",
          "description": "Landing page, relative to the app's directory in the archive.",
          "$comment": "Relative, forward-slashed, no traversal — enforced by the pattern below rather than by prose.",
          "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
        },
        "icon": {
          "type": "string",
          "default": "book-open",
          "description": "Icon name from the supported set. An unrecognised value falls back to book-open rather than failing the build.",
          "enum": [
            "book-open", "cube", "chip", "chart-bar", "shield",
            "cog", "terminal", "globe", "layers", "lightning-bolt",
            "document", "collection", "puzzle", "database"
          ]
        },
        "tags": {
          "type": "array",
          "maxItems": 5,
          "description": "Taxonomy tags shown as pills on the catalog card.",
          "items": { "type": "string", "minLength": 1, "maxLength": 32 }
        },
        "pages": {
          "type": "array",
          "minItems": 1,
          "description": "Navigation manifest. When present it is the authoritative route list for the app and the knowledge base does not crawl the directory.",
          "items": { "$ref": "#/definitions/page" }
        }
      }
    },
    "page": {
      "type": "object",
      "required": ["title", "path", "order"],
      "additionalProperties": false,
      "properties": {
        "title": {
          "type": "string",
          "minLength": 1,
          "maxLength": 128,
          "description": "Human-readable page title used in navigation."
        },
        "path": {
          "type": "string",
          "description": "Path to the HTML file, relative to the app's directory in the archive.",
          "pattern": "^(?!/)(?!.*(^|/)\\.\\.(/|$))[^\\\\]+$"
        },
        "order": {
          "type": "integer",
          "minimum": 0,
          "description": "Sort position within the app's navigation (lower sorts higher)."
        },
        "section": {
          "type": "string",
          "minLength": 1,
          "maxLength": 64,
          "description": "Optional group heading to display above this page."
        }
      }
    }
  }
}