diff --git a/ovs/v3/OVS_v3.0.3.yaml b/ovs/v3/OVS_v3.0.3.yaml index 8070535e..e2fcfe45 100644 --- a/ovs/v3/OVS_v3.0.3.yaml +++ b/ovs/v3/OVS_v3.0.3.yaml @@ -15,7 +15,7 @@ info: This API follows the guidelines defined in version 2.0 of the API Design & Implementation Principles which can be found on the [DCSA Developer Portal](https://developer.dcsa.org/api_design) ### Changelog and Contact Us - For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ovs/v3#v302). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). + For a changelog please click [here](https://github.com/dcsaorg/DCSA-OpenAPI/tree/master/ovs/v3#v303). If you have any questions, feel free to [Contact Us](https://dcsa.org/get-involved/contact-us). API specification issued by [DCSA.org](https://dcsa.org/). contact: @@ -38,24 +38,39 @@ paths: Get a list of Schedules operationId: get-v3-service-schedules description: | - Get a list of service schedules. The result is `Vessel-Centric` - this means that the `Vessel` is in the top of the hierarchy of the response structure. A service is a heirarchical structure with the following elements: - - One or more `Services` which can contain one or more `Vessels` - - A `Vessel` which can call multiple `Ports` (`TransportCalls`). - - A `Port` (`TransportCall`) can contain one or more `TimeStamps`. + Get a list of service schedules. - 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 response is an array of `ServiceSchedule` objects. Each `ServiceSchedule` can contain one or more `VesselSchedule` objects in its `vesselSchedules` property. - **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. + The response hierarchy is: + - A `ServiceSchedule` can contain one or more `VesselSchedule` objects in `vesselSchedules`. + - A `VesselSchedule` can contain multiple `TransportCall` objects in `transportCalls`. + - A `TransportCall` represents a location in the vessel schedule. It can represent a port, optionally further specified by a terminal, or a waterway, optionally further specified by an SMDG waterway entry point. + - A `TransportCall` can contain one or more `Timestamp` objects in `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 by the `responseScope` query parameter. This means that even though a filter only matches a single `TransportCall` in a voyage, or a single `Timestamp` within a `TransportCall`, **the entire matched voyage** is returned. + + If the `carrierImportVoyageNumber` of the matched `TransportCall` differs from its `carrierExportVoyageNumber`, the **entire Voyage** for both voyage numbers is included. + + For example, when `&UNLocationCode=DEHAM` is used as a filter parameter, entire voyages containing a `TransportCall` with `UNLocationCode=DEHAM` are returned. + + **Note as of v3.0.2:** If `responseScope` is set to `MATCHED_CALLS`, only **partial voyage(s) may be returned**. If a filter only matches a single `TransportCall` in a voyage, or a single `Timestamp` within a `TransportCall`, **only the matching `TransportCalls`** are returned. + + If the `carrierImportVoyageNumber` of a `TransportCall` differs from its `carrierExportVoyageNumber`, the `TransportCall` is included when either or both voyage numbers match the filter. - 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: + For example, when `&UNLocationCode=DEHAM` is used, only `TransportCalls` with `UNLocationCode=DEHAM` are included. + + Be aware that it is possible to specify mutually exclusive filters, resulting in an empty response list. For example: ``` &vesselIMONumber=9321483&vesselName=King of the Seas ``` - If no `Vessel` exists where `vesselIMONumber` is **9321483** and `vesselName` is **King of the Seas** then the result will be an empty list + If no `Vessel` exists where `vesselIMONumber` is `9321483` and `vesselName` is `King of the Seas`, the result is an empty list. - If no `startDate` filter is provided then **3 months** prior to the request data is used. If no `endDate` filters is provided then **6 months** after the request date is used. + If no `startDate` filter is provided, **3 months** before the request date is used. If no `endDate` filter is provided, **6 months** after the request date is used. parameters: - name: carrierServiceName in: query @@ -112,7 +127,9 @@ paths: - name: carrierVoyageNumber in: query description: | - The carrier specific identifier of a `Voyage` - can be both **importVoyageNumber** and **exportVoyageNumber**. The result will only return schedules including the `Ports` where `carrierVoyageNumber` is either `carrierImportVoyageNumber` or `carrierExportVoyageNumber` + The carrier-specific identifier of a `Voyage`. It can be either the `carrierImportVoyageNumber` or the `carrierExportVoyageNumber`. + + The result will only return schedules containing `TransportCalls` where `carrierVoyageNumber` matches either `carrierImportVoyageNumber` or `carrierExportVoyageNumber`. schema: type: string maxLength: 50 @@ -120,7 +137,9 @@ paths: - name: universalVoyageReference in: query description: | - The Universal Reference of a `Voyage` - can be both **importUniversalVoyageReference** and **exportUniversalVoyageReference**. The result will only return schedules including the `Ports` where `universalVoyageReference` is either `importUniversalVoyageReference` or `exportUniversalVoyageReference` + The universal reference of a `Voyage`. It can be either the `universalImportVoyageReference` or the `universalExportVoyageReference`. + + The result will only return schedules containing `TransportCalls` where `universalVoyageReference` matches either `universalImportVoyageReference` or `universalExportVoyageReference`. schema: type: string pattern: ^\d{2}[0-9A-Z]{2}[NEWSR]$ @@ -129,7 +148,9 @@ paths: - name: UNLocationCode in: query description: | - The `UN Location Code` specifying where a port is located. Specifying this filter will only return schedules including **entire Voyages** related to this particular `UN Location Code`. + The `UN Location Code` identifying a location associated with a `TransportCall`. The location can, for example, represent a port or a waterway. + + Specifying this filter returns schedules containing entire voyages associated with the given `UNLocationCode`, subject to the selected `responseScope`. schema: type: string pattern: ^[A-Z]{2}[A-Z2-9]{3}$ @@ -155,7 +176,13 @@ paths: - name: startDate in: query description: | - The start date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or after (`≥`) the `startDate` the **entire Voyage** (import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **3 months** prior to request time. + The start date of the period for which schedule information is requested. + + If the date of any Timestamp (`ATA`, `ETA`, or `PTA`) inside a `TransportCall` is on or after (`>=`) the `startDate`, the entire voyage associated with that `TransportCall` is included, subject to the selected `responseScope`. + + Date matching is performed using the local date at the location represented by the `TransportCall`. + + If this filter is not provided, the default is **three months** before the request date. schema: type: string format: date @@ -163,7 +190,13 @@ paths: - name: endDate in: query description: | - The end date of the period for which schedule information is requested. If a date of any Timestamp (`ATA`, `ETA` or `PTA`) inside a `PortCall` matches a date on or before (`≤`) the `endDate` the **entire Voyage**(import- and export-Voyage) matching the `PortCall` will be included in the result. All matching is done towards local Date at the place of the port call. If this filter is not provided the default value is **6 months** after request time. + The end date of the period for which schedule information is requested. + + If the date of any Timestamp (`ATA`, `ETA`, or `PTA`) inside a `TransportCall` is on or before (`<=`) the `endDate`, the entire voyage associated with that `TransportCall` is included, subject to the selected `responseScope`. + + Date matching is performed using the local date at the location represented by the `TransportCall`. + + If this filter is not provided, the default is **six months** after the request date. schema: type: string format: date @@ -282,7 +315,9 @@ components: type: object title: Service Schedule description: | - The timetable of the roundtrip sequence of ports being served by a (number of) vessel(s) on a specific Proforma (schedule). Synonyms are rotation, loop, or string. A Service is defined by rotation, transit times, weekdays of departure per port, and frequencies. + The timetable for the roundtrip sequence of `TransportCalls` made by one or more vessels on a specific proforma schedule. + + A service is defined by its rotation, transit times, departure weekdays at the relevant locations, and frequency. Synonyms include rotation, loop, and string. properties: carrierServiceName: type: string @@ -314,7 +349,7 @@ components: type: object title: Vessel Schedule description: | - The timetable of departure and arrival times for each port call on the rotation of the vessel in question. + The timetable of arrival and departure times for each `TransportCall` in the rotation of the vessel. properties: vesselOperatorSMDGLinerCode: type: string @@ -389,21 +424,31 @@ components: type: object title: Transport Call description: | - A transportCall in the schedule. A transportCall can be either just a Port or further specified as a terminalCall. - - The order of the list is the sequence of the list + A **TransportCall** represents a location in the vessel schedule. + + It can represent a port, which may be further specified by a terminal, or a waterway, which may be further specified by an SMDG waterway entry point. + + One **TransportCall** with `location.locationType` set to `WWAY` represents one waterway location. When `waterwaySMDGEntryPointCode` is provided, it represents the specific waterway point identified by the combination of `UNLocationCode` and `waterwaySMDGEntryPointCode`. + + The order of the **TransportCalls** in the list defines their sequence in the vessel schedule. properties: portVisitReference: type: string maxLength: 50 description: | - The unique reference that can be used to link different `transportCallReferences` to the same port visit. The reference is provided by the port to uniquely identify a port call + The unique reference used to associate different `transportCallReferences` with the same port visit. The reference is provided by the port to identify the port call. + + This property applies only when the `TransportCall` represents a port. It is not applicable to a `TransportCall` where `location.locationType` is `WWAY` and **SHOULD** be omitted in that case. example: NLAMS1234589 transportCallReference: type: string maxLength: 100 description: | - The unique reference for a transport call. It's the vessel operator's responsibility to provide the Transport Call Reference, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + The unique reference for a **TransportCall**. It's the vessel operator's responsibility to provide the `transportCallReference`, other parties are obliged to pick it up and use it. It can take the form of Port Call References as defined in OVS Definitions Document, or alternatively a reference as defined by the vessel operator. + + For a **TransportCall** where `location.locationType` is `WWAY`, the reference identifies the scheduled call at the waterway location represented by that **TransportCall**. When `waterwaySMDGEntryPointCode` is provided, it includes that specific waterway point. + + It does not identify the complete passage through the waterway. example: SR11111X-9321483-2107W-NLAMS-ACT-1-1 carrierImportVoyageNumber: type: string @@ -439,17 +484,21 @@ components: example: 2103N location: description: | - General purpose object to capture location-related data, the location can be specified in **one** of the following ways: `UN Location Code`, a `Facility` or an `Address`. + General purpose object to capture location-related data. A location can be specified as a `UN Location Code`, an `SMDG Facility`, an `Address` or an `SMDG waterway` location. + + Consumers implemented against OVS versions that do not support the `WWAY` location type may need to be updated before processing this location type. discriminator: propertyName: locationType mapping: UNLO: "#/components/schemas/UNLocationLocation" FACS: "#/components/schemas/FacilitySMDGLocation" ADDR: "#/components/schemas/AddressLocation" + WWAY: "#/components/schemas/WaterwaySMDGLocation" oneOf: - $ref: '#/components/schemas/UNLocationLocation' - $ref: '#/components/schemas/FacilitySMDGLocation' - $ref: '#/components/schemas/AddressLocation' + - $ref: '#/components/schemas/WaterwaySMDGLocation' statusCode: type: string description: | @@ -512,6 +561,7 @@ components: example: Port of Amsterdam locationType: type: string + pattern: ^UNLO$ maxLength: 4 description: | Discriminator used to identify this as a `UNLocation` location interface. @@ -546,6 +596,7 @@ components: example: Port of Amsterdam locationType: type: string + pattern: ^FACS$ maxLength: 4 description: | Discriminator used to identify this as a `Facility Location` interface only using `SMDG` code list. @@ -589,6 +640,7 @@ components: example: Port of Amsterdam locationType: type: string + pattern: ^ADDR$ maxLength: 4 description: | Discriminator used to identify this as an `Address` location interface. @@ -642,11 +694,63 @@ components: required: - address - locationType + + WaterwaySMDGLocation: + type: object + title: Waterway SMDG Location + description: | + A waterway location identified using the [**SMDG Waterway Code List**](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). + + `UNLocationCode` identifies the waterway. When `waterwaySMDGEntryPointCode` is provided, the combination of the two values identifies a specific point on the waterway. + + If `waterwaySMDGEntryPointCode` is omitted, the location identifies only the waterway. No specific waterway point can then be inferred from an `ARRI` or `DEPA` timestamp. + + Waterway locations represent locations without loading or discharge operations and without vessel berthing. + properties: + locationName: + type: string + maxLength: 100 + description: The name of the waterway or waterway point. + example: Panama Canal + locationType: + type: string + pattern: ^WWAY$ + maxLength: 4 + description: | + Discriminator identifying this as an **SMDG waterway location**. + example: WWAY + UNLocationCode: + type: string + pattern: ^[A-Z]{2}[A-Z2-9]{3}$ + minLength: 5 + maxLength: 5 + description: | + The UN/LOCODE identifying the waterway. The pattern used must be: + + - 2 characters for the country code using [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) + - 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used + + More information is available from [UN/LOCODE](https://en.wikipedia.org/wiki/UN/LOCODE). + example: PAPCN + waterwaySMDGEntryPointCode: + type: string + maxLength: 6 + description: | + The SMDG entry-point code identifying a specific point on the waterway. + + The code is not unique by itself and must be interpreted together with `UNLocationCode`. + + This property is optional. When omitted, the location identifies the waterway but not a specific waterway point. When provided, it **MUST** contain a valid code published in the [SMDG Waterway Code List](https://smdg.org/documents/smdg-code-lists/smdg-waterway-code-list/). + example: ATL + required: + - locationType + - UNLocationCode + Timestamp: type: object title: Timestamp description: | - A timestamp for a port. + A timestamp for the location represented by the containing **TransportCall**. properties: eventTypeCode: type: string @@ -654,6 +758,12 @@ components: Identifier for type of `transportEvent` - `ARRI` (Arrived) - `DEPA` (Departed) + + For a **TransportCall** with `location.locationType` set to `WWAY`, `ARRI` means arrival at the waterway location represented by that **TransportCall**, and `DEPA` means departure from the same location. + + When `waterwaySMDGEntryPointCode` is provided, both event types refer to that specific waterway point. `DEPA` does not mean that the vessel has exited the complete waterway at the point on the opposite side. + + A carrier may publish the point at the other end as another ordered **TransportCall** with `location.locationType` set to `WWAY`. enum: - ARRI - DEPA @@ -714,11 +824,17 @@ components: maxLength: 4 default: BRTH description: | - The code to identify the specific type of facility. The following values are supported: + The code identifying the type of facility associated with the timestamp. + + Supported values: - `PBPL` (Pilot Boarding Place) - `BRTH` (Berth) - If no value is provided, `BRTH` is the default value. + For TransportCalls representing ports or facilities, `BRTH` is the default when this property is omitted. + + `facilityTypeCode` has no business meaning when the containing **TransportCall** has `location.locationType` set to `WWAY`. Providers **SHOULD** omit it for such TransportCalls. + + The `BRTH` default is retained for backwards compatibility. If schema-driven tooling materializes `BRTH` for a **TransportCall** with `location.locationType` set to `WWAY`, consumers **MUST** disregard the value and **MUST NOT** interpret it as vessel berthing. example: BRTH required: - eventClassifierCode diff --git a/ovs/v3/README.md b/ovs/v3/README.md index 40017b27..92de668d 100644 --- a/ovs/v3/README.md +++ b/ovs/v3/README.md @@ -4,6 +4,18 @@ The DCSA OVS API is documented on [**SwaggerHub**](https://app.swaggerhub.com/ap The primary purpose of this API is to specify endPoints for schedules shared between Vessel Partners. +[Release v3.0.3](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.3) +--- +A patch adding support for waterway locations in operational vessel schedules. + +- Added `WWAY` as a location discriminator value. +- Added `WaterwaySMDGLocation`. +- Added optional `waterwaySMDGEntryPointCode`. +- Clarified `ARRI` and `DEPA` semantics for waterway locations. +- Clarified that waterway locations do not represent loading, discharge, or berthing operations. +- Constrained each location schema's `locationType` using an exact pattern to resolve overlapping `oneOf` validation. +- Generalized port-only wording to cover all TransportCalls. + [Release v3.0.2 (12 June 2026)](https://app.swaggerhub.com/apis-docs/dcsaorg/DCSA_OVS/3.0.2) --- An update to allow partial schedules and add `facilityTypeCode`.