@coveo/thermidor-schema 1.0.0-beta.4 → 1.0.0-beta.40

package/schema/components/layout-stack.schema.json

@@ -2,16 +2,31 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/layout-stack.schema.json",
   "title": "LayoutStack",
-  "description": "Generic layout container that stacks its children along a single axis. It carries no business data: its AG-UI state is empty. Layout is a presentation concern and travels as an A2-UI node prop ('direction': 'column' | 'row'), never as AG-UI state. Reused across surfaces (commerce search, knowledge search) to compose columns and rows from the A2-UI composition plane rather than hardcoding layout per parent renderer.",
+  "description": "Generic layout container that stacks its children along a single axis. Carries no business data; its state is empty and the stacking direction travels as a presentation prop.",
+  "$comment": "Reused across surfaces to compose rows/columns from the A2-UI composition plane rather than hardcoding layout per parent renderer.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "LayoutStack"
+    },
+    "direction": {
+      "title": "LayoutStackDirection",
       "type": "string",
-      "const": "layout-stack"
+      "enum": ["column", "row"],
+      "description": "The axis along which children are stacked. A plain presentation value at the node top level, never server state."
+    },
+    "children": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-list.schema.json",
+      "description": "The ordered children, a ChildList of ComponentId references mounted in order via children(id).",
+      "$comment": "Homogeneous ordered-list composition: the ordered list is the semantics; child ids are static, passed through unresolved."
     },
     "state": {
       "$ref": "#/$defs/LayoutStackState"
@@ -20,24 +35,13 @@
       "type": "object",
       "properties": {},
       "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
-      },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
   "$defs": {
     "LayoutStackState": {
       "title": "LayoutStackState",
-      "description": "The layout-stack state. A layout container holds no business data, so its state is always the empty object. The stacking direction is presentation and travels as an A2-UI node prop, never as AG-UI state.",
+      "description": "Empty: a layout container holds no business data.",
       "type": "object",
       "required": [],
       "properties": {},

package/schema/components/next-actions-bar.schema.json

@@ -2,40 +2,40 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/next-actions-bar.schema.json",
   "title": "NextActionsBar",
-  "description": "Renders a set of suggested next actions the user can pick from. The selectAction action is dispatched when the user clicks an action button.",
+  "description": "Renders a set of suggested next actions the user can pick from. The selectAction action is dispatched when the user clicks a \"followup\" or \"search\" action button, and selectSearchOption when they click a \"searchOption\" one.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "next-actions-bar"
+      "const": "NextActionsBar"
+    },
+    "suggestedActions": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Bound list of selectable next-action descriptors (bound to /state/<id>/suggestedActions). Presentation data, not the dispatchable actions map.",
+      "$comment": "Named `suggestedActions` (not `actions`) so it does not collide with the reserved dispatchable `actions` map."
     },
     "state": {
       "$ref": "#/$defs/NextActionsState"
     },
     "actions": {
       "type": "object",
-      "required": ["selectAction"],
+      "required": ["selectAction", "selectSearchOption"],
       "properties": {
         "selectAction": {
           "$ref": "#/$defs/SelectActionAction"
+        },
+        "selectSearchOption": {
+          "$ref": "#/$defs/SelectSearchOptionAction"
         }
       },
       "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
-      },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -45,9 +45,9 @@
       "description": "The list of suggested actions to render. Owned exclusively by the backend; the frontend must not mutate this directly.",
       "$comment": "This schema validates the runtime state value the backend pushes to the frontend.",
       "type": "object",
-      "required": ["actions"],
+      "required": ["suggestedActions"],
       "properties": {
-        "actions": {
+        "suggestedActions": {
           "type": "array",
           "description": "Suggested actions the assistant offers the user.",
           "items": {
@@ -83,6 +83,33 @@
           "additionalProperties": false
         }
       }
+    },
+    "SelectSearchOptionAction": {
+      "title": "selectSearchOption",
+      "description": "Signals that the user selected a \"searchOption\" action. The backend runs the search it saved under optionId; text is what the user selected, so a consumer can show it.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["optionId", "text"],
+          "properties": {
+            "optionId": {
+              "type": "string",
+              "minLength": 1,
+              "description": "The optionId of the selected action, echoed unchanged."
+            },
+            "text": {
+              "type": "string",
+              "description": "The display text of the action the user selected."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
     }
   }
 }

package/schema/components/numeric-facet.schema.json

@@ -9,9 +9,44 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "numeric-facet"
+      "const": "NumericFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The index field the facet queries, bound to /state/<id>/field."
+    },
+    "displayName": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet's human-readable label, bound to /state/<id>/displayName."
+    },
+    "values": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The numeric-range facet values, bound to /state/<id>/values."
+    },
+    "customRange": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The custom range, bound to /state/<id>/customRange."
+    },
+    "hasActiveValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether at least one facet value is active, bound to /state/<id>/hasActiveValues."
+    },
+    "canShowMoreValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether more facet values can be shown, bound to /state/<id>/canShowMoreValues."
+    },
+    "canShowLessValues": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "Whether fewer facet values can be shown, bound to /state/<id>/canShowLessValues."
+    },
+    "domain": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The numeric domain (min/max) of the facet, bound to /state/<id>/domain."
     },
     "state": {
       "$ref": "#/$defs/NumericFacetState"
@@ -47,17 +82,6 @@
         }
       },
       "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
