From 0c8817457f7d71c38f4f3df3ce30df415636b98a Mon Sep 17 00:00:00 2001
From: Bob Nisco <bob.nisco@snowflake.com>
Date: Tue, 13 Jan 2026 13:59:14 -0800
Subject: [PATCH] [feat] Add JSONSchemas

---
 directory/schemas/compiled.schema.json  | 157 ++++++++++++++++++++++++
 directory/schemas/component.schema.json | 124 +++++++++++++++++++
 2 files changed, 281 insertions(+)
 create mode 100644 directory/schemas/compiled.schema.json
 create mode 100644 directory/schemas/component.schema.json

diff --git a/directory/schemas/compiled.schema.json b/directory/schemas/compiled.schema.json
new file mode 100644
index 00000000..2f95965f
--- /dev/null
+++ b/directory/schemas/compiled.schema.json
@@ -0,0 +1,157 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/compiled.schema.json",
+  "title": "Component Gallery compiled catalog (compiled/components.json)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["generatedAt", "schemaVersion", "categories", "components"],
+  "properties": {
+    "generatedAt": { "type": "string", "format": "date-time" },
+    "schemaVersion": { "type": "integer", "const": 1 },
+    "categories": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "type": "string" }
+    },
+    "components": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "title",
+          "author",
+          "socialUrl",
+          "pipLink",
+          "categories",
+          "image",
+          "gitHubUrl",
+          "enabled",
+          "appUrl"
+        ],
+        "properties": {
+          "title": { "type": "string", "minLength": 1 },
+          "author": { "type": "string", "minLength": 1 },
+          "pipLink": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "null" }
+            ]
+          },
+          "pypi": {
+            "oneOf": [
+              { "type": "string", "minLength": 1 },
+              { "type": "null" }
+            ]
+          },
+          "categories": {
+            "type": "array",
+            "minItems": 1,
+            "uniqueItems": true,
+            "items": { "type": "string" }
+          },
+          "image": { "type": ["string", "null"], "format": "uri" },
+          "gitHubUrl": { "type": "string", "format": "uri" },
+          "enabled": { "type": "boolean" },
+          "appUrl": { "type": ["string", "null"], "format": "uri" },
+          "socialUrl": { "type": ["string", "null"], "format": "uri" },
+          "metrics": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "properties": {
+              "github": {
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "properties": {
+                  "stars": { "type": ["integer", "null"], "minimum": 0 },
+                  "forks": { "type": ["integer", "null"], "minimum": 0 },
+                  "contributorsCount": {
+                    "type": ["integer", "null"],
+                    "minimum": 0
+                  },
+                  "openIssues": { "type": ["integer", "null"], "minimum": 0 },
+                  "lastPushAt": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "fetchedAt": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "isStale": { "type": ["boolean", "null"] }
+                }
+              },
+              "pypi": {
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "properties": {
+                  "latestVersion": {
+                    "oneOf": [
+                      { "type": "string", "minLength": 1 },
+                      { "type": "null" }
+                    ]
+                  },
+                  "latestReleaseAt": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "fetchedAt": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "isStale": { "type": ["boolean", "null"] }
+                }
+              },
+              "pypistats": {
+                "type": ["object", "null"],
+                "additionalProperties": false,
+                "properties": {
+                  "lastDay": { "type": ["integer", "null"], "minimum": 0 },
+                  "lastWeek": { "type": ["integer", "null"], "minimum": 0 },
+                  "lastMonth": { "type": ["integer", "null"], "minimum": 0 },
+                  "fetchedAt": {
+                    "type": ["string", "null"],
+                    "format": "date-time"
+                  },
+                  "isStale": { "type": ["boolean", "null"] }
+                }
+              }
+            }
+          },
+          "ranking": {
+            "type": ["object", "null"],
+            "additionalProperties": false,
+            "required": ["score", "signals", "computedAt"],
+            "properties": {
+              "score": { "type": "number" },
+              "computedAt": { "type": "string", "format": "date-time" },
+              "signals": {
+                "type": "object",
+                "additionalProperties": false,
+                "properties": {
+                  "starsScore": { "type": ["number", "null"] },
+                  "recencyScore": { "type": ["number", "null"] },
+                  "daysSinceUpdate": {
+                    "type": ["number", "null"],
+                    "minimum": 0
+                  },
+                  "contributorsScore": { "type": ["number", "null"] },
+                  "daysSinceGithubPush": {
+                    "type": ["number", "null"],
+                    "minimum": 0
+                  },
+                  "daysSincePypiRelease": {
+                    "type": ["number", "null"],
+                    "minimum": 0
+                  },
+                  "downloadsScore": { "type": ["number", "null"] }
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+}
diff --git a/directory/schemas/component.schema.json b/directory/schemas/component.schema.json
new file mode 100644
index 00000000..720d8ccc
--- /dev/null
+++ b/directory/schemas/component.schema.json
@@ -0,0 +1,124 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://example.com/schemas/component.schema.json",
+  "title": "Component Gallery submission (source-of-truth)",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "title", "author", "links", "governance", "categories"],
+  "properties": {
+    "schemaVersion": {
+      "type": "integer",
+      "const": 1
+    },
+    "title": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 80
+    },
+    "author": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["github"],
+      "properties": {
+        "github": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 39,
+          "pattern": "^[A-Za-z0-9_]+(?:-[A-Za-z0-9_]+)*$",
+          "description": "GitHub username (no @)."
+        },
+        "displayName": {
+          "type": "string",
+          "minLength": 1,
+          "maxLength": 80
+        }
+      }
+    },
+    "links": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["github"],
+      "properties": {
+        "github": {
+          "type": "string",
+          "format": "uri",
+          "pattern": "^https://github\\.com/[^/]+/[^/]+/?$"
+        },
+        "pypi": {
+          "type": ["string", "null"],
+          "pattern": "^[A-Za-z0-9_.-]+$",
+          "description": "PyPI project name (not a URL)."
+        },
+        "demo": {
+          "type": ["string", "null"],
+          "format": "uri"
+        },
+        "docs": {
+          "type": ["string", "null"],
+          "format": "uri"
+        }
+      }
+    },
+    "media": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "image": {
+          "type": ["string", "null"],
+          "format": "uri"
+        }
+      }
+    },
+    "install": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "pip": {
+          "type": ["string", "null"],
+          "minLength": 1,
+          "maxLength": 200
+        }
+      }
+    },
+    "governance": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["enabled"],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "notes": {
+          "type": ["string", "null"],
+          "maxLength": 500
+        }
+      }
+    },
+    "categories": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "enum": [
+          "LLMs",
+          "Widgets",
+          "Charts",
+          "Authentication",
+          "Connections",
+          "Images & video",
+          "Audio",
+          "Text",
+          "Maps",
+          "Dataframes",
+          "Graphs",
+          "Molecules & genes",
+          "Code editors",
+          "Page navigation",
+          "Developer tools",
+          "Integrations"
+        ]
+      }
+    }
+  }
+}