Add schema for data and config files (#785)

Closes #661 Signed-off-by: Cintia Sánchez García <cynthiasg@icloud.com>
cncf · Jan 16, 2025 · 78c5155 · 78c5155
1 parent 7f60c8b
commit 78c5155
Show file tree

Hide file tree

Showing 8 changed files with 1,096 additions and 3 deletions.
diff --git a/docs/config/data.yml b/docs/config/data.yml
@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/cncf/landscape2/refs/heads/main/docs/config/schema/data.schema.json
+
 # Landscape2 data
 #
 # This file contains the data that will be used to generate the landscape. The landscape data is a
@@ -164,7 +166,7 @@ categories:
               documentation_url: https://documentation.url
 
               # Facebook URL (optional).
-              facebook_url: https://facebook.url
+              facebook_url: https://facebook.com/url
 
               # GitHub discussions URL (optional).
               github_discussions_url: https://github.discussions.url
@@ -208,10 +210,10 @@ categories:
               parent_project: "Project name"
 
               # Pinterest URL (optional).
-              pinterest_url: https://pinterest.url
+              pinterest_url: https://pinterest.com/url
 
               # Reddit URL (optional).
-              reddit_url: https://reddit.url
+              reddit_url: https://reddit.com/url
 
               # Slack URL (optional).
               slack_url: https://slack.url

diff --git a/docs/config/games.yml b/docs/config/games.yml
@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/cncf/landscape2/refs/heads/main/docs/config/schema/games.schema.json
+
 # Landscape games data
 #
 # This file allows defining the content of the landscape games.

diff --git a/docs/config/guide.yml b/docs/config/guide.yml
@@ -1,3 +1,5 @@
+# yaml-language-server: $schema=https://raw.githubusercontent.com/cncf/landscape2/refs/heads/main/docs/config/schema/guide.schema.json
+
 # Landscape2 guide
 #
 # This file allows defining the content of the landscape guide.

diff --git a/docs/config/schema/data.schema.json b/docs/config/schema/data.schema.json
diff --git a/docs/config/schema/games.schema.json b/docs/config/schema/games.schema.json
@@ -0,0 +1,66 @@
+{
+  "title": "Landscape games JSON schema",
+  "description": "The games file allows defining the content of the landscape games",
+  "type": "object",
+  "properties": {
+    "quiz": {
+      "title": "Quiz game content",
+      "type": "object",
+      "properties": {
+        "questions": {
+          "title": "List of questions",
+          "description": "A subset of these questions will be randomly picked up for each quiz game",
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "title": {
+                "title": "Question title",
+                "type": "string",
+                "examples": ["Which of the following projects provides an open source container orchestration engine for automating deployment, scaling, and management of containerized applications?"]
+              },
+              "options": {
+                "title": "Answer options",
+                "description": "At least two options must be provided. Options will be shuffled on every quiz game, so the order used here is not important",
+                "type": "array",
+                "items": {
+                  "type": "object",
+                  "properties": {
+                    "item": {
+                      "title": "Name of the landscape item this option refers to",
+                      "description": "It must match the name of the item in the landscape.yml file",
+                      "type": "string",
+                      "examples": ["Kubernetes", "gRPC", "Cilium"]
+                    },
+                    "category": {
+                      "title": "Category of the item in the landscape",
+                      "description": "This field can be used when the item is not unique across the landscape to avoid ambiguity",
+                      "type": "string",
+                      "examples": ["Orchestration & Management"]
+                    },
+                    "subcategory": {
+                      "title": "Subcategory of the item in the landscape",
+                      "description": "This field can be used when the item is not unique across the landscape to avoid ambiguity",
+                      "type": "string",
+                      "examples": ["Scheduling & Orchestration"]
+                    },
+                    "correct": {
+                      "title": "Whether this option is correct",
+                      "description": "It can be omitted if this not the correct option. Only one option can be marked as correct",
+                      "type": "boolean",
+                      "examples": [true, false]
+                    }
+                  },
+                  "required": ["item"]
+                },
+                "minItems": 2
+              }
+            },
+            "required": ["title", "options"]
+          }
+        }
+      }
+    }
+  },
+  "required": ["quiz"]
+}
diff --git a/docs/config/schema/guide.schema.json b/docs/config/schema/guide.schema.json
@@ -0,0 +1,49 @@
+{
+  "title": "Landscape guide JSON schema",
+  "description": "The guide file allows defining the content of the landscape guide. The landscape guide is organized into categories and subcategories. Each of these entities requires a name and some content. The content can be provided in markdown format. Categories and subcategories names are not required to match the ones defined in the landscape data file but, when they do, those categories/subcategories will be enriched with some extra information. So whenever possible, it's highly recommended that they do. We recommend using headings of level 4-6 within the content blocks as levels 1-3 are reserved to illustrate the hierarchy of categories and subcategories",
+  "type": "object",
+  "properties": {
+    "categories": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "category": {
+            "title": "The name of the category",
+            "type": "string"
+          },
+          "content": {
+            "title": "The content of the category in markdown format",
+            "type": "string"
+          },
+          "keywords": {
+            "title": "Keywords associated with the category",
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          },
+          "subcategories": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "subcategory": {
+                  "title": "The name of the subcategory",
+                  "type": "string"
+                },
+                "content": {
+                  "title": "The content of the subcategory in markdown format",
+                  "type": "string"
+                }
+              },
+              "required": ["subcategory", "content"]
+            }
+          }
+        },
+        "required": ["category", "content"]
+      }
+    }
+  },
+  "required": ["categories"]
+}