OVS 3.0: SD-3052: Add 'responseScope' to limit response

ovs/v3/OVS_v3.0.2.yaml

@@ -43,9 +43,9 @@ paths:
         - A `Vessel` which can call multiple `Ports` (`TransportCalls`).
         - A `Port` (`TransportCall`) can contain one or more `TimeStamps`.
 
-        The number of service schedules in the list can be narrowed down by providing filter parameters. The resulting payload will always include **entire voyage(s) being matched**. This means that even though a filter only matches a single `Port` in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included.
-        
-        An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.
+        The number of service schedules in the list can be narrowed down by providing filter parameters. The resulting payload will always include **entire voyage(s) being matched**, unless otherwise specified (see `responseScope` query parameter). This means that even though a filter only matches a single `Port` in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **the entire Voyage matched** is returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **entire Voyage** for both these Voyage numbers are included. An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **entire Voyages** would be listed where `DEHAM` is a `Port`.
+
+        **Note as of v3.0.2:** If `responseScope` is used with the `MATCHED_CALLS` value then only **partial voyage(s) will potentially be returned**. This means that if a filter only matches a single `Port` (`UNLocationCode`) in a `Voyage` or a single `Timestamp` within a `Port` in a `Voyage` - **only matched transportCalls** are returned. If the `carrierImportVoyageNumber` of the `Port` differs from the `carrierExportVoyageNumber` of the `Port` then the **matched transportCalls** where either one (or both) match the filter are included. An example of this is when `&UNLocationCode=DEHAM` is used as a filter parameter. In this case **transportCalls matching `DEHAM`** would be included.
 
         Be aware that it is possible to specify filters that are mutially exclusive resulting in an empty response list. An example of this could be when both using `vesselIMONumber` and `vesselName` filters at the same time:
 
@@ -168,6 +168,20 @@ paths:
             type: string
             format: date
             example: '2020-04-10'
+        - name: responseScope
+          in: query
+          description: |
+            Indicates whether the `transportCalls` arrays in the returned service schedules represent full matched voyage(s) (the **default**) or only matched transport calls. Possible values are:
+
+              - `FULL_VOYAGE` (the response includes entire voyages - which is also the default)
+              - `MATCHED_CALLS` (the response only includes matched `transportCalls`)
+
+            If omitted, the default value is `FULL_VOYAGE`.
+          schema:
+            type: string
+            maxLength: 30
+            default: FULL_VOYAGE
+            example: MATCHED_CALLS
         - name: limit
           in: query
           description: |