-      },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -87,8 +111,6 @@
         "values": {
           "type": "array",
           "description": "The numeric range values available for this facet.",
-          "minItems": 0,
-          "maxItems": 500,
           "items": {
             "$ref": "#/$defs/NumericFacetValue"
           }
@@ -143,8 +165,8 @@
           "description": "The number of results matching this range."
         },
         "state": {
-          "$ref": "https://schema.thermidor.coveo.com/definitions/selectable-facet-value-state.schema.json",
-          "description": "The selection state of this facet value (idle or selected; exclusion is not supported)."
+          "$ref": "https://schema.thermidor.coveo.com/definitions/facet-value-state.schema.json",
+          "description": "The selection state of this facet value."
         }
       },
       "additionalProperties": false

package/schema/components/page-size.schema.json

@@ -2,16 +2,24 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/page-size.schema.json",
   "title": "PageSize",
-  "description": "A 'Products per page' selector for a search surface. Its own componentType lets it be mounted through the A2-UI tree (one renderer per componentType). It owns the current pageSize in its state and dispatches setPageSize; the backend applies the change to the surface's paging so the pagination component re-renders from the shared view.",
+  "description": "A 'Products per page' selector for a search surface. Owns the current pageSize in its state and dispatches setPageSize.",
+  "$comment": "Its own component discriminant lets it mount through the A2-UI tree. The backend applies the change so the pagination component re-renders from the shared view.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "page-size"
+      "const": "PageSize"
+    },
+    "pageSize": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The current page size, bound to /state/<id>/pageSize via a { \"path\": ... } Data_Binding."
     },
     "state": {
       "$ref": "#/$defs/PageSizeState"
@@ -25,24 +33,14 @@
         }
       },
       "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
-      },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
   "$defs": {
     "PageSizeState": {
       "title": "PageSizeState",
-      "description": "The current page size. Owned exclusively by the backend. Kept as its own entry (keyed by this component's id) so the selector reads exactly the field it needs without depending on the pagination component's state shape.",
+      "description": "The current page size. Owned exclusively by the backend.",
+      "$comment": "Kept as its own entry (keyed by this component's id) so the selector reads only the field it needs, independent of the pagination component's state shape.",
       "type": "object",
       "required": ["pageSize"],
       "properties": {

package/schema/components/pagination.schema.json

@@ -9,36 +9,44 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "pagination"
+      "const": "Pagination"
+    },
+    "page": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The current page number, bound to /state/<id>/page via a { \"path\": ... } Data_Binding."
+    },
+    "pageSize": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The number of items per page, bound to /state/<id>/pageSize."
+    },
+    "totalEntries": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The total number of items, bound to /state/<id>/totalEntries."
+    },
+    "totalPages": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The total number of pages, bound to /state/<id>/totalPages."
     },
     "state": {
       "$ref": "#/$defs/PaginationState"
     },
     "actions": {
       "type": "object",
-      "required": ["selectPage", "setPageSize"],
+      "required": ["selectPage", "showMore"],
       "properties": {
         "selectPage": {
           "$ref": "#/$defs/SelectPageAction"
         },
-        "setPageSize": {
-          "$ref": "#/$defs/SetPageSizeAction"
+        "showMore": {
+          "$ref": "#/$defs/ShowMoreAction"
         }
       },
       "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
-      },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,
@@ -95,9 +103,9 @@
         }
       }
     },
