EBL 3.0: SD-520: Add a description to missing objects

[HenrikHL]

User description

SD-520: Add missing descriptions

---

PR Type

Documentation

---

Description

• Add missing descriptions to schema objects

• Enhance API documentation completeness

• Cover booking, shipping, and transport objects

---

Diagram Walkthrough

flowchart LR
  A["Schema Objects"] --> B["Add Descriptions"]
  B --> C["BKG API"]
  B --> D["EBL API"]
  B --> E["PINT API"]
  C --> F["Booking Operations"]
  D --> G["Shipping Instructions"]
  E --> H["Envelope Management"]

Loading

File Walkthrough

Relevant files

Documentation

BKG_v2.0.3.yaml Add descriptions to booking-related schema objects              bkg/v2/BKG_v2.0.3.yaml Add description to CancelBookingRequest object Add description to CreateBooking object Add description to UpdateBooking object Add description to Booking object +11/-0    EBL_v3.0.2.yaml Add descriptions to EBL schema objects                                      ebl/v3/EBL_v3.0.2.yaml Add description to CancelShippingInstructionsUpdate object Add description to ApproveTransportDocument object Add description to Transports object +6/-0      EBL_ISS_v3.0.2.yaml Add descriptions to issuance schema objects                            ebl/v3/issuance/EBL_ISS_v3.0.2.yaml Add description to Transports object Add description to IssuanceError object Add description to IssuanceResponse object +6/-0      EBL_PINT_v3.0.0.yaml Add descriptions to PINT envelope schema objects                  pint/v3/EBL_PINT_v3.0.0.yaml Add description to EblEnvelope object Add description to EnvelopeManifest object Add description to EnvelopeTransferChainEntry object Add description to EnvelopeTransferStartedResponse object Add description to EnvelopeTransferFinishedResponse object Add description to Transports object +12/-0

---

[qodo-code-review]

PR Reviewer Guide 🔍

Here are some key observations to aid the review process:

🎫 Ticket compliance analysis ✅ SD-520 - PR Code Verified Compliant requirements: Add missing descriptions to schema objects flagged as lacking descriptions. Apply updates across multiple APIs (BKG v2, EBL v3, EBL Issuance v3, PINT v3). Improve API documentation completeness for booking, shipping, and transport objects. Requires further human verification: Confirm (via Spectral/CI) that no remaining objects or properties across all specs are missing descriptions. Validate consistency of terminology and capitalization across descriptions (e.g., "Confirmed Booking", "Booking amendment", "Transport(s)", "Shipping Instructions"). Check that Markdown/backticks within descriptions render correctly in the documentation site. Spot-check generated API docs for clarity and user-friendliness.

⏱️ Estimated effort to review: 2 🔵🔵⚪⚪⚪

🧪 No relevant tests

🔒 No security concerns identified

⚡ Recommended focus areas for review Wording Consistency The description under CancelShippingInstructionsUpdate uses an imperative style and backticks; consider aligning with the third-person present-tense style used elsewhere (e.g., "Cancels an update to the Shipping Instructions.") and avoid backticks unless referencing a literal field name. description: | Cancel the `Shipping Instructions` update Vague Description EnvelopeTransferStartedResponse description is not informative ("Envelope Transfer Started object"). Consider clarifying what the object represents and when it is returned (e.g., "Response returned when an envelope transfer is initiated, including identifiers needed for subsequent steps."). description: | Envelope Transfer Started object properties: Vague Description EnvelopeTransferFinishedResponse description is minimal ("Envelope Transfer Finished object"). Consider explaining its purpose and typical contents (e.g., "Response confirming an envelope transfer has completed, including final checksums/status codes."). description: | Envelope Transfer Finished object

[qodo-code-review]

PR Code Suggestions ✨

Explore these optional code suggestions:

Category	Suggestion	Impact
High-level	Bump spec patch versions Instead of modifying existing versioned specification files (e.g., BKG_v2.0.3.yaml), the PR should create new patch versions (e.g., BKG_v2.0.4.yaml) for each modified specification. This preserves version traceability and reproducibility, which is crucial even for documentation-only changes. Examples: bkg/v2/BKG_v2.0.3.yaml [2317-2321] description: | Cancels one of the following things: - A booking request (prior to a Confirmed Booking) - An amendment to a Confirmed Booking - A Confirmed Booking ebl/v3/EBL_v3.0.2.yaml [2674-2675] description: | Cancel the `Shipping Instructions` update Solution Walkthrough: Before: # The PR modifies versioned files in-place. # Example: bkg/v2/BKG_v2.0.3.yaml ... components: schemas: CancelBookingRequest: type: object title: Cancel Booking Request # description is added here oneOf: ... After: # The PR should create new patch-versioned files with the changes. # Example: Create bkg/v2/BKG_v2.0.4.yaml ... components: schemas: CancelBookingRequest: type: object title: Cancel Booking Request description: | Cancels one of the following things... oneOf: ... # The old file, bkg/v2/BKG_v2.0.3.yaml, should remain unchanged. Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies a critical process flaw in modifying published specification files, which undermines versioning integrity and reproducibility, and proposes the standard best practice.	High
More

[HenrikHL]

@palatsangeetha and @pedrocarvalhodcsa this is a FYI - merging this as it is "just" cosmetic description updates ;-)