improve description

Author: ben-kalmus

specs/composition/common/params/Composition.yml

@@ -116,7 +116,13 @@ enableABTest:
 sortBy:
   type: string
   description: |
-    Parameter targeting the `sortingStrategy` setting set in the Composition body.
+    Indicates which sorting strategy to apply for the request.
+    The value must match one of the labels defined in the "sortingStrategy" mapping. For example, "Price (asc)", see Upsert Composition.
+    At runtime, this label is used to look up the corresponding index or replica configured in "sortingStrategy", and the query is executed using that index’s in the main injection.
+
+    In addition to "sortingStrategy", this parameter is also used to apply a matching Composition Rule that contains a condition defined to trigger on "sortBy", see Composition Rules.
+
+    If no value is provided, no sorting strategy is applied.
   default: ''
   example:
-    "Price (asc)"
+    'Price (asc)'

specs/composition/common/schemas/components/Composition.yml

@@ -17,13 +17,20 @@ composition:
     sortingStrategy:
       type: object
       description: |
-        Sorting Label to indices. Up to 20 sorting strategies can be defined.
-      example:
-        {
-          "Price (asc)": "products-low-to-high",
-          "Price (desc)": "products-high-to-low",
-        }
+        A mapping of sorting labels to the indices (or replicas) that implement those sorting rules.
+
+        Each key is the label your frontend sends at runtime (for example, "Price (asc)"), and each value is the name of the index that should be queried when that label is selected.
+        When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main injection targeted index is replaced
+        with the sorting strategy index it is mapped to.
 
+        Up to 20 sorting strategies can be defined.
+      maxItems: 20
+      additionalProperties:
+        type: string
+      example:
+        'Price (asc)': 'products-low-to-high'
+        'Price (desc)': 'products-high-to-low'
+        
   required:
     - objectID
     - behavior