From 187a3b7f3bcb3dbc81fef7ce15ed1a947cc4ad4c Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Fri, 15 May 2026 11:28:29 +0200 Subject: [PATCH 1/3] OVS 3.0: SD-3052: Add 'responseScope' to limit response --- ovs/v3/OVS_v3.0.2.yaml | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/ovs/v3/OVS_v3.0.2.yaml b/ovs/v3/OVS_v3.0.2.yaml index 131e115c..9e5292df 100644 --- a/ovs/v3/OVS_v3.0.2.yaml +++ b/ovs/v3/OVS_v3.0.2.yaml @@ -43,9 +43,13 @@ 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. + 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 +172,20 @@ paths: type: string format: date example: '2020-04-10' + - name: responseScope + in: query + description: | + Indicates whether the `transportCalls` arrays in the returned vessel 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: | From 23935bf0bed30d630c6ff4c2665f878c79ee1826 Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Fri, 15 May 2026 11:51:10 +0200 Subject: [PATCH 2/3] Improve sections --- ovs/v3/OVS_v3.0.2.yaml | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/ovs/v3/OVS_v3.0.2.yaml b/ovs/v3/OVS_v3.0.2.yaml index 9e5292df..60723b7b 100644 --- a/ovs/v3/OVS_v3.0.2.yaml +++ b/ovs/v3/OVS_v3.0.2.yaml @@ -43,13 +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**, 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`. + 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. + **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: From de8055f519ebdfed6eca2165c69a5d1976a5dbff Mon Sep 17 00:00:00 2001 From: "henrik.larsen@dcsa.org" Date: Fri, 15 May 2026 11:53:54 +0200 Subject: [PATCH 3/3] Change filter descrption --- ovs/v3/OVS_v3.0.2.yaml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/ovs/v3/OVS_v3.0.2.yaml b/ovs/v3/OVS_v3.0.2.yaml index 60723b7b..439e9973 100644 --- a/ovs/v3/OVS_v3.0.2.yaml +++ b/ovs/v3/OVS_v3.0.2.yaml @@ -171,7 +171,7 @@ paths: - name: responseScope in: query description: | - Indicates whether the `transportCalls` arrays in the returned vessel schedules represent full matched voyage(s) (the **default**) or only matched transport calls. Possible values are: + 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`)