EBL 3.0: SD-2440: Multiple eBL, Issuance, Surrender and PINT changes

bkg/v2/BKG_v2.0.3.yaml

@@ -4776,6 +4776,8 @@ components:
     IdentifyingCode:
       type: object
       title: Identifying Code
+      description: |
+        A code and value that uniquely identifies a party.
       properties:
         codeListProvider:
           type: string

ebl/v3/EBL_v3.0.2.yaml

@@ -4568,6 +4568,32 @@ components:
       required:
         - partyName
 
+    OnBehalfOfShipper:
+      type: object
+      title: On Behalf of Shipper
+      description: |
+        The party allowed to act on behalf of the shipper for documentation purposes.
+
+        **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.
+      properties:
+        partyName:
+          type: string
+          pattern: ^\S(?:.*\S)?$
+          maxLength: 70
+          description: |
+            Name of the party.
+          example: IKEA Denmark
+        address:
+          $ref: '#/components/schemas/PartyAddress'
+        identifyingCodes:
+          type: array
+          description: |
+            **Condition:** Either the `address` or a party `identifyingCode` must be provided. 
+          items:
+            $ref: '#/components/schemas/IdentifyingCode'
+      required:
+        - partyName
+
     ShipperHBL:
       type: object
       title: Shipper (House B/L)
@@ -4698,6 +4724,31 @@ components:
         - partyName
         - identifyingCodes
 
+    OnBehalfOfConsignee:
+      type: object
+      title: On Behalf of Consignee
+      description: |
+        The party allowed to act on behalf of the consignee for documentation purposes.
+
+        **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.
+      properties:
+        partyName:
+          type: string
+          pattern: ^\S(?:.*\S)?$
+          maxLength: 70
+          description: |
+            Name of the party.
+          example: IKEA Denmark
+        address:
+          $ref: '#/components/schemas/PartyAddress'
+        identifyingCodes:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/IdentifyingCode'
+      required:
+        - partyName
+
     ConsigneeShipper:
       type: object
       title: Consignee (Shipper provided)
@@ -5628,6 +5679,8 @@ components:
     IdentifyingCode:
       type: object
       title: Identifying Code
+      description: |
+        A code and value that uniquely identifies a party.
       properties:
         codeListProvider:
           type: string
@@ -8663,8 +8716,12 @@ components:
       properties:
         shipper:
           $ref: '#/components/schemas/Shipper'
+        onBehalfOfShipper:
+          $ref: '#/components/schemas/OnBehalfOfShipper'
         consignee:
           $ref: '#/components/schemas/ConsigneeShipper'
+        onBehalfOfConsignee:
+          $ref: '#/components/schemas/OnBehalfOfConsignee'
         endorsee:
           $ref: '#/components/schemas/EndorseeShipper'
         issueTo:
@@ -8734,8 +8791,12 @@ components:
       properties:
         shipper:
           $ref: '#/components/schemas/Shipper'
+        onBehalfOfShipper:
+          $ref: '#/components/schemas/OnBehalfOfShipper'
         consignee:
           $ref: '#/components/schemas/Consignee'
+        onBehalfOfConsignee:
+          $ref: '#/components/schemas/OnBehalfOfConsignee'
         endorsee:
           $ref: '#/components/schemas/Endorsee'
         issuingParty:

ebl/v3/issuance/EBL_ISS_v3.0.2.yaml

@@ -325,10 +325,14 @@ components:
     SupportingDocument:
       type: object
       title: Supporting Document
+      description: |
+        A binary document representing the visualisation of the eBL.
       properties:
         name:
           type: string
           maxLength: 100
+          description: |
+            Name of the Supporting Document
           example: Carrier rendered copy of the EBL.pdf
         content:
           type: string
@@ -438,6 +442,8 @@ components:
     IdentifyingCode:
       type: object
       title: Identifying Code
+      description: |
+        A code and value that uniquely identifies a party.
       properties:
         codeListProvider:
           type: string
