Skip to content

Verifications

Note

This page is a Draft and it's not approved by the COTB

In addition to allowing third parties to propose modifications to specific properties of a LogisticsObject (See Update a Logistics Object), the ONE Record standard provides a solution for flagging anomalies, missing properties, or errors within these objects through a procedure called VerificationRequest.

Error Handling with Verification Request

The following diagram illustrates a basic data exchange process between a forwarder and a carrier, focusing on error handling using a Verification Request. The forwarder creates a LogisticsObject of type Shipment and notifies the carrier. Upon receiving the shipment, the carrier identifies any discrepancies in the goods description and reports these issues back to the forwarder using by sending a Verification object. The forwarder creates a VerificationRequest linking the Verification object sent by the carrier. Depending on the case, the forwarder acknowledges or rejects the Verification Request.

sequenceDiagram
    participant Forwarder
    participant Carrier

    Forwarder->>Forwarder: Create shipment LogisticsObject on its ONE Record server
    Forwarder->>Carrier: Notify about the creation of the shipment using notification endpoint
    Carrier->>Carrier: Review the shipment object and identify issues in goods description
    Carrier->>Forwarder: Request a verification of the incorrect goods description property
    Forwarder-->>Carrier: Response with link to VerificationRequest object
    Forwarder->>Forwarder: Acknowledge VerificationRequest and rectify the shipment object
    Forwarder->>Carrier: Notify about the update of the shipment

Guidelines for Verifications in ONE Record:

  • The hasLogisticsObject and the hasRevision allows the party to target a specific version of a logistics object
  • The hasError property is an array of Error objects. As in all other Action Requests, notifyRequestStatusChange allows to receive notification on status change.
  • Each issue or anomaly on a specific logistics object will be incapsulated into a Error object which contains two attributes: HasTitle and HasErrorDetail.
  • Should users need to convey a specific message, indicate a particular property, or transmit an error code, they can utilize the ErrorDetail object for this purpose.

Request Verification

Endpoint

POST {{baseURL}}/logistics-objects/{{logisticsObjectId}}

Request

The following HTTP header parameters MUST be present in the POST request:

Request Header Description Examples
Accept The content type that you want the HTTP response to be formatted in. application/ld+json
Content-Type The content type that is contained with the HTTP body. application/ld+json

The HTTP request body must contain a valid Verification object in the format as specified by the Content-Type in the header.

The Verification is a data classes of the ONE Record API ontology. The properties and relationships to other data classes are visualized in the following class diagram.

    classDiagram

    direction LR   

    class LogisticsObject{                
    }

    class Error{        
        + hasErrorDetail[]: ErrorDetail [1..*]
        + hasTitle: xsd:string
    }
    Error "1" --> "*" ErrorDetail

    class ErrorDetail{
        + hasCode: xsd:string  [0..1] [0..1]
        + hasMessage: xsd:string [0..1]
        + hasProperty: xsd:anyURI [0..1]
        + hasResource: xsd:anyURI [0..1]
    }


    class Verification{      
        + hasLogisticsObject: LogisticsObject
        + hasError[]: Error[1..*]        
        + hasRevision: xsd:positiveInteger        
        + notifyRequestStatusChange: xsd:boolean = FALSE
    }
    Verification "1" --> "1" LogisticsObject
    Verification "1" --> "1..*" Error

Response

A successful request MUST return a `HTTP/1.1 201 Created status code and the following HTTP headers parameters MUST be present in the response:

Header Description Example
Location The URI of the newly created VerificationRequest https://1r.example.com/action-requests/6b948f9b-b812-46ed-be39-4501453da99b
Type The type of the newly created resource as a URI https://onerecord.iata.org/ns/api#VerificationRequest

Otherwise, an Error object with ErrorDetail as response body MUST be returned with the following HTTP headers:

Header Description Example
Content-Type The content type that is contained with the HTTP body. application/ld+json
Content-Language Describes the language(s) for which the requested resource is intended. en-US

The following HTTP status codes MUST be supported:

Code Description Response body
201 The change request was correctly created No body required
400 The verification request body is invalid Error
401 Not authenticated Error
403 Not authorized to update the Logistics Object Error
404 Logistics Object not found Error
415 Unsupported Content Type, response when the client sends a POST document format that the server does not support for the resource identified by the Request-URI. Error
422 Unprocessable request, when the server understands the POST document and the syntax of the POST document appears to be valid, but the server is incapable of processing the request. Error

Security

To engage with the "Verification" endpoint, a client needs proper authentication. If requests lack proper authentication, the ONE Record server should respond with a 401 "Not Authenticated" status.

Example A1

A carrier identifies an issue on a Piece with the URI https://1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c

Request: 

POST /logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c HTTP/1.1
Host: 1r.example.com
Content-Type: application/ld+json; version=2.0.0-dev
Accept: application/ld+json; version=2.0.0-dev

{
    "@context": {
        "cargo": "https: //onerecord.iata.org/ns/cargo#",
        "api": "https: //onerecord.iata.org/ns/api#",
        "xsd": "http://www.w3.org/2001/XMLSchema"
    },
    "@type": "api:Verification",
    "api:hasLogisticsObject": {
        "@id": "https: //1r.example.com/logistics-objects/1a8ded38-1804-467c-a369-81a411416b7c"
    },
    "api:hasError": [{
            "@type": "api:Error",
            "api:hasTitle": "The gross weight is missing",
            "api:hasErrorDetail": {
                "@type": "api:ErrorDetail",
                "api:hasCode": "AWB07",
                "api:hasMessage": "weight code",
                "api:hasProperty": {
                    "@value": "https: //onerecord.iata.org/ns/cargo#grossWeight",
                    "@type": "xsd:anyURI"
                }
            }
        }, {
            "@type": "api:Error",
            "api:hasTitle": "Empty goodsDescription. Please use goodsDescription to specify the description of the cargo",
            "api:hasErrorDetail": {
                "@type": "api:ErrorDetail",
                "api:hasProperty": {
                    "@value": "https: //onerecord.iata.org/ns/cargo#goodsDescription",
                    "@type": "xsd:anyURI"
                }
            }
        }
    ],
    "api:hasRevision": {
        "@type": "http: //www.w3.org/2001/XMLSchema#positiveInteger",
        "@value": "1"
    }
}
(Verification.json)

Response: 

HTTP/1.1 201 Created
Location: https://1r.example.com/action-requests/e4cf1ea5-96fc-4025-be21-159b779e3200
Content-Type: application/ld+json; version=2.0.0-dev
Type: https://onerecord.iata.org/ns/api#VerificationRequest

see also Example A2 in Action Requests for an example of a Verification Request.

Open Issues & Discussions

Audit Trail update

Note

(under discussion). see Introduction of VerificationRequest #218

For full transparency, all VerificationRequest objects MUST be linked in the AuditTrail. For this reason the hasChangeRequest in the audit trail should be renamed into hasActionRequest and it should contains both Verification Requests and Change Requests.

ChangeRequest update

Note

(under discussion). see Introduction of VerificationRequest #218

In order to reference a VerificationRequest while requesting a Change (see Update a Logistics Object, we would like to add a new optional property in the Change object: - hasVerificationRequest : link to the VerificationRequest that caused the change.