EBL 3.0: SD-2504: Improve Address description on Buyer, Seller and NotifyParties

[HenrikHL]

SD-2504: Includes the following change:

• Improve the description on the Buyer, Seller and NotifyParties on the House B/L
• add extra information about transportDocumentRefernece and ICS2 requirements

The AddressHBL object is a copy of the Address object - only difference is the description where extra information (only relevant to HBL) is added.

[qodo-code-review]

PR Compliance Guide 🔍

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Missing schema validation Description: The new description for AddressHBL introduces an ICS2 requirement implying that either streetNumber or POBox should be provided, but the schema does not enforce this with validation (e.g., oneOf with required constraints), allowing payloads that do not meet the stated requirement. EBL_v3.0.3.yaml [4286-4345] Referred Code AddressHBL: type: object title: Address House B/L description: | An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. properties: street: type: string maxLength: 70 description: The name of the street. example: Ruijggoordweg streetNumber: type: string maxLength: 50 description: The number of the street. example: '100' floor: type: string pattern: ^\S(?:.*\S)?$ maxLength: 50 description: | ... (clipped 39 lines)
Ticket Compliance
🟢	🎫 #SD-2504 🟢 Add a comment to the transport document reference in Shipping Instructions indicating it should be provided to meet ICS2 filing requirements. Add a comment to the Buyer, Seller, and Notify Parties address objects in the SI stating that either Street number or PO Box should be provided to meet ICS2 filing requirements.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	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: 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: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No auditing: The PR adds and updates OpenAPI schema descriptions and references without introducing any logging for critical actions, but as this is a schema file changes may not require audit logs. Referred Code A unique number allocated by the shipping line, for the shipper to indicate which `transportDocumentReference` should be linked with this `Shipping Instructions`. When available, the `transportDocumentReference` should be provided to meet **ICS2** filing requirements. example: HHL71800000 transportDocumentTypeCode: type: string description: | Specifies the type of the transport document - `BOL` (Bill of Lading) - `SWB` (Sea Waybill) enum: - BOL - SWB example: SWB isShippedOnBoardType: type: boolean description: | Specifies whether the Transport Document is a received for shipment, or shipped on board. example: true freightPaymentTermCode: type: string description: | An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided). ... (clipped 2378 lines) 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: No errors handled: The changes are schema description and reference updates with no executable error handling; if validation logic relies on these schemas, confirm that edge cases (e.g., missing streetNumber and POBox) are enforced at runtime. Referred Code AddressHBL: type: object title: Address House B/L description: | An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. properties: street: type: string maxLength: 70 description: The name of the street. example: Ruijggoordweg streetNumber: type: string maxLength: 50 description: The number of the street. example: '100' floor: type: string pattern: ^\S(?:.*\S)?$ maxLength: 50 description: | ... (clipped 38 lines) 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: Validation ambiguity: The new AddressHBL description states either Street number or PO Box should be provided, but the schema required list still includes street and does not enforce mutuality between streetNumber and POBox; this may require additional validation rules not visible here. Referred Code An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. properties: street: type: string maxLength: 70 description: The name of the street. example: Ruijggoordweg streetNumber: type: string maxLength: 50 description: The number of the street. example: '100' floor: type: string pattern: ^\S(?:.*\S)?$ maxLength: 50 description: | The floor of the street number. example: N/A postCode: type: string ... (clipped 34 lines) Learn more about managing compliance generic rules or creating your own custom rules

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
High-level	Avoid duplicating the Address schema Instead of creating a duplicate AddressHBL schema just to change its description, reuse the original Address schema. Apply the new description directly where Address is referenced in the Buyer, Seller, and NotifyParty schemas to avoid code duplication and maintenance issues. Examples: ebl/v3/EBL_v3.0.3.yaml [4286-4345] AddressHBL: type: object title: Address House B/L description: | An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. properties: street: type: string maxLength: 70 description: The name of the street. ... (clipped 50 lines) ebl/v3/EBL_v3.0.3.yaml [5276] $ref: '#/components/schemas/AddressHBL' Solution Walkthrough: Before: # ebl/v3/EBL_v3.0.3.yaml components: schemas: AddressHBL: # New duplicated schema type: object description: | An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. properties: street: ... streetNumber: ... # ... all other properties from Address Buyer: properties: address: $ref: '#/components/schemas/AddressHBL' # uses duplicated schema After: # ebl/v3/EBL_v3.0.3.yaml components: schemas: # No AddressHBL schema is needed. Buyer: properties: address: # Re-use existing Address schema and add/override description allOf: - $ref: '#/components/schemas/Address' description: | An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a significant design flaw (schema duplication) and proposes a standard, more maintainable solution using schema composition, which is a critical improvement.	High
Possible issue	Enforce conditional requirement in schema Enforce the conditional requirement in the AddressHBL schema that either streetNumber or POBox must be provided by using the anyOf keyword. ebl/v3/EBL_v3.0.3.yaml [4286-4344] AddressHBL: type: object title: Address House B/L description: | An object for storing address related information. Either **Street number** or **PO Box** should be provided to meet **ICS2** filing requirements. properties: street: type: string maxLength: 70 description: The name of the street. example: Ruijggoordweg streetNumber: type: string maxLength: 50 description: The number of the street. example: '100' floor: type: string pattern: ^\S(?:.*\S)?$ maxLength: 50 description: | The floor of the street number. example: N/A postCode: type: string maxLength: 10 description: The post code of the address. example: 1047 HM POBox: type: string maxLength: 20 description: A numbered box at a post office where a person or business can have mail or parcels delivered. example: '123' city: type: string pattern: ^\S(?:.*\S)?$ maxLength: 35 description: | The name of the city. example: Amsterdam stateRegion: type: string maxLength: 65 description: The name of the state/region. example: North Holland countryCode: type: string pattern: ^[A-Z]{2}$ minLength: 2 maxLength: 2 description: | The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en) **Note:** In case the `countryCode` is unknown it is possible to use the code `ZZ`. example: NL required: - street - city - countryCode + anyOf: + - required: [ streetNumber ] + - required: [ POBox ] Apply / Chat Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies a discrepancy between the schema's description and its validation rules and proposes the correct fix using anyOf to enforce the conditional requirement, which is crucial for ICS2 compliance.	Medium
More