From f81d5273a1d41d06f0e923b629fe346176ef4ec0 Mon Sep 17 00:00:00 2001
From: Dylan Farrell <dylan@getcatalog.ai>
Date: Tue, 19 May 2026 15:57:08 -0700
Subject: [PATCH] feat(schema): add distribution and verified-purchase count to
 Rating

Adds two optional properties to source/schemas/shopping/types/rating.json:

- distribution: per-bucket review counts so agents can detect patterns
  like bimodal distributions that an average would obscure.
- verified_count: sub-count of reviews from verified purchasers.

Additive. No new files, no docs changes (the existing schema_fields
macro auto-renders the new fields), no transport changes.
---
 source/schemas/shopping/types/rating.json | 34 +++++++++++++++++++++++
 1 file changed, 34 insertions(+)

diff --git a/source/schemas/shopping/types/rating.json b/source/schemas/shopping/types/rating.json
index 6b0b3b5fb..3b0bf8c60 100644
--- a/source/schemas/shopping/types/rating.json
+++ b/source/schemas/shopping/types/rating.json
@@ -29,6 +29,40 @@
       "type": "integer",
       "minimum": 0,
       "description": "Number of reviews contributing to the rating."
+    },
+    "distribution": {
+      "type": "object",
+      "description": "Per-bucket review counts so agents can detect patterns like bimodal distributions that an average would obscure. Sum of bucket counts SHOULD equal `count`.",
+      "required": ["buckets"],
+      "additionalProperties": false,
+      "properties": {
+        "buckets": {
+          "type": "array",
+          "minItems": 1,
+          "description": "One entry per discrete scale value. Continuous scales bucket at integers by default; producers grading at half-integers MAY include half-integer bucket values.",
+          "items": {
+            "type": "object",
+            "required": ["value", "count"],
+            "additionalProperties": false,
+            "properties": {
+              "value": {
+                "type": "number",
+                "description": "Bucket value on the rating scale. MUST fall within `scale_min`/`scale_max`."
+              },
+              "count": {
+                "type": "integer",
+                "minimum": 0,
+                "description": "Number of reviews at this bucket value."
+              }
+            }
+          }
+        }
+      }
+    },
+    "verified_count": {
+      "type": "integer",
+      "minimum": 0,
+      "description": "Number of reviews from verified purchasers. MUST be less than or equal to `count`. The definition of \"verified\" is business-defined (e.g., purchase confirmed, identity-linked)."
     }
   }
 }