EBL 3.0: SD-2793: Update API description

[HenrikHL]

User description

SD-2793: Improve PINT API description
Removes wrong reference to END partyFuntionCode as DocumentParties now have specific party objects

---

PR Type

Documentation

---

Description

• Updates API documentation to reflect DocumentParties structure changes

• Replaces array notation with object notation for documentParties references

• Removes incorrect references to partyFunction END code

• Clarifies endorsee party as specific object instead of array element

---

Diagram Walkthrough

flowchart LR
  A["Old: documentParties[] array<br/>with partyFunction END"] -- "Refactored to" --> B["New: documentParties object<br/>with endorsee property"]
  C["Blank-endorsed eBL:<br/>no END in array"] -- "Updated to" --> D["no endorsee object"]
  E["To-order eBL:<br/>contains END in array"] -- "Updated to" --> F["contains endorsee object"]

Loading

File Walkthrough

Relevant files

Documentation

EBL_PINT_v3.0.0.yaml Clarify DocumentParties structure in eBL type descriptions pint/v3/EBL_PINT_v3.0.0.yaml Updated documentation for blank-endorsed eBL documents to reference documentParties object instead of array with partyFunction END code Updated documentation for to-order/negotiable eBL documents to reference endorsee document party object instead of array element with END code Changed references from documentParties[] (array notation) to documentParties (object notation) Clarified that endorsee is a specific document party object property rather than an array element +2/-2

---

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟢	🎫 #SD-2793 🟢 Update the PINT API description to remove outdated references to DocumentParty.partyFunction value END (Endorsee). Update the description to reflect that DocumentParties has a dedicated endorsee property/object (rather than modeling endorsee as an element in documentParties[]). Update the narrative rules for Blank-endorsed and To-order/Negotiable eBL documents accordingly (absence/presence of endorsee).
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Secure Logging Practices Objective: To ensure logs are useful for debugging and auditing without exposing sensitive information like PII, PHI, or cardholder data. Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed Learn more about managing compliance generic rules or creating your own custom rules
Update

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
Possible issue	Clarify contradiction in document immutability Add a note to clarify the apparent contradiction between the eBL document's immutability and the ENDORSE transaction, which modifies the endorsee. Explain that an endorsement creates a new, immutable state of the document. pint/v3/EBL_PINT_v3.0.0.yaml [20-25] The eBL document must be unchanged between different envelope transfers for the lifetime of the eBL document. The PINT API is designed to support transfer of the following types of eBL documents: 1. Straight eBL documents. This type of eBL document is defined by [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `false` 2. Blank-endorsed eBL documents. This type of eBL document is created by setting [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentParties`](#/EblEnvelope) object does not contain the `endorsee` document party object -3. To-order/Negotiable eBL documents. This type of eBL document is created by setting the [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentParties`](#/EblEnvelope) object contains the `endorsee` document party object. If the current endorsee party is also in possession of the eBL (possessor), this party can endorse some other party on the same eBL Platform (and make that other party new endorsee) by executing transaction with [`Transaction.actionCode`](#/Transaction) type `ENDORSE` (Endorsement). The DCSA PINT API support To-order/Negotiable documents, however, given that not all of the eBL solution providers support the split between possession and endorsements, this doesn't apply yet to interoperable eBL +3. To-order/Negotiable eBL documents. This type of eBL document is created by setting the [`EblEnvelope.transportDocument.isToOrder`](#/EblEnvelope) attribute to `true`, and making sure that [`EblEnvelope.transportDocument.documentParties`](#/EblEnvelope) object contains the `endorsee` document party object. If the current endorsee party is also in possession of the eBL (possessor), this party can endorse some other party on the same eBL Platform (and make that other party new endorsee) by executing transaction with [`Transaction.actionCode`](#/Transaction) type `ENDORSE` (Endorsement). + > **Note:** An `ENDORSE` transaction modifies the `endorsee` within the `transportDocument`. This should be viewed as creating a new state or version of the eBL document, which then remains immutable until the next endorsement. + The DCSA PINT API support To-order/Negotiable documents, however, given that not all of the eBL solution providers support the split between possession and endorsements, this doesn't apply yet to interoperable eBL [To ensure code accuracy, apply this suggestion manually] Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a critical logical contradiction in the documentation between the stated immutability of the eBL document and the ENDORSE action which modifies it, preventing potential implementation errors.	Medium
Update

[Copilot]

Pull request overview

This PR updates the API documentation to reflect a refactoring of the documentParties structure from an array to an object with specific properties. The changes clarify how different types of eBL documents are represented, particularly for blank-endorsed and to-order/negotiable eBLs.

Changes:

• Updated documentation to reference documentParties as an object rather than an array
• Removed incorrect references to partyFunction code END (Endorsee)
• Clarified that the endorsee is represented as a specific object property rather than an array element with a particular party function code

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.