feat(specs): add external injection source definition and runtime parameter (#5283)

Co-authored-by: Clara Muller <[email protected]>
Co-authored-by: Pierre Millot <[email protected]>

Author: 3 people

specs/composition-full/common/params/Composition.yml

@@ -26,4 +26,42 @@ ruleContexts:
   default: []
   example: [mobile]
   x-categories:
-    - Rules
+    - Rules
+
+injectedItems:
+  type: object
+  additionalProperties:
+    $ref: '#/externalInjectedItem'
+  description: |
+    A list of extenrally injected objectID groups into from an external source.
+  default: {}
+  x-categories:
+    - Advanced
+
+externalInjectedItem:
+  type: object
+  properties:
+    items:
+      type: array
+      items:
+        title: externalInjection
+        type: object
+        additionalProperties: false
+        properties:
+          objectID:
+            type: string
+            description: An objectID injected into an external source.
+          metadata:
+            type: object
+            additionalProperties: true
+            description: |
+              User-defined key-values that will be added to the injected item in the response.
+              This is identical to Hits metadata defined in Composition or Composition Rule,
+              with the benefit of being set at runtime.
+            example: {'my-field': 'my-value'}
+        required:
+          - objectID
+        example:
+          {'objectID': 'my-object-1', 'metadata': {'my-field': 'my-value'}}
+  required:
+    - items

specs/composition-full/common/schemas/components/CompositionBehavior.yml

@@ -54,25 +54,8 @@ injectedItem:
       type: string
       description: injected Item unique identifier.
     source:
-      title: injectedItemSource
-      type: object
-      additionalProperties: false
-      properties:
-        search:
-          title: injectedItemSourceSearch
-          type: object
-          additionalProperties: false
-          properties:
-            index:
-              type: string
-              description: Composition Main Index name.
-              example: Products
-            params:
-              $ref: './Injection.yml#/injectedItemsQueryParameters'
-          required:
-            - index
-      required:
-        - search
+      description: Search source to be used to inject items into result set.
+      $ref: '#/injectedItemSource'
     position:
       type: integer
       minimum: 0
@@ -103,3 +86,8 @@ injectedItem:
     - source
     - position
     - length
+
+injectedItemSource:
+  oneOf:
+    - $ref: './InjectionSource.yml#/SearchSource'
+    - $ref: './InjectionSource.yml#/ExternalSource'

specs/composition-full/common/schemas/components/InjectionSource.yml

@@ -0,0 +1,49 @@
+SearchSource:
+  title: searchSource
+  description: Injected items will originate from a search request performed on the specified index.
+  type: object
+  additionalProperties: false
+  properties:
+    search:
+      title: search
+      type: object
+      additionalProperties: false
+      properties:
+        index:
+          type: string
+          description: Composition Index name.
+          example: Products
+        params:
+          $ref: './Injection.yml#/injectedItemsQueryParameters'
+      required:
+        - index
+  required:
+    - search
+
+ExternalSource:
+  title: externalSource
+  description: Injected items will originate from externally provided objectIDs (that must exist in the index) given at runtime in the run request payload.
+  type: object
+  additionalProperties: false
+  properties:
+    external:
+      title: external
+      type: object
+      additionalProperties: false
+      properties:
+        index:
+          type: string
+          description: Composition Index name.
+          example: Products
+        params:
+          $ref: './Injection.yml#/injectedItemsQueryParameters'
+        ordering:
+          $ref: '#/externalOrdering'
+      required:
+        - index
+  required:
+    - external
+
+externalOrdering:
+  enum: ['default', 'userDefined']
+  default: 'default'

specs/composition-full/common/schemas/requestBodies/RunParams.yml

@@ -54,4 +54,6 @@ params:
     enableABTest:
       $ref: '../../params/Composition.yml#/enableABTest'
     enableReRanking:
-      $ref: '../../params/Search.yml#/enableReRanking'
+      $ref: '../../params/Search.yml#/enableReRanking'
+    injectedItems:
+      $ref: '../../params/Composition.yml#/injectedItems'

tests/CTS/requests/composition-full/putComposition.json

@@ -61,5 +61,76 @@
         }
       }
     }
+  },
+  {
+    "parameters": {
+      "compositionID": "my-external-injection-compo",
+      "composition": {
+        "objectID": "my-external-injection-compo",
+        "name": "my first composition",
+        "behavior": {
+          "injection": {
+            "main": {
+              "source": {
+                "search": {
+                  "index": "foo"
+                }
+              }
+            },
+            "injectedItems": [
+              {
+                "key": "injectedItem1",
+                "source": {
+                  "external": {
+                    "index": "foo",
+                    "ordering": "userDefined",
+                    "params": {
+                      "filters": "brand:adidas"
+                    }
+                  }
+                },
+                "position": 2,
+                "length": 1
+              }
+            ]
+          }
+        }
+      }
+    },
+    "request": {
+      "path": "/1/compositions/my-external-injection-compo",
+      "method": "PUT",
+      "body": {
+        "objectID": "my-external-injection-compo",
+        "name": "my first composition",
+        "behavior": {
+          "injection": {
+            "main": {
+              "source": {
+                "search": {
+                  "index": "foo"
+                }
+              }
+            },
+            "injectedItems": [
+              {
+                "key": "injectedItem1",
+                "source": {
+                  "external": {
+                    "index": "foo",
+                    "ordering": "userDefined",
+                    "params": {
+                      "filters": "brand:adidas"
+                    }
+                  }
+                },
+                "position": 2,
+                "length": 1
+              }
+            ]
+          }
+        }
+      }
+    }
   }
 ]

tests/CTS/requests/composition-full/search.json

@@ -13,5 +13,54 @@
         "params": { "query": "batman" }
       }
     }
+  },
+  {
+    "parameters": {
+      "compositionID": "foo",
+      "requestBody": {
+        "params": {
+          "query": "batman",
+          "injectedItems": {
+            "injectedItem1": {
+              "items": [
+                {
+                  "objectID": "my-object-1"
+                },
+                {
+                  "objectID": "my-object-2",
+                  "metadata": {
+                    "my-key": "my-value"
+                  }
+                }
+              ]
+            }
+          }
+        }
+      }
+    },
+    "request": {
+      "path": "/1/compositions/foo/run",
+      "method": "POST",
+      "body": {
+        "params": {
+          "query": "batman",
+          "injectedItems": {
+            "injectedItem1": {
+              "items": [
+                {
+                  "objectID": "my-object-1"
+                },
+                {
+                  "objectID": "my-object-2",
+                  "metadata": {
+                    "my-key": "my-value"
+                  }
+                }
+              ]
+            }
+          }
+        }
+      }
+    }
   }
 ]