test(protocol): add catalog structural integrity validation

Update the Catalog definition schema in client_capabilities.json to allow standard JSON schema properties ($schema, $id, title, description, $defs). Add a new test step to run_tests.py that automatically validates the basic, minimal, and testing catalogs against this Catalog schema definition.

Author: gspencergoog

samples/client/flutter/restaurant_finder/e2e_test/test/infra_test.dart

@@ -30,13 +30,9 @@ void main() {
     print('Joke from AI:\n\n$result\n\n');
   });
 
-  test(
-    'test can start restaurant_finder',
-    () async {
-      final restaurantFinderClient = TestRestaurantFinderClient();
-      addTearDown(restaurantFinderClient.dispose);
-      await restaurantFinderClient.startAndVerify();
-    },
-    timeout: const Timeout(Duration(minutes: 5)),
-  );
+  test('test can start restaurant_finder', () async {
+    final restaurantFinderClient = TestRestaurantFinderClient();
+    addTearDown(restaurantFinderClient.dispose);
+    await restaurantFinderClient.startAndVerify();
+  }, timeout: const Timeout(Duration(minutes: 5)));
 }

specification/v0_10/json/client_capabilities.json

@@ -41,7 +41,7 @@
             "call": {
               "type": "object",
               "properties": {
-                "const": { "type": "string" }
+                "const": {"type": "string"}
               },
               "required": ["const"]
             },
@@ -56,8 +56,8 @@
         },
         "required": {
           "type": "array",
-          "items": { "type": "string" },
-          "contains": { "const": "call" }
+          "items": {"type": "string"},
+          "contains": {"const": "call"}
         },
         "unevaluatedProperties": {
           "type": "boolean"
@@ -99,6 +99,11 @@
       "type": "object",
       "description": "A collection of component and function definitions.",
       "properties": {
+        "$schema": {"type": "string"},
+        "$id": {"type": "string"},
+        "title": {"type": "string"},
+        "description": {"type": "string"},
+        "$defs": {"type": "object"},
         "catalogId": {
           "type": "string",
           "description": "Unique identifier for this catalog."

specification/v0_10/test/run_tests.py

@@ -183,6 +183,63 @@ def validate_jsonl_example(jsonl_path):
     finally:
         cleanup_catalog_alias()
 
+def validate_catalogs_structure():
+    """
+    Validates the catalog files directly against the Catalog definition in
+    client_capabilities.json schema.
+    """
+    client_caps_path = os.path.join(SCHEMA_DIR, "client_capabilities.json")
+    if not os.path.exists(client_caps_path):
+        print(f"Error: client_capabilities.json not found at {client_caps_path}")
+        return 0, 1
+
+    temp_validator_path = os.path.join(TEST_DIR, "temp_catalog_validator.json")
+
+    # We reference the absolute ID of client_capabilities.json which gets loaded as a reference
+    validator_schema = {
+        "$schema": "https://json-schema.org/draft/2020-12/schema",
+        "$ref": "https://a2ui.org/specification/v0_10/client_capabilities.json#/$defs/Catalog"
+    }
+
+    with open(temp_validator_path, 'w') as f:
+        json.dump(validator_schema, f)
+
+    catalogs_to_validate = [
+        ("catalogs/basic/catalog.json", os.path.join(SPEC_DIR, "catalogs/basic/catalog.json")),
+        ("catalogs/minimal/catalog.json", os.path.join(SPEC_DIR, "catalogs/minimal/catalog.json")),
+        ("test/testing_catalog.json", os.path.join(TEST_DIR, "testing_catalog.json")),
+    ]
+
+    passed = 0
+    failed = 0
+
+    print("\nValidating catalog structural integrity against client_capabilities.json...")
+
+    ref_schemas = {
+        "client_capabilities.json": client_caps_path
+    }
+
+    try:
+        for name, path in catalogs_to_validate:
+            if not os.path.exists(path):
+                print(f"  [FAIL] {name} (File not found)")
+                failed += 1
+                continue
+
+            is_valid, output = validate_ajv(temp_validator_path, path, ref_schemas)
+            if is_valid:
+                passed += 1
+                # print(f"  [PASS] {name}")
+            else:
+                failed += 1
+                print(f"  [FAIL] {name}")
+                print(f"         Output: {output.strip()}")
+
+        return passed, failed
+    finally:
+        if os.path.exists(temp_validator_path):
+            os.remove(temp_validator_path)
+
 def main():
     if not os.path.exists(CASES_DIR):
         print(f"No cases directory found at {CASES_DIR}")
@@ -206,6 +263,11 @@ def main():
         total_passed += p
         total_failed += f
 
+        # 3. Validate catalogs structural integrity
+        p, f = validate_catalogs_structure()
+        total_passed += p
+        total_failed += f
+
         print("\n" + "="*30)
         print(f"Total Passed: {total_passed}")
         print(f"Total Failed: {total_failed}")