-    "SetPageSizeAction": {
-      "title": "setPageSize",
-      "description": "Changes the number of items displayed per page.",
+    "ShowMoreAction": {
+      "title": "showMore",
+      "description": "Advances to the next page while preserving backend ownership of pagination state.",
       "allOf": [
         {
           "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
@@ -106,14 +114,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": ["pageSize"],
-          "properties": {
-            "pageSize": {
-              "type": "integer",
-              "minimum": 1,
-              "description": "The number of items to display per page."
-            }
-          },
+          "properties": {},
           "additionalProperties": false
         }
       }

package/schema/components/product-carousel.schema.json

@@ -9,9 +9,20 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "product-carousel"
+      "const": "ProductCarousel"
+    },
+    "heading": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The carousel heading, bound to /state/<id>/heading."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered list of products, bound to /state/<id>/products."
     },
     "state": {
       "$ref": "#/$defs/ProductCarouselState"
@@ -20,17 +31,6 @@
       "type": "object",
       "properties": {},
       "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
-      },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
     }
   },
   "additionalProperties": false,

package/schema/components/product-list.schema.json

@@ -9,28 +9,32 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "product-list"
+      "const": "ProductList"
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered list of products, bound to /state/<id>/products via a { \"path\": ... } Data_Binding."
     },
     "state": {
       "$ref": "#/$defs/ProductListState"
     },
     "actions": {
       "type": "object",
-      "properties": {},
-      "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "required": ["selectProducts", "productClick"],
+      "properties": {
+        "selectProducts": {
+          "$ref": "#/$defs/SelectProductsAction"
+        },
+        "productClick": {
+          "$ref": "#/$defs/ProductClickAction"
+        }
       },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "additionalProperties": false
     }
   },
   "additionalProperties": false,
@@ -50,6 +54,63 @@
         }
       },
       "additionalProperties": false
+    },
+    "SelectProductsAction": {
+      "title": "selectProducts",
+      "description": "Persists the set of products selected by the shopper.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["productIds"],
+          "properties": {
+            "productIds": {
+              "type": "array",
+              "items": {
+                "type": "string",
+                "minLength": 1
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "ProductClickAction": {
+      "title": "productClick",
+      "description": "Records a shopper clicking a product result.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["productId", "position"],
+          "properties": {
+            "productId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "name": {
+              "type": "string"
+            },
+            "price": {
+              "type": ["number", "null"]
+            },
+            "position": {
+              "type": "integer",
+              "minimum": 0
+            }
+          },
+          "additionalProperties": false
+        }
+      }
     }
   }
 }

package/schema/components/product-research-card.schema.json

@@ -0,0 +1,107 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/product-research-card.schema.json",
+  "title": "ProductResearchCard",
+  "description": "Renders a research card for a single known product: the product details alongside a short research summary and a list of concise product-education bullets. Read-only from the frontend: the backend is the sole source of truth for the product and the research content.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "ProductResearchCard"
+    },
+    "product": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The researched product, bound to /state/<id>/product."
+    },
+    "summary": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The research summary, bound to /state/<id>/summary."
+    },
+    "bullets": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The product-education bullets, bound to /state/<id>/bullets."
+    },
+    "relatedDocuments": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The related documents, bound to /state/<id>/relatedDocuments."
+    },
+    "state": {
+      "$ref": "#/$defs/ProductResearchCardState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProductResearchCardState": {
+      "title": "ProductResearchCardState",
+      "description": "The researched product, its research content, and related documents. Owned exclusively by the backend; the frontend must not mutate this directly.",
+      "$comment": "This schema validates the runtime state value the backend pushes to the frontend.",
+      "type": "object",
+      "required": ["product", "summary", "bullets"],
+      "properties": {
+        "product": {
+          "$ref": "https://schema.thermidor.coveo.com/definitions/product.schema.json"
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Short research paragraph about the product."
+        },
+        "bullets": {
+          "type": "array",
+          "minItems": 1,
+          "description": "Concise product-education bullets, in display order. Producers currently emit at most 5 bullets.",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "relatedDocuments": {
+          "type": "array",
+          "description": "Documents related to the researched product, in display order.",
+          "items": {
+            "$ref": "#/$defs/ProductResearchRelatedDocument"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "ProductResearchRelatedDocument": {
+      "title": "ProductResearchRelatedDocument",
+      "description": "A document related to the researched product.",
+      "type": "object",
+      "required": ["title"],
+      "properties": {
+        "title": {
+          "type": "string",
+          "description": "The display title of the document."
+        },
+        "clickUri": {
+          "type": "string",
+          "description": "The URI used to open the document."
+        },
+        "size": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The document size in bytes."
+        },
+        "filetype": {
+          "type": "string",
+          "description": "The document file type."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}