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

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

@@ -2,16 +2,28 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/product-summary.schema.json",
   "title": "ProductSummary",
-  "description": "Renders a single commerce product as a compact summary row (thumbnail, name, short description, price) for a category slot. Read-only from the frontend: the backend is the sole source of truth for the summarized product. Presentation as a compact row is expressed by this component type on the A2-UI plane, never as data in AG-UI state.",
+  "description": "Renders a single commerce product as a compact summary row (thumbnail, name, short description, price) for a category slot. Read-only from the frontend.",
+  "$comment": "Compact-row presentation is expressed by this component type on the A2-UI plane, never as data in AG-UI state.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "product-summary"
+      "const": "ProductSummary"
+    },
+    "categoryLabel": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The product category label, bound to /state/<id>/categoryLabel."
+    },
+    "product": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The single summarized product, bound to /state/<id>/product."
     },
     "state": {
       "$ref": "#/$defs/ProductSummaryState"
@@ -20,17 +32,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/query-suggestions.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/query-suggestions.schema.json",
+  "title": "QuerySuggestions",
+  "description": "Requests and renders backend-provided query completions for the active search input.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "QuerySuggestions"
+    },
+    "query": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The input query these suggestions were requested for, bound to /state/<id>/query."
+    },
+    "completions": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The query completions, bound to /state/<id>/completions."
+    },
+    "state": {
+      "$ref": "#/$defs/QuerySuggestionsState"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["fetchSuggestions"],
+      "properties": {
+        "fetchSuggestions": {
+          "$ref": "#/$defs/FetchSuggestionsAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "QuerySuggestionsState": {
+      "title": "QuerySuggestionsState",
+      "description": "The suggestion result for one query. Owned exclusively by the backend.",
+      "type": "object",
+      "required": ["query", "completions"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The input query for which these suggestions were requested."
+        },
+        "completions": {
+          "type": "array",
+          "description": "Query completions returned by the commerce service.",
+          "items": {
+            "$ref": "#/$defs/QueryCompletion"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "FetchSuggestionsAction": {
+      "title": "fetchSuggestions",
+      "description": "Fetches query completions for the current input.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "required": ["query"],
+          "properties": {
+            "query": {
+              "type": "string"
+            }
+          },
+          "additionalProperties": false
+        }
+      }
+    },
+    "QueryCompletion": {
+      "title": "QueryCompletion",
+      "description": "One query completion returned by the commerce service.",
+      "type": "object",
+      "required": ["expression"],
+      "properties": {
+        "expression": {
+          "type": "string",
+          "description": "The suggested query text."
+        },
+        "score": {
+          "type": "number",
+          "description": "The relevance score returned by the commerce service, when available."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/query-summary.schema.json

@@ -2,35 +2,53 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/components/query-summary.schema.json",
   "title": "QuerySummary",
-  "description": "Summarizes the current result window for a search surface (e.g. 'Products 1-12 of 43 for Water Sports'). Read-only from the frontend. Rather than reading three sibling components' state (search-box query, pagination page/pageSize/totalEntries, product-list count), it carries its own backend-computed aggregate so it has no cross-component coupling.",
+  "description": "Summarizes the current result window for a search surface (e.g. 'Products 1-12 of 43 for Water Sports'), says when the backend replaced the shopper's query, and dispatches the action that searches the shopper's query instead when the backend allows it.",
+  "$comment": "Carries its own backend-computed aggregate instead of reading sibling state (search box, pagination, product-list), so it has no cross-component coupling.",
   "allOf": [
     {
       "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "query-summary"
+      "const": "QuerySummary"
+    },
+    "query": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The current query string, bound to /state/<id>/query."
+    },
+    "firstIndex": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The 1-based index of the first result on the page, bound to /state/<id>/firstIndex."
+    },
+    "lastIndex": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The 1-based index of the last result on the page, bound to /state/<id>/lastIndex."
+    },
+    "totalEntries": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The total number of results, bound to /state/<id>/totalEntries."
+    },
+    "correction": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The replacement of the shopper's query, bound to /state/<id>/correction."
     },
     "state": {
       "$ref": "#/$defs/QuerySummaryState"
     },
     "actions": {
       "type": "object",
-      "properties": {},
-      "additionalProperties": false
-    },
-    "children": {
-      "type": "array",
-      "items": {
-        "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "required": ["overrideCorrection"],
+      "properties": {
+        "overrideCorrection": {
+          "$ref": "#/$defs/OverrideCorrectionAction"
+        }
       },
-      "maxItems": 1000,
-      "default": []
-    },
-    "child": {
-      "$ref": "https://schema.thermidor.coveo.com/definitions/child-ref.schema.json"
+      "additionalProperties": false
     }
   },
   "additionalProperties": false,
@@ -43,7 +61,7 @@
       "properties": {
         "query": {
           "type": "string",
-          "description": "The current query string. May be empty when the surface has no active query."
+          "description": "The query whose results are shown. May be empty when the surface has no active query."
         },
         "firstIndex": {
           "type": "integer",
@@ -59,9 +77,45 @@
           "type": "integer",
           "minimum": 0,
           "description": "The total number of results across all pages."
+        },
+        "correction": {
+          "$ref": "#/$defs/QueryCorrection"
         }
       },
       "additionalProperties": false
+    },
+    "QueryCorrection": {
+      "title": "QueryCorrection",
+      "description": "Says that the backend searched another query than the shopper's. Absent when the shopper's query was searched as typed.",
+      "type": "object",
+      "required": ["originalQuery", "cause", "canOverride"],
+      "properties": {
+        "originalQuery": {
+          "type": "string",
+          "minLength": 1,
+          "description": "The query the shopper submitted."
+        },
+        "cause": {
+          "title": "QueryCorrectionCause",
+          "type": "string",
+          "enum": ["correction", "trigger"],
+          "description": "What replaced the shopper's query: an automatic query correction, or a query trigger."
+        },
+        "canOverride": {
+          "type": "boolean",
+          "description": "Whether overrideCorrection can search the original query instead. False when searching it would replace it again, as for an automatic correction the search service applies on every search."
+        }
+      },
+      "additionalProperties": false
+    },
+    "OverrideCorrectionAction": {
+      "title": "overrideCorrection",
+      "description": "Searches the shopper's original query instead of the query that replaced it, for this search only: a later query can be replaced again. The backend reads the original query from its state and applies the action only when the correction's canOverride is true.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ]
     }
   }
 }

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

