eBL 3.0: SD-2778: Add vessel/voyage role

[HenrikHL]

User description

SD-2778: Add role to Vessel/Voyage
The role can be either MOTHER or FIRST_SEA_GOING. Adding as pseudoEnum in order to be able to modify it in the future

---

PR Type

Enhancement

---

Description

• Add role property to VesselVoyage schema

• Support two role values: FIRST_SEA_GOING and MOTHER

• Update schema descriptions across three OpenAPI files

• Enhance documentation with role usage examples

---

Diagram Walkthrough

flowchart LR
  VV["VesselVoyage Schema"] -- "adds role property" --> ROLE["role: string<br/>FIRST_SEA_GOING | MOTHER"]
  ROLE -- "applied to" --> EBL["EBL_ISS_v3.0.3.yaml<br/>EBL_v3.0.3.yaml<br/>EBL_PINT_v3.0.0.yaml"]

Loading

File Walkthrough

	Relevant files
Enhancement	EBL_ISS_v3.0.3.yaml Add role property to VesselVoyage schema                                  ebl/v3/issuance/EBL_ISS_v3.0.3.yaml Add role property to VesselVoyage component with string type and maxLength 30 Define two possible role values: FIRST_SEA_GOING and MOTHER Update component description to document role functionality Include example value MOTHER for the new property +10/-1    EBL_PINT_v3.0.0.yaml Add role property to VesselVoyage schema                                  pint/v3/EBL_PINT_v3.0.0.yaml Add role property to VesselVoyage component with string type and maxLength 30 Define two possible role values: FIRST_SEA_GOING and MOTHER Update component description to document role functionality Include example value MOTHER for the new property +10/-1    EBL_v3.0.3.yaml Add role property to VesselVoyage schema                                  ebl/v3/EBL_v3.0.3.yaml Add role property to VesselVoyage component with string type and maxLength 30 Define two possible role values: FIRST_SEA_GOING and MOTHER Update component description to document role functionality Include example value MOTHER for the new property +10/-1
Configuration changes	styleguide.json Styleguide configuration update                                                    .stoplight/styleguide.json Configuration file modified (insufficient token budget for detailed analysis) +1/-1

---

[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-2778 🟢 Add a way to tag/identify whether a vesselVoyage is the first sea-going vessel or the mother vessel within the transports / vesselVoyages structure. Remove ambiguity when multiple vesselVoyages are provided (and also clarify meaning when only one is provided).
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: Weak schema validation: The new role field is documented as having only two allowed values but is modeled as an unconstrained string (no enum/pattern), which may allow unexpected input values unless validated elsewhere. Referred Code role: type: string maxLength: 30 description: | Identifies the role of the vessel voyage within the Transport Document. Possible values are: - `FIRST_SEA_GOING` (First sea-going vessel) - `MOTHER` (mother vessel) example: MOTHER 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

[Copilot]

Pull request overview

This PR adds a role field to the VesselVoyage schema across three API specification files to support identifying vessels as either mother vessels or first sea-going vessels in transport documents.

Changes:

• Added optional role field to VesselVoyage schema with two possible values: FIRST_SEA_GOING and MOTHER
• Updated VesselVoyage description to explain the role field usage
• Implemented as a pseudo-enum (string with maxLength 30) to allow future extensibility

Reviewed changes

Copilot reviewed 3 out of 4 changed files in this pull request and generated 3 comments.

File	Description
pint/v3/EBL_PINT_v3.0.0.yaml	Added role field to VesselVoyage schema in PINT v3.0.0 specification
ebl/v3/issuance/EBL_ISS_v3.0.3.yaml	Added role field to VesselVoyage schema in issuance v3.0.3 specification
ebl/v3/EBL_v3.0.3.yaml	Added role field to VesselVoyage schema in main EBL v3.0.3 specification

---

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

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Centralize duplicated OpenAPI component definitions Refactor the duplicated VesselVoyage schema from three separate OpenAPI files into a single, common file. Then, use $ref in the original files to reference the shared component, improving maintainability. Examples: ebl/v3/issuance/EBL_ISS_v3.0.3.yaml [2557-2599] VesselVoyage: type: object title: Vessel/Voyage description: | Vessel and export voyage. The vessel can be nominated a `role` as either: first sea-going vessel or a mother vessel. properties: vesselName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 50 ... (clipped 33 lines) pint/v3/EBL_PINT_v3.0.0.yaml [3311-3353] VesselVoyage: type: object title: Vessel/Voyage description: | Vessel and export voyage. The vessel can be nominated a `role` as either: first sea-going vessel or a mother vessel. properties: vesselName: type: string pattern: ^\S(?:.*\S)?$ maxLength: 50 ... (clipped 33 lines) Solution Walkthrough: Before: // File: ebl/v3/issuance/EBL_ISS_v3.0.3.yaml components: schemas: VesselVoyage: type: object description: Vessel and export voyage... properties: ... role: type: string ... // File: pint/v3/EBL_PINT_v3.0.0.yaml components: schemas: VesselVoyage: // Identical definition is repeated here ... // File: ebl/v3/EBL_v3.0.3.yaml // ... and again here After: // NEW FILE: common/schemas.yaml components: schemas: VesselVoyage: type: object description: Vessel and export voyage... properties: ... role: type: string ... // File: ebl/v3/issuance/EBL_ISS_v3.0.3.yaml components: schemas: VesselVoyage: $ref: '../../common/schemas.yaml#/components/schemas/VesselVoyage' // Other files use the same $ref Suggestion importance[1-10]: 8 __ Why: The suggestion correctly identifies significant schema duplication introduced by the PR and proposes a standard architectural improvement that would greatly enhance long-term maintainability.	Medium
General	Enforce allowed values with enum For the role property, use the enum keyword to enforce the allowed values (FIRST_SEA_GOING, MOTHER) instead of only listing them in the description. ebl/v3/issuance/EBL_ISS_v3.0.3.yaml [2588-2595] role: type: string maxLength: 30 description: | - Identifies the role of the vessel voyage within the Transport Document. Possible values are: - - `FIRST_SEA_GOING` (First sea-going vessel) - - `MOTHER` (mother vessel) + Identifies the role of the vessel voyage within the Transport Document. + enum: + - FIRST_SEA_GOING + - MOTHER example: MOTHER Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly proposes using enum to enforce a fixed set of values, which is a best practice for API definitions that enables automated validation and improves clarity.	Medium
Update