@@ -2896,6 +2902,32 @@ components:
       required:
         - partyName
 
+    OnBehalfOfShipper:
+      type: object
+      title: On Behalf of Shipper
+      description: |
+        The party allowed to act on behalf of the shipper for documentation purposes.
+
+        **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.
+      properties:
+        partyName:
+          type: string
+          pattern: ^\S(?:.*\S)?$
+          maxLength: 70
+          description: |
+            Name of the party.
+          example: IKEA Denmark
+        address:
+          $ref: '#/components/schemas/PartyAddress'
+        identifyingCodes:
+          type: array
+          description: |
+            **Condition:** Either the `address` or a party `identifyingCode` must be provided. 
+          items:
+            $ref: '#/components/schemas/IdentifyingCode'
+      required:
+        - partyName
+
     Consignee:
       type: object
       title: Consignee
@@ -2981,6 +3013,31 @@ components:
         - partyName
         - identifyingCodes
 
+    OnBehalfOfConsignee:
+      type: object
+      title: On Behalf of Consignee
+      description: |
+        The party allowed to act on behalf of the consignee for documentation purposes.
+
+        **Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.
+      properties:
+        partyName:
+          type: string
+          pattern: ^\S(?:.*\S)?$
+          maxLength: 70
+          description: |
+            Name of the party.
+          example: IKEA Denmark
+        address:
+          $ref: '#/components/schemas/PartyAddress'
+        identifyingCodes:
+          type: array
+          minItems: 1
+          items:
+            $ref: '#/components/schemas/IdentifyingCode'
+      required:
+        - partyName
+
     Endorsee:
       type: object
       title: Endorsee
@@ -3382,8 +3439,12 @@ components:
       properties:
         shipper:
           $ref: '#/components/schemas/Shipper'
+        onBehalfOfShipper:
+          $ref: '#/components/schemas/OnBehalfOfShipper'
         consignee:
           $ref: '#/components/schemas/Consignee'
+        onBehalfOfConsignee:
+          $ref: '#/components/schemas/OnBehalfOfConsignee'
         endorsee:
           $ref: '#/components/schemas/Endorsee'
         issuingParty:

ebl/v3/surrender/EBL_SUR_v3.0.2.yaml

@@ -148,7 +148,22 @@ components:
     TransactionParty:
       type: object
       title: Transaction Party
-      description: Refers to a company or a legal entity.
+      description: |
+        Refers to a company or a legal entity.
+
+        **Note:** In case this object populates the `recipient` property of the `Transaction` object it is possible to use a '**No Party**' placeholder when the `actionCode` is one of the following values: `SIGN`, `BLANK ENDORSE` or `SURRENDERED` (as none of these `actionCodes` require a `recipient`). A '**No Party**' object MUST be populated with the following values:
+        ```
+          {
+            'eblPlatform': 'NONE',
+            'partyName': 'NONE',
+            'identifyingCodes': [
+              {
+                'codeListProvider': 'NONE',
+                'partyCode': 'NONE',
+              }
+            ]
+          }
+        ```
       properties:
         eblPlatform:
           type: string
@@ -173,6 +188,7 @@ components:
             - `KTNE` (KTNET)
             - `CRED` (Credore)
             - `BLOC` (BlockPeer Technologies)
+            - `NONE` (To be used as part of the '**No Party**' object when `actionCode` is `SIGN`, `BLANK ENDORSE` or `SURRENDERED`)
           example: BOLE
         partyName:
           type: string
@@ -192,13 +208,37 @@ components:
           type: array
           items:
             $ref: '#/components/schemas/TaxLegalReference'
+        representedParty:
+          $ref: '#/components/schemas/RepresentedParty'
       required:
         - partyName
         - eblPlatform
         - identifyingCodes