@@ -9,9 +9,40 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "component": {
       "type": "string",
-      "const": "regular-facet"
+      "const": "RegularFacet"
+    },
+    "id": {
+      "type": "string"
+    },
+    "field": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The index field the facet is built 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 facet values, bound to /state/<id>/values."
+    },
+    "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."
+    },
+    "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/RegularFacetState"
@@ -20,9 +51,7 @@
       "type": "object",
       "required": [
         "toggleSelect",
-        "toggleExclude",
         "toggleSingleSelect",
-        "toggleSingleExclude",
         "clearAllActiveValues",
         "search",
         "showMoreSearchResults",
@@ -34,15 +63,9 @@
         "toggleSelect": {
           "$ref": "#/$defs/RegularFacetToggleSelectAction"
         },
-        "toggleExclude": {
-          "$ref": "#/$defs/RegularFacetToggleExcludeAction"
-        },
         "toggleSingleSelect": {
           "$ref": "#/$defs/RegularFacetToggleSingleSelectAction"
         },
-        "toggleSingleExclude": {
-          "$ref": "#/$defs/RegularFacetToggleSingleExcludeAction"
-        },
         "clearAllActiveValues": {
           "$ref": "#/$defs/RegularFacetClearAllActiveValuesAction"
         },
@@ -63,17 +86,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,
@@ -95,19 +107,14 @@
         "field": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 255,
           "description": "The index field the facet is built on."
         },
         "displayName": {
           "type": "string",
-          "minLength": 1,
-          "maxLength": 255,
           "description": "Human-readable name for the facet."
         },
         "values": {
           "type": "array",
-          "minItems": 0,
-          "maxItems": 1000,
           "description": "The facet values available for selection.",
           "items": {
             "$ref": "#/$defs/RegularFacetValue"
@@ -115,7 +122,7 @@
         },
         "hasActiveValues": {
           "type": "boolean",
-          "description": "Whether at least one facet value is not in the idle state (i.e. selected or excluded)."
+          "description": "Whether at least one facet value is selected."
         },
         "canShowMoreValues": {
           "type": "boolean",
@@ -141,13 +148,11 @@
         "value": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 1024,
           "description": "The raw facet value."
         },
         "numberOfResults": {
           "type": "integer",
           "minimum": 0,
-          "maximum": 999999999,
           "description": "The number of results matching this facet value."
         },
         "state": {
@@ -158,15 +163,13 @@
       "additionalProperties": false
     },
     "RegularFacetSearch": {
-      "title": "RegularFacetSearch",
+      "title": "RegularFacetSearchState",
       "description": "The facet search state for a regular facet.",
       "type": "object",
       "required": ["query", "canShowMoreResults", "results"],
       "properties": {
         "query": {
           "type": "string",
-          "minLength": 0,
-          "maxLength": 1024,
           "description": "The current facet search query."
         },
         "canShowMoreResults": {
@@ -175,8 +178,6 @@
         },
         "results": {
           "type": "array",
-          "minItems": 0,
-          "maxItems": 1000,
           "description": "The current facet search results.",
           "items": {
             "$ref": "#/$defs/RegularFacetSearchResult"
@@ -194,13 +195,11 @@
         "value": {
           "type": "string",
           "minLength": 1,
-          "maxLength": 1024,
-          "description": "The raw facet value. Pass this to toggleSelect/toggleExclude to act on it."
+          "description": "The raw facet value. Pass this to toggleSelect to act on it."
         },
         "numberOfResults": {
           "type": "integer",
           "minimum": 0,
-          "maximum": 999999999,
           "description": "The number of results matching this facet search value."
         }
       },
@@ -222,7 +221,6 @@
             "value": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 1024,
               "description": "The raw facet value to toggle selection for."
             }
           },
@@ -230,30 +228,6 @@
         }
       }
     },
