Add catalogs configuration schema

README.md

@@ -52,7 +52,21 @@ list:
     react: npm:19.0.0
 ```
 
-### 2. Apply catalogs to `.yarnrc.yml`
+### 2. (Optional) Configure schema validation in VSCode
+
+For better editing experience with `catalogs.yml`, you can enable schema validation in VSCode by adding the following to `.vscode/settings.json`:
+
+```json
+{
+  "yaml.schemas": {
+    "https://raw.githubusercontent.com/toss/yarn-plugin-catalogs/refs/heads/main/sources/configuration/schema.json": "catalogs.yml"
+  }
+}
+```
+
+This will provide autocomplete and validation for your `catalogs.yml` file.
+
+### 3. Apply catalogs to `.yarnrc.yml`
 
 ```bash
 $ yarn catalogs apply
@@ -101,7 +115,7 @@ catalogs:
     react: npm:19.0.0
 ```
 
-### 3. Use catalog protocol in package.json
+### 4. Use catalog protocol in package.json
 
 ```json
 {

sources/configuration/schema.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2019-09/schema#",
+  "title": "Yarn Catalogs Configuration",
+  "description": "The schema for the Yarn catalogs configuration file (catalogs.yml). Strictly validates options and catalog mappings.",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "options": {
+      "type": "object",
+      "description": "Optional options that control the catalog behavior",
+      "additionalProperties": false,
+      "properties": {
+        "default": {
+          "description": "Default enabled catalog groups for 'yarn add'. Can be the reserved token 'max' for max mode, a single group name, or an array of group names.",
+          "oneOf": [
+            { "type": "string", "enum": ["max"] },
+            { "$ref": "#/$defs/catalogGroupName" },
+            {
+              "type": "array",
+              "items": { "$ref": "#/$defs/catalogGroupName" }
+            }
+          ]
+        },
+        "validation": {
+          "type": "string",
+          "description": "The level of dependency source validation",
+          "enum": ["warn", "strict", "off"]
+        },
+        "includedWorkspaces": {
+          "type": "array",
+          "description": "The list of workspace names/paths to include in catalog application",
+          "items": { "$ref": "#/$defs/workspaceName" }
+        },
+        "ignoredWorkspaces": {
+          "type": "array",
+          "description": "The list of workspace names/paths to exclude from catalog application",
+          "items": { "$ref": "#/$defs/workspaceName" }
+        }
+      }
+    },
+    "list": {
+      "type": "object",
+      "description": "The mapping of package sources by catalog group",
+      "propertyNames": { "$ref": "#/$defs/catalogGroupName" },
+      "additionalProperties": { "$ref": "#/$defs/catalogGroup" },
+      "minProperties": 1
+    }
+  },
+  "required": ["list"],
+  "$defs": {
+    "workspaceName": {
+      "type": "string",
+      "minLength": 1
+    },
+    "catalogGroupName": {
+      "type": "string",
+      "description": "Catalog group name; may include '/' to indicate inheritance (e.g., stable, stable/canary). Excludes the reserved token 'max'.",
+      "pattern": "^(?!max$)[A-Za-z0-9._-]+(?:\\/[A-Za-z0-9._-]+)*$"
+    },
+    "packageName": {
+      "type": "string",
+      "description": "The package name",
+      "pattern": "^(?:@[a-z0-9][a-z0-9-_]*\\/)?[a-z0-9][a-z0-9-._]*$"
+    },
+    "sourceString": {
+      "type": "string",
+      "description": "Free-form version/source string (e.g. \"18.2.0\", \"log-v3:45.0.1::__version=7.0.16\", \"1.0.14-nightly.20251119194855\")."
+    },
+    "catalogGroup": {
+      "type": "object",
+      "description": "Mapping of package name → source specification",
+      "additionalProperties": { "$ref": "#/$defs/sourceString" },
+      "propertyNames": { "$ref": "#/$defs/packageName" },
+      "minProperties": 0
+    }
+  }
+}