@coveo/thermidor-schema 1.0.0-beta.1 → 1.0.0-beta.13

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

@@ -0,0 +1,70 @@
+{
+  "$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."
+    },
+    "state": {
+      "$ref": "#/$defs/ProductResearchCardState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProductResearchCardState": {
+      "title": "ProductResearchCardState",
+      "description": "The researched product and its research content. 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
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,64 @@
+{
+  "$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.",
+  "$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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "ProductSummaryState": {
+      "title": "ProductSummaryState",
+      "description": "The single product to summarize for a category slot. Owned exclusively by the backend; the frontend must not mutate this directly.",
+      "type": "object",
+      "required": ["categoryLabel", "product"],
+      "properties": {
+        "categoryLabel": {
+          "type": "string",
+          "description": "Display label of the product category this summary represents (e.g. 'Surfboard')."
+        },
+        "product": {
+          "description": "The single product to summarize, or null when no product is available for this slot.",
+          "oneOf": [
+            {
+              "$ref": "https://schema.thermidor.coveo.com/definitions/product.schema.json"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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

@@ -0,0 +1,113 @@
+{
+  "$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 and product suggestions 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."
+    },
+    "products": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The product suggestions, bound to /state/<id>/products."
+    },
+    "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", "products"],
+      "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"
+          }
+        },
+        "products": {
+          "type": "array",
+          "description": "Product suggestions returned by the commerce service.",
+          "items": {
+            "$ref": "https://schema.thermidor.coveo.com/definitions/product.schema.json"
+          }
+        }
+      },
+      "additionalProperties": false
+    },
+    "FetchSuggestionsAction": {
+      "title": "fetchSuggestions",
+      "description": "Fetches query completions and product suggestions 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

@@ -0,0 +1,76 @@
+{
+  "$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.",
+  "$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": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
+      "type": "string",
+      "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."
+    },
+    "state": {
+      "$ref": "#/$defs/QuerySummaryState"
+    },
+    "actions": {
+      "type": "object",
+      "properties": {},
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": false,
+  "$defs": {
+    "QuerySummaryState": {
+      "title": "QuerySummaryState",
+      "description": "The backend-computed aggregate for the current result window. Owned exclusively by the backend; the frontend must not mutate this directly.",
+      "type": "object",
+      "required": ["query", "firstIndex", "lastIndex", "totalEntries"],
+      "properties": {
+        "query": {
+          "type": "string",
+          "description": "The current query string. May be empty when the surface has no active query."
+        },
+        "firstIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The 1-based index of the first result on the current page."
+        },
+        "lastIndex": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The 1-based index of the last result on the current page."
+        },
+        "totalEntries": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "The total number of results across all pages."
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}

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"
@@ -125,11 +156,7 @@
       "title": "RegularFacetValue",
       "description": "A single selectable value within a regular facet.",
       "type": "object",
-      "required": [
-        "value",
-        "numberOfResults",
-        "state"
-      ],
+      "required": ["value", "numberOfResults", "state"],
       "properties": {
         "value": {
           "type": "string",
@@ -154,11 +181,7 @@
       "title": "RegularFacetSearch",
       "description": "The facet search state for a regular facet.",
       "type": "object",
-      "required": [
-        "query",
-        "canShowMoreResults",
-        "results"
-      ],
+      "required": ["query", "canShowMoreResults", "results"],
       "properties": {
         "query": {
           "type": "string",
@@ -186,10 +209,7 @@
       "title": "RegularFacetSearchResult",
       "description": "A single result returned by a regular facet search. Facet search only returns idle (unselected) values, so it carries no selection state.",
       "type": "object",
-      "required": [
-        "value",
-        "numberOfResults"
-      ],
+      "required": ["value", "numberOfResults"],
       "properties": {
         "value": {
           "type": "string",
@@ -217,9 +237,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -243,9 +261,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -269,9 +285,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -295,9 +309,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "value"
-          ],
+          "required": ["value"],
           "properties": {
             "value": {
               "type": "string",
@@ -330,9 +342,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "query"
-          ],
+          "required": ["query"],
           "properties": {
             "query": {
               "type": "string",
@@ -382,4 +392,4 @@
       ]
     }
   }
-}
+}

package/schema/components/sort.schema.json

@@ -9,18 +9,27 @@
     }
   ],
   "properties": {
-    "componentType": {
+    "id": {
+      "type": "string"
+    },
+    "component": {
       "type": "string",
-      "const": "sort"
+      "const": "Sort"
+    },
+    "appliedSort": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The currently applied sort criterion, bound to /state/<id>/appliedSort."
+    },
+    "availableSorts": {
+      "$ref": "https://schema.thermidor.coveo.com/definitions/data-binding.schema.json",
+      "description": "The available sort options, bound to /state/<id>/availableSorts."
     },
     "state": {
       "$ref": "#/$defs/SortState"
     },
     "actions": {
       "type": "object",
-      "required": [
-        "selectSort"
-      ],
+      "required": ["selectSort"],
       "properties": {
         "selectSort": {
           "$ref": "#/$defs/SelectSortAction"
@@ -35,10 +44,7 @@
       "title": "SortState",
       "description": "The current sort state. Owned exclusively by the backend.",
       "type": "object",
-      "required": [
-        "appliedSort",
-        "availableSorts"
-      ],
+      "required": ["appliedSort", "availableSorts"],
       "properties": {
         "appliedSort": {
           "$ref": "#/$defs/SortCriterion",
@@ -58,10 +64,7 @@
       "title": "SortCriterion",
       "description": "A sort criterion consisting of a named criteria and field definitions.",
       "type": "object",
-      "required": [
-        "sortCriteria",
-        "fields"
-      ],
+      "required": ["sortCriteria", "fields"],
       "properties": {
         "sortCriteria": {
           "type": "string",
@@ -85,10 +88,7 @@
       "properties": {
         "payload": {
           "type": "object",
-          "required": [
-            "sortCriteria",
-            "fields"
-          ],
+          "required": ["sortCriteria", "fields"],
           "properties": {
             "sortCriteria": {
               "type": "string",
@@ -104,4 +104,4 @@
       }
     }
   }
-}
+}

package/schema/definitions/bundle-tier.schema.json

@@ -4,7 +4,7 @@
   "title": "BundleTier",
   "description": "A tier in a product bundle, grouping product slots by price/quality level.",
   "type": "object",
-  "required": ["label", "description", "slots"],
+  "required": ["label", "description", "total", "slots"],
   "properties": {
     "label": {
       "type": "string",
@@ -14,6 +14,11 @@
       "type": "string",
       "description": "Brief description of what the tier includes."
     },
+    "total": {
+      "type": "number",
+      "minimum": 0,
+      "description": "Backend-computed total price for this tier's slots, in the request currency."
+    },
     "slots": {
       "type": "array",
       "description": "Product category slots within this tier.",
@@ -27,15 +32,15 @@
     "BundleSlot": {
       "title": "BundleSlot",
       "type": "object",
-      "required": ["categoryLabel", "surfaceRef"],
+      "required": ["categoryLabel", "childId"],
       "properties": {
         "categoryLabel": {
           "type": "string",
           "description": "Display name of the product category for this slot."
         },
-        "surfaceRef": {
+        "childId": {
           "type": "string",
-          "description": "Surface ID where this slot's products are rendered via a ProductCarousel."
+          "description": "Id of the bundle-display child product-list node that renders this slot's products. Associates the slot with its child on the A2-UI composition plane; the renderer mounts the child via children(id)."
         }
       },
       "additionalProperties": false

package/schema/definitions/child-list.schema.json

@@ -0,0 +1,32 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/child-list.schema.json",
+  "title": "ChildList",
+  "description": "The A2-UI ChildList type: how a container holds its ordered children, as a static array of ComponentId references or a template binding children to a data-model list.",
+  "$comment": "A2-UI common_types.json#/$defs/ChildList. Any child-list property MUST use this type so validators treat it as a structural link. Thermidor emits only the static array form.",
+  "oneOf": [
+    {
+      "type": "array",
+      "description": "A static, ordered list of child component ids. Order is backend-owned and meaningful for container components (e.g. facet order); referential integrity and uniqueness are owned by the backend and not enforced at parse time.",
+      "items": {
+        "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json"
+      },
+      "maxItems": 1000
+    },
+    {
+      "type": "object",
+      "description": "A template for generating a dynamic list of children from a data-model list. The componentId is the component used as the template; path is the JSON Pointer to the list of component property objects in the data model.",
+      "required": ["componentId", "path"],
+      "properties": {
+        "componentId": {
+          "$ref": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json"
+        },
+        "path": {
+          "type": "string",
+          "description": "An RFC 6901 JSON Pointer to the list of component property objects in the A2-UI data model."
+        }
+      },
+      "additionalProperties": false
+    }
+  ]
+}

package/schema/definitions/comparison-attribute.schema.json

@@ -2,13 +2,13 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/definitions/comparison-attribute.schema.json",
   "title": "ComparisonAttribute",
-  "description": "Defines an attribute (column) used in a ComparisonTable. The key is the programmatic identifier that maps to values in ComparisonProduct.values, and label is the human-readable column heading.",
+  "description": "Defines an attribute (row) used in a ComparisonTable. The key is the programmatic identifier that maps to values in each compared product's values record, and label is the human-readable row heading.",
   "type": "object",
   "required": ["key", "label"],
   "properties": {
     "key": {
       "type": "string",
-      "description": "The programmatic identifier for this attribute, used as a key in ComparisonProduct.values."
+      "description": "The programmatic identifier for this attribute, used as a key in each compared product's values record."
     },
     "label": {
       "type": "string",

package/schema/definitions/comparison-product.schema.json

@@ -2,9 +2,9 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://schema.thermidor.coveo.com/definitions/comparison-product.schema.json",
   "title": "ComparisonProduct",
-  "description": "A product entry in a comparison table, containing required identifiers and a values record mapping attribute keys to display strings.",
+  "description": "A product entry (column) in a ComparisonTable, containing required identifiers and a values record mapping attribute keys to display strings.",
   "type": "object",
-  "required": ["productId", "name", "values"],
+  "required": ["productId", "name"],
   "properties": {
     "productId": {
       "type": "string",

package/schema/definitions/component-id.schema.json

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schema.thermidor.coveo.com/definitions/component-id.schema.json",
+  "title": "ComponentId",
+  "type": "string",
+  "pattern": "^[a-z][a-z0-9-]*$",
+  "description": "A reference to the unique id of another component within the same surface. Thermidor node ids are kebab-case; the pattern narrows the A2-UI string type to that convention.",
+  "$comment": "A2-UI common_types.json#/$defs/ComponentId. Any property holding another component's id MUST use this type so validators treat it as a structural link rather than free text."
+}