-    "RegularFacetToggleExcludeAction": {
-      "title": "regularFacetToggleExclude",
-      "description": "Toggles the excluded state of a facet value.",
-      "allOf": [
-        {
-          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
-        }
-      ],
-      "properties": {
-        "payload": {
-          "type": "object",
-          "required": ["value"],
-          "properties": {
-            "value": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 1024,
-              "description": "The raw facet value to toggle exclusion for."
-            }
-          },
-          "additionalProperties": false
-        }
-      }
-    },
     "RegularFacetToggleSingleSelectAction": {
       "title": "regularFacetToggleSingleSelect",
       "description": "Toggles the selected state of a facet value, deselecting all other values (single-select behavior).",
@@ -270,7 +244,6 @@
             "value": {
               "type": "string",
               "minLength": 1,
-              "maxLength": 1024,
               "description": "The raw facet value to single-select."
             }
           },
@@ -278,33 +251,9 @@
         }
       }
     },
-    "RegularFacetToggleSingleExcludeAction": {
-      "title": "regularFacetToggleSingleExclude",
-      "description": "Toggles the excluded state of a facet value, clearing all other selections/exclusions (single-exclude behavior).",
-      "allOf": [
-        {
-          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
-        }
-      ],
-      "properties": {
-        "payload": {
-          "type": "object",
-          "required": ["value"],
-          "properties": {
-            "value": {
-              "type": "string",
-              "minLength": 1,
-              "maxLength": 1024,
-              "description": "The raw facet value to single-exclude."
-            }
-          },
-          "additionalProperties": false
-        }
-      }
-    },
     "RegularFacetClearAllActiveValuesAction": {
       "title": "regularFacetClearAllActiveValues",
-      "description": "Resets all facet values to the idle state, clearing every selection and exclusion.",
+      "description": "Resets all facet values to the idle state, clearing every selection.",
       "allOf": [
         {
           "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
@@ -312,7 +261,7 @@
       ]
     },
     "RegularFacetSearchAction": {
-      "title": "search",
+      "title": "regularFacetSearch",
       "description": "Runs a facet search with the given query.",
       "allOf": [
         {
@@ -326,8 +275,6 @@
           "properties": {
             "query": {
               "type": "string",
-              "minLength": 0,
-              "maxLength": 1024,
               "description": "The facet search query to run."
             }
           },
@@ -354,7 +301,7 @@
       ]
     },
     "RegularFacetShowMoreValuesAction": {
-      "title": "showMoreValues",
+      "title": "regularFacetShowMoreValues",
       "description": "Increases the number of facet values shown.",
       "allOf": [
         {
@@ -363,7 +310,7 @@
       ]
     },
     "RegularFacetShowLessValuesAction": {
-      "title": "showLessValues",
+      "title": "regularFacetShowLessValues",
       "description": "Decreases the number of facet values shown.",
       "allOf": [
         {

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

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/search-box.schema.json",
+  "title": "SearchBox",
+  "description": "Draws the search input. What is typed and which suggestion is highlighted stay on the renderer side, which passes them to the search box's children; what submitting does is the application's.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "SearchBox"
+    },
+    "suggestionsChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The suggestions named slot: a static ComponentId of the QuerySuggestions node that draws the completions, mounted by name via children(suggestionsChild)."
+    },
+    "instantProductsChild": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+      "description": "The instant products named slot: a static ComponentId of the InstantProducts node that draws the products for the highlighted query, mounted by name via children(instantProductsChild)."
+    },
+    "state": {
+      "$ref": "#/$defs/SearchBoxState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "SearchBoxState": {
+      "title": "SearchBoxState",
+      "description": "Empty: what is typed and the highlight stay on the renderer side.",
+      "type": "object",
+      "required": [],
+      "properties": {},
+      "additionalProperties": false
+    }
+  }
+}

package/schema/components/session-shell.schema.json

@@ -0,0 +1,65 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/components/session-shell.schema.json",
+  "title": "SessionShell",
+  "description": "Root of the surface that lives for the whole session. Its children are the components that exist for the whole session; other surfaces stay independent of it. Dispatches initialize to open the session.",
+  "allOf": [
+    {
+      "$ref": "https://schema.thermidor.coveo.com/base/component.schema.json"
+    }
+  ],
+  "properties": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "const": "SessionShell"
+    },
+    "children": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/child-list.schema.json",
+      "description": "The components that exist for the whole session, 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/SessionShellState"
+    },
+    "actions": {
+      "type": "object",
+      "required": ["initialize"],
+      "properties": {
+        "initialize": {
+          "$ref": "#/$defs/InitializeAction"
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "SessionShellState": {
+      "title": "SessionShellState",
+      "description": "Empty: the shell holds no business data.",
+      "type": "object",
+      "required": [],
+      "properties": {},
+      "additionalProperties": false
+    },
+    "InitializeAction": {
+      "title": "initialize",
+      "description": "Opens the session. Sent before any component exists, with no surface id or source component, and only without a session token.",
+      "allOf": [
+        {
+          "$ref": "https://schema.thermidor.coveo.com/base/action.schema.json"
+        }
+      ],
+      "properties": {
+        "payload": {
+          "type": "object",
+          "properties": {},
+          "additionalProperties": false
+        }
+      }
+    }
+  }
+}