DCSA Reference Documentation / Standards / Standard Releases / Commercial Schedules / Archive / Commercial Schedules v1.0.3

DCSA CS 1.0.3 - P2P Conformance Scenarios

Archived copy: This immutable copy preserves Commercial Schedules v1.0.3. View the current v1 documentation.

Contents

• 1. What is Conformance?
  • 1.1. Scope
• 2. Conformance Criteria
• 3. Conformance Scenarios
  • 3.1. Schedule Producer
    • 3.1.1. Required query parameter scenario — Required
    • 3.1.2. Optional query parameter scenario — Optional/report-only
    • 3.1.3. Pagination scenario — Optional/report-only
  • 3.2. Schedule Consumer
    • 3.2.1. GET scenario — Required
• 4. Conformance Validations
  • • Validation occurrence semantics
  • 4.1. Custom validations: Schedule Producer
    • 4.1.1. Mandatory response-content validation
    • 4.1.2. Optional query-filtering evidence
    • 4.1.3. Optional response-content validations
  • 4.2. Custom validations: Schedule Consumer

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/point-to-point-routes.

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 Point-to-Point Routings available for retrieval through GET /v1/point-to-point-routes	May additionally support the following capabilities: Can include cut-off information Can include a booking routing reference (routingReference, introduced in CS 1.0.1) Can include footprint emissions per routing solution (solutionFootprint, introduced in CS 1.0.2) Can include footprint emissions per leg (legs[].footprint, introduced in CS 1.0.2)	None
Schedule Consumer	Shipper / Freight Forwarder / BCO / Solution Provider	It is mandatory to support the following capability: Can retrieve Point-to-Point Routings by calling GET /v1/point-to-point-routes 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/point-to-point-routes on the adopter’s system. Unless a scenario states otherwise, the supplied values must cause the adopter’s system to return at least one Point-to-Point Routing matching the scenario.

In the Point-to-Point Routings module:

• the Schedule Producer implements GET /v1/point-to-point-routes
• the Schedule Consumer retrieves Point-to-Point Routings by calling GET /v1/point-to-point-routes on 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/point-to-point-routes and make Point-to-Point Routings available for retrieval.

Both placeOfReceipt and placeOfDelivery are required by the endpoint.

• Supply parameters (placeOfReceipt + placeOfDelivery) + GET Point-to-Point Routings

The adopter must provide values for placeOfReceipt and placeOfDelivery that cause the adopter’s system to return at least one Point-to-Point Routing. This scenario and the applicable mandatory validations in Section 4.1.1 must pass for the Schedule Producer badge.

3.1.2. Optional query parameter scenario — Optional/report-only

This scenario measures support for optional Point-to-Point Routing filters in addition to the two required location filters.

Passing this scenario does not affect certification. When run, its result is included in the conformance report.

• Supply parameters (placeOfReceipt + placeOfDelivery + supported optional filters) + GET Point-to-Point Routings

The adopter provides valid placeOfReceipt and placeOfDelivery values and may additionally provide any supported combination of:

• departureStartDate
• departureEndDate
• arrivalStartDate
• arrivalEndDate
• maxTranshipment
• receiptTypeAtOrigin
• deliveryTypeAtDestination
• cargoType

The pagination parameters limit and cursor are tested separately in Section 3.1.3. The conformance report must record the exact optional query parameter names exercised in this scenario.

3.1.3. Pagination scenario — Optional/report-only

This scenario measures pagination support for GET /v1/point-to-point-routes.

Passing this scenario does not affect certification. When run, its result is included in the conformance report.

• Supply parameters (placeOfReceipt + placeOfDelivery + limit) + GET Point-to-Point Routings + GET Point-to-Point Routings (placeOfReceipt + placeOfDelivery + limit + cursor)

The adopter must provide values for placeOfReceipt, placeOfDelivery, and limit such that the sandbox can retrieve at least two pages, with each page containing at least one Point-to-Point Routing.

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 placeOfReceipt, placeOfDelivery, 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 Point-to-Point Routings from a Schedule Producer.

• GET Point-to-Point Routings

The adopter’s system must call GET /v1/point-to-point-routes on the synthetic Schedule Producer running in the conformance sandbox and successfully retrieve at least one Point-to-Point Routing.

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 validation applies to all Schedule Producer scenarios in Section 3.1.

4.1.1. Mandatory response-content validation

• At least one Point-to-Point Routing must be included in the root response array.

4.1.2. Optional query-filtering evidence

Optional query-filtering support is derived from the scenario in Section 3.1.2. It is reported separately from optional response-content features and does not affect certification.

4.1.3. Optional response-content validations

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 routing must contain a non-empty cutOffTimes[] array at routing level or at least one legs[] item must contain a non-empty cutOffTimes[] array.
• Booking routing reference: at least one returned routing must demonstrate the correct use of routingReference (not empty or blank).
• Footprint emissions per routing solution: at least one returned routing must demonstrate the correct use of solutionFootprint.
• Footprint emissions per leg: at least one legs[] item within at least one returned routing must demonstrate the correct use of footprint.

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.