add external source definition and runtime param

Author: ben-kalmus

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

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

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: '#/injectionSource'
     position:
       type: integer
       minimum: 0
@@ -103,3 +86,8 @@ injectedItem:
     - source
     - position
     - length
+
+injectionSource:
+  oneOf:
+    - $ref: './InjectionSource.yml#/search'
+    - $ref: './InjectionSource.yml#/external'

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

@@ -0,0 +1,37 @@
+search:
+  title: injectedItemSearchSource
+  description: Injected items will originate from a search request performed on the specified index.
+  type: object
+  additionalProperties: false
+  allOf:
+    - $ref: '#/baseSource'
+    - type: object
+      additionalProperties: false
+
+external:
+  title: injectedItemExternalSource
+  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
+  allOf:
+    - $ref: '#/baseSource'
+  properties:
+    ordering:
+      $ref: '#/externalOrdering'
+
+baseSource:
+  type: object
+  additionalProperties: false
+  properties:
+    index:
+      type: string
+      description: Composition Index name.
+      example: Products
+    params:
+      $ref: './Injection.yml#/injectedItemsQueryParameters'
+  required:
+    - index
+
+externalOrdering:
+  enum: ['default', 'user-defined']
+  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'