DCSA Reference Documentation / Standards / Standard Releases / Commercial Schedules / Commercial Schedules v1
DCSA CS 1.0.3 - PS Conformance Scenarios
Contents
1. What is Conformance?
Conformance refers to the validation process used to assess whether an adopter’s implementation of the DCSA Commercial Schedules API adheres to the expected technical and business requirements defined by DCSA.
The objective is to ensure interoperability across carriers, shippers, freight forwarders, and solution providers by demonstrating that commercial schedules are made available and retrievable using the correct format and content through the defined endpoints.
These conformance scenarios define the certification test set for Commercial Schedules retrieval interoperability. They do not necessarily exhaustively exercise every obligation in the standard specification.
1.1. Scope
Conformance testing validates the minimum interoperability requirements exercised by the certification scenarios. Optional enrichments, producer-specific extensions, and broader semantic completeness beyond the tested scenarios are out of scope.
2. Conformance Criteria
Two conformance certification badges are available, one for each standard role:
- Schedule Producer
- Schedule Consumer
To receive a badge, adopters implementing either role must support the mandatory exchange capability of the module through GET /v1/port-schedules.
| Standard role | Business type (example) | Mandatory features to get a badge 🏅 | Optional features | Scope qualifiers |
|---|---|---|---|---|
| Schedule Producer | Ocean Carrier / Solution Provider | It is mandatory to support the following capability: Can make Port Schedules available for retrieval through GET /v1/port-schedules | May additionally support the following capability: Can include cut-off information | None |
| Schedule Consumer | Shipper / Freight Forwarder / BCO / Solution Provider | It is mandatory to support the following capability: Can retrieve Port Schedules by calling GET /v1/port-schedules on a Schedule Producer | None | None |
Standard role
The standard role for which the criteria are defined, for example: BKG (Carrier, Shipper), TNT (Event Producer, Event Consumer), OVS (Schedule Producer, Schedule Consumer), etc.
The criteria are defined per standard role. Unless explicitly stated otherwise, the same criteria apply to all adopters implementing that role, regardless of business type.
Business type
The type of business of an example adopter that may typically implement the standard role, for example: Ocean Carrier, Terminal Operator, Freight Forwarder, BCO, Shipper, Solution Provider, etc.
This column is illustrative only. It helps readers understand which kinds of organizations may implement a given role, but it does not change the certification logic.
Mandatory features to get a badge 🏅
The features of the standard that an adopter implementing a certain role must support in order to be certified as conformant. Unless otherwise specified, an adopter implementing a given role must implement all listed mandatory features in order to receive certification. When relevant, this column may also define a minimum subset of mandatory features that must be implemented, for example: “at least one of these two features or capabilities must be implemented or supported”
Optional features
The features of the standard that are meaningful enough to be mentioned in the certification details, therefore can be demonstrated, but that do not determine whether the adopter can or cannot receive certification. Optional features are included only where they provide useful additional visibility into the implementation. For example, a standard may include optional features or capabilities that enrich the implementation, add extra data, or support additional interactions, without being required for conformance certification.
Scope qualifiers
Qualifiers indicate the supported scope of a certified implementation. Scope qualifiers are used when certification can apply to different subsets of the standard, for example:
- supported service types
- supported modules
- supported business sub-scopes
This allows an adopter to be certified as conformant for correctly implementing the mandatory features, while making clear that the certification applies only to a defined subset of the standard.
3. Conformance Scenarios
The Supply parameters action prompts the adopter to provide query parameter values that the synthetic Schedule Consumer running in the conformance sandbox will use to call GET /v1/port-schedules on the adopter’s system. Unless a scenario states otherwise, the supplied values must cause the adopter’s system to return at least one Port Schedule matching the scenario.
In the Port Schedules module:
- the Schedule Producer implements
GET /v1/port-schedules - the Schedule Consumer retrieves Port Schedules by calling
GET /v1/port-scheduleson a Schedule Producer
Section 3.1 contains Schedule Producer scenarios. Section 3.2 contains Schedule Consumer scenarios.
3.1. Schedule Producer
3.1.1. Required query parameter scenario — Required
This scenario measures the conformance of Schedule Producers who implement GET /v1/port-schedules and make Port Schedules available for retrieval.
Both UNLocationCode and date are required by the endpoint.
- Supply parameters (
UNLocationCode+date) + GET Port Schedules
The adopter must provide values for UNLocationCode and date that cause the adopter’s system to return at least one Port Schedule. This scenario and the applicable mandatory validations in Section 4.1.1 must pass for the Schedule Producer badge.
3.1.2. Pagination scenario — Optional/report-only
This scenario measures pagination support for GET /v1/port-schedules.
Passing this scenario does not affect certification. When run, its result is included in the conformance report.
- Supply parameters (
UNLocationCode+date+limit) + GET Port Schedules + GET Port Schedules (UNLocationCode+date+limit+cursor)
The adopter must provide values for UNLocationCode, date, and limit such that the sandbox can retrieve at least two pages, with each page containing at least one Port Schedule.
The synthetic Schedule Consumer sends the first GET request using the supplied parameters. When additional results are available, the Schedule Producer returns a Next-Page-Cursor response header.
The sandbox then sends the second request by retaining UNLocationCode, date, and limit unchanged and adding cursor with the value returned in the first response’s Next-Page-Cursor header.
Changing or omitting the original query parameters in a subsequent pagination request does not conform to the pagination mechanism.
3.2. Schedule Consumer
3.2.1. GET scenario — Required
This scenario measures the conformance of Schedule Consumers who retrieve Port Schedules from a Schedule Producer.
- GET Port Schedules
The adopter’s system must call GET /v1/port-schedules on the synthetic Schedule Producer running in the conformance sandbox and successfully retrieve at least one Port Schedule.
4. Conformance Validations
Conformance reports indicate whether validations succeeded or failed.
Default validations, including URL, response-code, and schema validations, apply to every API exchange exercised by a scenario.
Custom validations are standard-specific rules that check business or data requirements in addition to the default technical validations.
Schedule Producer custom validations apply to the responses returned through the scenarios in Section 3.1. Schedule Consumer certification relies on default validations only.
Validation occurrence semantics
Unless a validation explicitly states otherwise:
- At least one… means that one representative root object, nested object, list, or list item in the tested response must demonstrate the stated capability.
- A nested At least one… validation applies to an occurrence used to demonstrate its parent capability.
- If present… applies to every occurrence of the stated property or object that is present in the tested response.
- Every returned object and every nested object included in the tested response remains subject to default schema validation.
- A custom validation does not require every sibling object or list item to demonstrate the same optional capability unless it explicitly states Every….
4.1. Custom validations: Schedule Producer
The mandatory validations apply to all Schedule Producer scenarios in Section 3.1.
4.1.1. Mandatory response-content validations
- At least one Port Schedule must be included in the root response array.
- At least one returned Port Schedule must contain a
vesselSchedules[]array with at least one item.
Each vesselSchedules[] item in a Port Schedule is a schedule object containing vessel, service-partner, voyage-reference, timestamp, and optional cut-off information for an arrival or departure at the requested port.
4.1.2. Optional response-content validation
These validations are used to determine whether an adopter has demonstrated support for optional response-content capabilities. If the relevant content is not present, the capability is recorded as not demonstrated. If the content is present, it must satisfy the applicable validation to be recorded as demonstrated. Failure of an optional response-content validation alone does not affect certification. All returned content remains subject to the default validations, including schema validation; a default validation failure causes the scenario in which it occurs to fail.
- Cut-off information: at least one returned Port Schedule must contain a non-empty
vesselSchedules[].cutOffTimes[]array.
4.2. Custom validations: Schedule Consumer
Schedule Consumer certification relies on default validations only. The required scenario in Section 3.2.1 passes when the Consumer’s GET request returns a valid HTTP response with the correct status code and a response body matching the standard schema.