From bb233880b1f319e1a911edb80355757e3732645d Mon Sep 17 00:00:00 2001
From: "Alex Pooley (@zuedev)" <zuedev@gmail.com>
Date: Thu, 5 Feb 2026 15:35:25 +0000
Subject: add json schema

---
 README.md           | 11 +++++++++
 gitinfo.schema.json | 69 +++++++++++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 80 insertions(+)
 create mode 100644 gitinfo.schema.json

diff --git a/README.md b/README.md
index 1973bfd..e81e102 100644
--- a/README.md
+++ b/README.md
@@ -10,10 +10,21 @@ The `.gitinfo` file is a simple text file that can be placed in the root directo
 
 The `.gitinfo` file uses JSONC (JSON with Comments) format, allowing for easy readability and the inclusion of comments. The file consists of key-value pairs, where each key represents a specific piece of metadata about the repository.
 
+### Validation
+
+A JSON Schema is available for validating `.gitinfo` files:
+
+```
+https://raw.githubusercontent.com/zuedev/gitinfo/main/gitinfo.schema.json
+```
+
+You can reference the schema in your `.gitinfo` file using the `$schema` property for editor autocompletion and validation support.
+
 ### Example `.gitinfo` File
 
 ```jsonc
 {
+  "$schema": "https://raw.githubusercontent.com/zuedev/gitinfo/main/gitinfo.schema.json",
   "root": "https://github.com/example/repository",
   "gitmail": "patches@example.com",
   "icon": "https://example.com/icon.png",
diff --git a/gitinfo.schema.json b/gitinfo.schema.json
new file mode 100644
index 0000000..1b9f241
--- /dev/null
+++ b/gitinfo.schema.json
@@ -0,0 +1,69 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://raw.githubusercontent.com/zuedev/gitinfo/main/gitinfo.schema.json",
+  "title": ".gitinfo",
+  "description": "Schema for the .gitinfo file specification",
+  "type": "object",
+  "required": ["root"],
+  "properties": {
+    "root": {
+      "type": "string",
+      "format": "uri",
+      "description": "The URL of the root repository. This is the main hosting location that acts as the source of truth for the codebase."
+    },
+    "gitmail": {
+      "type": "string",
+      "format": "email",
+      "description": "An email address associated with the repository for submitting git patches."
+    },
+    "icon": {
+      "type": "string",
+      "description": "A public URL or data URI formatted image (PNG, SVG, etc.) representing an icon for the repository.",
+      "pattern": "^(https?://|data:image/)"
+    },
+    "description": {
+      "type": "string",
+      "description": "A brief description of the repository's purpose or contents."
+    },
+    "tags": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "description": "A list of tags or keywords associated with the repository for easier categorization and searchability."
+    },
+    "mirrors": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "format": "uri"
+      },
+      "description": "A list of URLs representing mirror repositories."
+    },
+    "maintainers": {
+      "type": "array",
+      "items": {
+        "type": "array",
+        "items": [
+          {
+            "type": "string",
+            "description": "Maintainer name"
+          },
+          {
+            "type": "string",
+            "format": "email",
+            "description": "Maintainer email"
+          }
+        ],
+        "minItems": 2,
+        "maxItems": 2
+      },
+      "description": "A list of maintainers or contributors to the repository, provided as a 2D array with names and email addresses in the format [[name, email], ...]."
+    },
+    "license": {
+      "type": "string",
+      "description": "The license under which the repository is distributed. Use the short identifier from SPDX License List for consistency."
+    }
+  },
+  "additionalProperties": false
+}
-- 
cgit v1.2.3