+
+    RepresentedParty:
+      type: object
+      title: Represented Party
+      description: The party allowed to act on behalf of the `Shipper` or `Consignee` for documentation purposes.
+      properties:
+        partyName:
+          type: string
+          pattern: ^\S(?:.*\S)?$
+          maxLength: 70
+          description: |
+            Name of the party.
+          example: Globeteam
+        identifyingCodes:
+          type: array
+          items:
+            $ref: '#/components/schemas/IdentifyingCode'
+      required:
+        - partyName
+
     EndorsementChainLink:
       type: object
       title: Endorsement Chain Link
+      description: |
+        Entry in the endorsement chain.
       properties:
         actionDateTime:
           type: string
@@ -209,20 +249,31 @@ components:
           type: string
           maxLength: 50
           description: |
-            The action performed by the party. This should be one of:
-            - `ISSUE` (The actor issued the document to the recipient)
+            The action performed by the actor. This should be one of:
+            - `ISSUE` (The actor issued the document to the recipient, who is the first possessor of the eBL, as designated by the `Issue to Party`)
             - `ENDORSE` (The actor endorsed the document to the recipient)
-            - `SIGN` (The actor signed or performed an "assignment" to the recipient)
-            - `SURRENDER_FOR_DELIVERY` (The actor requested this surrender request for delivery to the recipient)
-            - `SURRENDER_FOR_AMENDMENT` (The actor requested this surrender request for amendment to the recipient)
-            Not all actions are applicable to all surrender requests.
+            - `SIGN` (The actor signed the eBL while it was in the actor's possession)
+            - `SURRENDER_FOR_DELIVERY` (The actor requested to surrender the eBL to the recipient for delivery)
+            - `SURRENDER_FOR_AMENDMENT` (The actor requested to surrender the eBL to the recipient for amendment)
+            - `BLANK_ENDORSE` (The actor endorsed the document in blank)
+            - `ENDORSE_TO_ORDER` (The actor endorsed the document to order of the recipient, allowing the recipient to further endorse the eBL to another party)
+            - `TRANSFER` (The actor transferred the possession of the eBL to the recipient)
+            - `SURRENDERED` (The actor acknowledged that the eBL has been accepted and the lifecycle of the eBL is accomplished)
+
+            Not all actions are applicable to all surrender requests. The combination and order of endorsement chain entries may differ by eBL Solution Provider, based on their rulebook and/or bilateral agreements with carriers.
           example: ISSUE
         actor:
           $ref: '#/components/schemas/TransactionParty'
         recipient:
           $ref: '#/components/schemas/TransactionParty'
-      description: |
-        Entry in the endorsement chain.
+        signatureHash:
+          type: string
+          minLength: 64
+          maxLength: 64
+          pattern: ^[0-9a-f]+$
+          description: |
+            The SHA-256 hash of the signature applied by the eBL Solution Provider to the endorsement chain action and parameters (`actionDateTime`, `actionCode`, `actor`, `recipient` and `transportDocument`).
+          example: 20a0257b313ae08417e07f6555c4ec829a512c083f3ead16b41158018a22abe9
       required:
         - actionDateTime
         - actionCode
@@ -286,23 +337,30 @@ components:
             - `SWTP` (Switch to paper)
             - `COD` (Change of destination)
             - `SWI` (Switch BL)
+
+            In case no valid `reasonCode` exists for the `AREQ` (Requested to Surrender for Amendment) - it is possible to use the `comments` property below to add more information.
           example: SWTP
         comments:
           type: string
           pattern: ^\S(?:.*\S)?$
           maxLength: 255
-          description: Optional free text comment associated with the surrender request transaction.
+          description: |
+            Optional free text comment associated with the surrender request transaction. In case no valid `reasonCode` exists - this property can also be used to provide a reason.
           example: As requested...
         endorsementChain:
           type: array
           description: |
-           A list of one or more endorsement related actions that were performed on or after the issuance of the eBL. It is equivalent to the "back side" of the physical bill of lading. The type of actions recorded in the endorsement chain as defined by the DCSA standard are listed below:
+            A list of one or more actions that affect an eBL, starting from its issuance onward. It is equivalent to the "back side" of a physical Bill of Lading. The type of actions recorded in the endorsement chain as defined by the DCSA standard are listed below:
 
-            - **Issue:** The act of issuing an eBL i.e. making the eBL available to the receiver.
-            - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a specific named party, allowing them to claim or deal with the goods. The user in control of the eBL may endorse the eBL in their turn to another named party. Only applicable to To-Order eBL (`isToOrder=true`).
-            - **Sign:** A general-purpose signature that can be used by any party to mark their possession of the eBL. Similar to how any possessor in the physical world can put a physical signature on the paper bill of lading. The endorsement chain as defined by DCSA does not record any transfer of possession of the eBL, unless a signature is added to it.
-            - **Request Surrender for Amendment:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of amending the eBL.
-            - **Request Surrender for Delivery:** The presentation (by transfer) of the eBL to the Issuer, or another user appointed by the Issuer, by a user entitled to do so for the purpose of claiming delivery of the goods.
+            - **Issue:** The act of issuing an eBL to the `Issue to` party, meaning the designated recipient of the action (typically the shipper or their on behalf of party). 
+            - **Endorse:** The act of transferring the rights and obligations associated with the eBL to a new endorsee, meaning the designated recipient of the action, allowing them to claim or deal with the goods. The newly appointed endorsee may **NOT** further endorse the eBL to another party. Only applicable to negotiable eBL (`isToOrder=true`).
+            - **Sign:** The act of visibly marking the actor's possession of the eBL within the chain. This action has no designated recipient and can only be performed while the actor is the current possessor of the eBL, similar to how a party may sign a physical Bill of Lading while in their possession.
+            - **Request Surrender for Amendment:** The act of surrendering an eBL so that the carrier can issue an amended version. If the request is accepted, the original eBL is voided, and the amended eBL must be reissued with a new endorsement chain. This action is also used when switching the eBL to a physical document (“switch to paper”), which is treated as part of the amendment process in the DCSA standard.
+            - **Request Surrender for Delivery:** The act of surrendering an eBL to the carrier to request delivery of the goods.
+            - **Blank Endorse:** The act of transferring the rights and obligations associated with the eBL in blank, meaning that the endorsement does not specify a recipient. A party in possession of a blank endorsed eBL is allowed to claim or deal with the goods. Only applicable to negotiable eBL (`isToOrder=true`).
+            - **Endorse to Order:** The act of transferring the rights and obligations associated with the eBL to a new endorsee, meaning the designated recipient of the action, allowing them to claim or deal with the goods. The newly appointed endorsee can further endorse the eBL to another party. Only applicable to negotiable eBL (`isToOrder=true`).
+            - **Transfer:** The act of transferring the possession of the eBL to the recipient.
+            - **Surrendered:** The act of confirming that the eBL has been surrendered, meaning that its lifecycle is completed.
 
             **Note:** DCSA member carriers have agreed that the name `endorsementChain` is still the correct name for this list of actions.
           items:
@@ -314,6 +372,8 @@ components:
     IdentifyingCode:
       type: object
       title: Identifying Code
+      description: |
+        A code and value that uniquely identifies a party.
       properties:
         codeListProvider:
           type: string
@@ -345,6 +405,7 @@ components:
             - `FMC` (Federal Maritime Commission)
             - `DCSA` (Digital Container Shipping Association)
             - `ZZZ` (Mutually defined)
+            - `NONE` (To be used as part of the '**No Party**' object when `actionCode` is `SIGN`, `BLANK ENDORSE` or `SURRENDERED`)
           example: W3C
         partyCode:
           type: string
@@ -538,6 +599,8 @@ components:
     SurrenderRequestAnswer:
       type: object
       title: Surrender Request Answer
+      description: |
+        Response to the Surrender Request
       properties:
         surrenderRequestReference:
           type: string