@coveo/thermidor-schema 1.0.0-beta.3 → 1.0.0-beta.30

package/schema/components/cart.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/cart.schema.json",
+  "title": "Cart",
+  "description": "Represents a commerce cart or checkout surface. The backend owns cart state; semantic cart mutations and purchase completion are dispatched through this component.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "component": {
+      "type": "string",
+      "const": "Cart"
+    },
+    "id": {
+      "type": "string"
+    },
+    "state": {
+      "$ref": "#/$defs/CartState"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["updateCart", "purchase"],
+      "properties": {
+        "updateCart": {
+          "$ref": "#/$defs/UpdateCartAction"
+        },
+        "purchase": {
+          "$ref": "#/$defs/PurchaseAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "CartState": {
+      "title": "CartState",
+      "description": "Cart state is backend-owned. This initial contract intentionally carries no presentation fields; it provides the canonical action anchor for cart mutations and checkout completion.",
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    },
+    "UpdateCartAction": {
+      "title": "updateCart",
+      "description": "Applies a semantic item update to the cart and records the corresponding commerce cart event.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["productId", "quantity", "operation"],
+          "properties": {
+            "productId": {
+              "type": "string",
+              "minLength": 1
+            },
+            "name": {
+              "type": "string"
+            },
+            "price": {
+              "type": ["number", "null"]
+            },
+            "quantity": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "operation": {
+              "title": "CartUpdateOperation",
+              "type": "string",
+              "enum": ["add", "remove", "setQuantity"]
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "PurchaseAction": {
+      "title": "purchase",
+      "description": "Records a completed commerce transaction.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["products", "transaction"],
+          "properties": {
+            "products": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/PurchaseProduct"
+              }
+            },
+            "transaction": {
+              "$ref": "#/$defs/Transaction"
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "PurchaseProduct": {
+      "title": "PurchaseProduct",
+      "type": "object",
+      "required": ["productId", "quantity"],
+      "properties": {
+        "productId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "name": {
+          "type": "string"
+        },
+        "price": {
+          "type": ["number", "null"]
+        },
+        "quantity": {
+          "type": "integer",
+          "minimum": 1
+        }
+      },
+      "additionalProperties": false
+    },
+    "Transaction": {
+      "title": "Transaction",
+      "type": "object",
+      "required": ["id", "revenue"],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "revenue": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -9,9 +9,36 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "category-facet"
+      "const": "CategoryFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The index field the facet operates on, 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 category facet values, bound to /state/<id>/values."
+    },
+    "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."
+    },
+    "facetSearch": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The facet search state, bound to /state/<id>/facetSearch."
     },
     "state": {
       "$ref": "#/$defs/CategoryFacetState"
@@ -51,17 +78,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,
@@ -148,7 +164,6 @@
       "properties": {
         "query": {
           "type": "string",
-          "maxLength": 256,
           "description": "The current facet search query."
         },
         "canShowMoreResults": {
@@ -214,7 +229,6 @@
           "properties": {
             "query": {
               "type": "string",
-              "maxLength": 256,
               "description": "The facet search query string."
             }
           },

package/schema/components/commerce-search.schema.json

@@ -2,35 +2,47 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/commerce-search.schema.json",
   "title": "CommerceSearch",
-  "description": "Surface-root component for a commerce search surface. Its componentType carries the surface intent; it owns the surface's top-level components via children.",
+  "description": "Surface-root component for a commerce search surface. Its component discriminant carries the surface intent; it owns the surface's top-level components via named child slots and dispatches search lifecycle actions (submitQuery, restoreState, overrideCorrection).",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "commerce-search"
+      "const": "CommerceSearch"
+    },
+    "sidebarChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The sidebar named slot: a static ComponentId the renderer mounts by name via children(sidebarChild).",
+      "$comment": "Heterogeneous named-slot composition: CommerceSearch uses named ComponentId slots (sidebar, main) rather than a positional children[] array."
+    },
+    "mainChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The main-area named slot: a static ComponentId the renderer mounts by name via children(mainChild)."
     },
     "state": {
       "$ref": "#/$defs/CommerceSearchState"
     },
     "actions": {
       "type": "object",
-      "properties": {},
-      "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "required": ["submitQuery", "restoreState", "overrideCorrection"],
+      "properties": {
+        "submitQuery": {
+          "$ref": "#/$defs/SubmitQueryAction"
+        },
+        "restoreState": {
+          "$ref": "#/$defs/RestoreStateAction"
+        },
+        "overrideCorrection": {
+          "$ref": "#/$defs/OverrideCorrectionAction"
+        }
       },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "additionalProperties": false
     }
   },
   "additionalProperties": false,
@@ -40,6 +52,135 @@
       "description": "The commerce search surface state. Owned exclusively by the backend.",
       "type": "object",
       "additionalProperties": false
+    },
+    "SubmitQueryAction": {
+      "title": "submitQuery",
+      "description": "Submits a new search query.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query"],
+          "properties": {
+            "query": {
+              "type": "string",
+              "description": "The query string to submit."
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "RestoreStateAction": {
+      "title": "restoreState",
+      "description": "Restores a commerce-search surface from externally persisted search state.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query", "page", "pageSize"],
+          "properties": {
+            "query": {
+              "type": "string"
+            },
+            "page": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "pageSize": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "sortCriteria": {
+              "type": "string"
+            },
+            "facets": {
+              "type": "array",
+              "items": {
+                "$ref": "#/$defs/FacetRestore"
+              }
+            },
+            "pinnedProducts": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "OverrideCorrectionAction": {
+      "title": "overrideCorrection",
+      "description": "Re-runs a search with the shopper's original query instead of an automatic correction.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["originalQuery"],
+          "properties": {
+            "originalQuery": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "FacetRestore": {
+      "title": "FacetRestore",
+      "type": "object",
+      "required": ["facetId"],
+      "properties": {
+        "facetId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "values": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "numericRanges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/NumericRangeRestore"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "NumericRangeRestore": {
+      "title": "NumericRangeRestore",
+      "type": "object",
+      "required": ["start", "end"],
+      "properties": {
+        "start": {
+          "type": "number"
+        },
+        "end": {
+          "type": "number"
+        },
+        "endInclusive": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": false
     }
   }
 }

package/schema/components/comparison-table.schema.json

@@ -9,9 +9,28 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "comparison-table"
+      "const": "ComparisonTable"
+    },
+    "heading": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The table heading, bound to /state/<id>/heading."
+    },
+    "summary": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The AI summary text, bound to /state/<id>/summary."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The compared products, bound to /state/<id>/products."
+    },
+    "attributes": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The ordered attribute descriptors, bound to /state/<id>/attributes."
     },
     "state": {
       "$ref": "#/$defs/ComparisonTableState"
@@ -20,17 +39,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/date-facet.schema.json

@@ -9,9 +9,40 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "date-facet"
+      "const": "DateFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The commerce index field the facet operates on, 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 date-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."
     },
     "state": {
       "$ref": "#/$defs/DateFacetState"
@@ -47,17 +78,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,

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

@@ -2,16 +2,25 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/facet-manager.schema.json",
   "title": "FacetManager",
-  "description": "Manages facet ordering and cross-facet concerns. Holds the backend-determined order of facet components as state. The position of each identifier (indexed from 0) determines the facet's rendering rank. Ready to gain cross-facet actions (e.g., clear all facets, reorder) as needs arise.",
+  "description": "Manages facet ordering and cross-facet concerns. Holds the backend-determined order of facet components as state; each identifier's position (from 0) is its rendering rank.",
+  "$comment": "Ready to gain cross-facet actions (e.g. clear all facets, reorder) as needs arise.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "facet-manager"
+      "const": "FacetManager"
+    },
+    "children": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-list.schema.json",
+      "description": "The backend-determined facet order: a ChildList of ComponentId references whose position (from 0) is each facet's rendering rank.",
+      "$comment": "Homogeneous ordered-list composition: child ids are static (binder passes through unresolved), mounted in order via children(id)."
     },
     "state": {
       "$ref": "#/$defs/FacetManagerState"
@@ -20,17 +29,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/layout-stack.schema.json

@@ -2,16 +2,30 @@
   "$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": {
       "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 +34,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": {},