BKG 2.0: SD-3132: Add Special Instructions by HenrikHL · Pull Request #644 · dcsaorg/DCSA-OpenAPI

HenrikHL · 2026-08-07T13:57:42Z

SD-3132: Add specialInstructions on root level and on requestedEquipment level

qodo-code-review · 2026-08-07T13:58:54Z

PR Summary by Qodo

BKG v2: add specialInstructions at booking and requestedEquipment level

✨ Enhancement 📝 Documentation 🕐 10-20 Minutes

AI Description

• Extend the BKG v2 OpenAPI schema with specialInstructions on Booking payloads.
• Add specialInstructions on requestedEquipment entries for equipment-specific notes.
• Define constraints (1–5 items, 512 chars) and require preserving item order.

Diagram

graph TD
  A["API Consumer"] --> B["BKG API v2"] --> C["Booking payload"]
  D["OpenAPI spec (BKG_v2.0.5.yaml)"] --> C["Booking payload"] --> E["specialInstructions[]"]
  D["OpenAPI spec (BKG_v2.0.5.yaml)"] --> F["RequestedEquipment"] --> E["specialInstructions[]"]

High-Level Assessment

The following are alternative approaches to this PR:

1. Extract SpecialInstructions into a reusable component schema ($ref)

➕ Avoids repeating identical array/item constraints across multiple schemas
➕ Reduces risk of future drift (e.g., maxItems or maxLength diverging)
➕ Makes documentation/validation rules consistent by construction
➖ Requires introducing a new named schema component and updating references
➖ May slightly reduce readability for consumers skimming inline definitions

2. Use a single string instead of an array (newline-delimited)

➕ Simpler payload shape and easier for some clients to serialize
➕ Avoids debates about item order across array elements
➖ Harder to validate/limit individual instruction length
➖ Less structured for UIs that want to display/edit instructions as separate entries
➖ Conflicts with the explicit requirement to preserve a list order

Recommendation: The PR’s approach (an ordered array of bounded strings) fits the need for multiple distinct instructions and explicit order preservation. Consider refactoring to a shared component schema via $ref to remove duplication across the multiple Booking-related and RequestedEquipment-related schema variants updated in this file.

Files changed (1) +107 / -0

Enhancement (1) +107 / -0

BKG_v2.0.5.yamlAdd specialInstructions to Booking and RequestedEquipment schemas +107/-0

Add specialInstructions to Booking and RequestedEquipment schemas

• Introduces a new specialInstructions field at the Booking/root level in multiple schema variants, defined as an ordered array of 1–5 strings (maxLength 512). Adds a similar specialInstructions field to requestedEquipment entries, scoped to equipment-specific notes and documented with the same ordering constraint.

bkg/v2/BKG_v2.0.5.yaml

Copilot

Pull request overview

Adds support for specialInstructions free-text notes to the Booking API v2.0.5 schema, allowing shippers to provide ordered instruction lines at both the Booking root level and per requestedEquipment.

Changes:

Introduces specialInstructions (array of 1–5 strings, max 512 chars each) on Booking-level schemas (CreateBooking, UpdateBooking, and Booking).
Introduces specialInstructions on equipment-level schemas (RequestedEquipment and RequestedEquipmentShipper).

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

qodo-code-review · 2026-08-07T14:03:29Z

Code Review by Qodo

🐞 Bugs (2) 📘 Rule violations (0) 📎 Requirement gaps (2) 📜 Skill insights (0)

1. Booking specialInstructions not string 📎 Requirement gap ≡ Correctness

Description

The specialInstructions field is defined as an array of strings at both the booking level and the
requested-equipment level, but the compliance requirement specifies a single optional free-text
string field. This schema mismatch can break or invalidate client requests that implement the
specified CreateBooking/UpdateBooking contract.

Code

bkg/v2/BKG_v2.0.5.yaml[R3187-3190]

+        specialInstructions:
+          type: array
+          minItems: 1
+          maxItems: 5

Evidence
PR Compliance ID 1 requires an optional booking-level Special Instructions field of type string,
yet the diff defines booking-level specialInstructions as type: array with items of `type:
string`, which does not satisfy the required scalar string type. Likewise, PR Compliance ID 2
requires an optional requested-equipment-level Special Instructions field of type string, but
the diff adds specialInstructions within the requested equipment structure as an array of strings,
creating the same contract mismatch and potential request validation incompatibility.
Add optional 'Special Instructions' free-text field at booking level for CreateBooking/UpdateBooking
bkg/v2/BKG_v2.0.5.yaml[3187-3206]
bkg/v2/BKG_v2.0.5.yaml[3618-3637]
bkg/v2/BKG_v2.0.5.yaml[4118-4137]
bkg/v2/BKG_v2.0.5.yaml[5464-5482]
bkg/v2/BKG_v2.0.5.yaml[5588-5606]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`specialInstructions` is currently modeled as an array of strings in the CreateBooking/UpdateBooking request schemas at both the booking level and the requested-equipment level, but compliance requires a single optional free-text field of type `string`.

## Issue Context
The SD-3132 compliance checklist specifies that `Special Instructions` must be an optional string field at the booking level (PR Compliance ID 1) and also an optional string field within the requested equipment structure (PR Compliance ID 2). The current OpenAPI/YAML schema definitions use `type: array` with string items in both locations, which can cause clients implementing the required contract to fail validation or break due to the type mismatch.

## Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[3187-3206]
- bkg/v2/BKG_v2.0.5.yaml[3618-3637]
- bkg/v2/BKG_v2.0.5.yaml[4118-4137]
- bkg/v2/BKG_v2.0.5.yaml[5464-5482]
- bkg/v2/BKG_v2.0.5.yaml[5588-5606]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

2. specialInstructions has maxLength 📎 Requirement gap ≡ Correctness

Description

The schema enforces maxLength: 512 on specialInstructions items, but the requirement explicitly
says not to enforce a maximum character length while the limit is TBC. This can cause valid longer
instructions to be rejected by schema validation.

Code

bkg/v2/BKG_v2.0.5.yaml[R3201-3204]

+          items:
+            type: string
+            maxLength: 512
+            description: |

Evidence
PR Compliance ID 3 forbids documenting or enforcing a specific maximum length for `Special
Instructions while the ticket states the limit is TBC. The diff explicitly adds maxLength: 512`
for specialInstructions items (booking level and requested equipment level).
Do not enforce a maximum character length for 'Special Instructions' until specified (TBC)
bkg/v2/BKG_v2.0.5.yaml[3201-3204]
bkg/v2/BKG_v2.0.5.yaml[3632-3635]
bkg/v2/BKG_v2.0.5.yaml[4132-4135]
bkg/v2/BKG_v2.0.5.yaml[5476-5479]
bkg/v2/BKG_v2.0.5.yaml[5600-5603]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`specialInstructions` enforces `maxLength: 512`, but compliance requires no explicit maximum length until specified.

## Issue Context
The SD-3132 compliance checklist states the maximum character length is TBC, so adding a concrete max length risks premature validation failures.

## Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[3201-3204]
- bkg/v2/BKG_v2.0.5.yaml[3632-3635]
- bkg/v2/BKG_v2.0.5.yaml[4132-4135]
- bkg/v2/BKG_v2.0.5.yaml[5476-5479]
- bkg/v2/BKG_v2.0.5.yaml[5600-5603]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

3. Empty instruction strings allowed 🐞 Bug ≡ Correctness

Description

specialInstructions items only constrain maxLength, so an array can schema-validate while
containing empty or whitespace-only strings (including newline-only entries), resulting in a
“non-empty” instructions list with no actual instruction content.

Code

bkg/v2/BKG_v2.0.5.yaml[R3201-3203]

+          items:
+            type: string
+            maxLength: 512

Evidence

The new specialInstructions.items definitions only specify type and maxLength, which allows
empty strings. In contrast, nearby free-text fields (e.g., bookingChannelReference) use a
non-whitespace pattern, demonstrating the spec’s existing approach to preventing blank values.

bkg/v2/BKG_v2.0.5.yaml[3199-3204]
bkg/v2/BKG_v2.0.5.yaml[3172-3176]
bkg/v2/BKG_v2.0.5.yaml[5464-5479]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The new `specialInstructions` array item schema only specifies `type: string` + `maxLength`, which permits empty/whitespace-only strings. Because the array also has `minItems: 1`, callers can satisfy validation while providing no meaningful instruction text.

## Issue Context
This behavior is introduced in multiple repeated schema blocks (booking-level and requestedEquipment-level). Most other “free text” fields in this spec use a non-whitespace `pattern` to ensure the value contains real content (e.g. `^\S(?:.*\S)?$`).

## Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[3187-3206]
- bkg/v2/BKG_v2.0.5.yaml[3618-3637]
- bkg/v2/BKG_v2.0.5.yaml[4118-4137]
- bkg/v2/BKG_v2.0.5.yaml[5464-5480]
- bkg/v2/BKG_v2.0.5.yaml[5588-5604]

## Suggested fix
Add a constraint ensuring at least one non-whitespace character is present while still allowing leading/trailing whitespace and embedded newlines. For example:
- `pattern: '^[\\s\\S]*\\S[\\s\\S]*$'`

Apply consistently to all `specialInstructions.items` definitions.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

4. Ambiguous order responsibility 🐞 Bug ⚙ Maintainability

Description

The specialInstructions description says order must be preserved “as by the provider of the API”,
which is ambiguous in request contexts where the shipper/consumer supplies the list and can confuse
implementers about who must preserve ordering.

Code

bkg/v2/BKG_v2.0.5.yaml[R3199-3200]

+            **Condition:** The order of the items in this array **MUST** be preserved
+            as by the provider of the API.

Evidence

The text first states the instructions are “provided by the shipper” but the ordering condition
references the “provider of the API,” creating ambiguity about responsibility and intent.

bkg/v2/BKG_v2.0.5.yaml[3192-3201]
bkg/v2/BKG_v2.0.5.yaml[5469-5476]

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
`specialInstructions` includes an ordering requirement with awkward/ambiguous phrasing ("preserved as by the provider of the API"). In request schemas, the list is provided by the consumer/shipper, while the API provider may need to preserve ordering when storing/returning.

## Issue Context
The wording appears in multiple newly added blocks at booking and requestedEquipment levels.

## Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[3192-3201]
- bkg/v2/BKG_v2.0.5.yaml[3623-3631]
- bkg/v2/BKG_v2.0.5.yaml[4123-4131]
- bkg/v2/BKG_v2.0.5.yaml[5469-5476]
- bkg/v2/BKG_v2.0.5.yaml[5593-5600]

## Suggested fix
Replace with explicit responsibility, e.g.:
- "The API provider MUST preserve the order of the items in this array." 
(or if intended differently, explicitly name consumer vs provider).

Apply consistently across all occurrences.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

Context used

✅ Tickets: 🎫 Update BKG API: Add Special Instructions [MSC request]

_{To customize comments, go to the Qodo configuration screen, or learn more in the docs.}

qodo-code-review · 2026-08-07T14:03:31Z

+        specialInstructions:
+          type: array
+          minItems: 1
+          maxItems: 5


1. Booking specialinstructions not string 📎 Requirement gap ≡ Correctness

The specialInstructions field is defined as an array of strings at both the booking level and the requested-equipment level, but the compliance requirement specifies a single optional free-text string field. This schema mismatch can break or invalidate client requests that implement the specified CreateBooking/UpdateBooking contract.

Agent Prompt

## Issue description `specialInstructions` is currently modeled as an array of strings in the CreateBooking/UpdateBooking request schemas at both the booking level and the requested-equipment level, but compliance requires a single optional free-text field of type `string`. ## Issue Context The SD-3132 compliance checklist specifies that `Special Instructions` must be an optional string field at the booking level (PR Compliance ID 1) and also an optional string field within the requested equipment structure (PR Compliance ID 2). The current OpenAPI/YAML schema definitions use `type: array` with string items in both locations, which can cause clients implementing the required contract to fail validation or break due to the type mismatch. ## Fix Focus Areas - bkg/v2/BKG_v2.0.5.yaml[3187-3206] - bkg/v2/BKG_v2.0.5.yaml[3618-3637] - bkg/v2/BKG_v2.0.5.yaml[4118-4137] - bkg/v2/BKG_v2.0.5.yaml[5464-5482] - bkg/v2/BKG_v2.0.5.yaml[5588-5606]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

qodo-code-review · 2026-08-07T14:03:31Z

+          items:
+            type: string
+            maxLength: 512
+            description: |


2. specialinstructions has maxlength 📎 Requirement gap ≡ Correctness

The schema enforces maxLength: 512 on specialInstructions items, but the requirement explicitly says not to enforce a maximum character length while the limit is TBC. This can cause valid longer instructions to be rejected by schema validation.

Agent Prompt

## Issue description `specialInstructions` enforces `maxLength: 512`, but compliance requires no explicit maximum length until specified. ## Issue Context The SD-3132 compliance checklist states the maximum character length is TBC, so adding a concrete max length risks premature validation failures. ## Fix Focus Areas - bkg/v2/BKG_v2.0.5.yaml[3201-3204] - bkg/v2/BKG_v2.0.5.yaml[3632-3635] - bkg/v2/BKG_v2.0.5.yaml[4132-4135] - bkg/v2/BKG_v2.0.5.yaml[5476-5479] - bkg/v2/BKG_v2.0.5.yaml[5600-5603]

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

qodo-code-review · 2026-08-07T14:03:31Z

+          items:
+            type: string
+            maxLength: 512


3. Empty instruction strings allowed 🐞 Bug ≡ Correctness

specialInstructions items only constrain maxLength, so an array can schema-validate while containing empty or whitespace-only strings (including newline-only entries), resulting in a “non-empty” instructions list with no actual instruction content.

Agent Prompt

## Issue description The new `specialInstructions` array item schema only specifies `type: string` + `maxLength`, which permits empty/whitespace-only strings. Because the array also has `minItems: 1`, callers can satisfy validation while providing no meaningful instruction text. ## Issue Context This behavior is introduced in multiple repeated schema blocks (booking-level and requestedEquipment-level). Most other “free text” fields in this spec use a non-whitespace `pattern` to ensure the value contains real content (e.g. `^\S(?:.*\S)?$`). ## Fix Focus Areas - bkg/v2/BKG_v2.0.5.yaml[3187-3206] - bkg/v2/BKG_v2.0.5.yaml[3618-3637] - bkg/v2/BKG_v2.0.5.yaml[4118-4137] - bkg/v2/BKG_v2.0.5.yaml[5464-5480] - bkg/v2/BKG_v2.0.5.yaml[5588-5604] ## Suggested fix Add a constraint ensuring at least one non-whitespace character is present while still allowing leading/trailing whitespace and embedded newlines. For example: - `pattern: '^[\\s\\S]*\\S[\\s\\S]*$'` Apply consistently to all `specialInstructions.items` definitions.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

qodo-code-review · 2026-08-07T14:03:31Z

+            **Condition:** The order of the items in this array **MUST** be preserved
+            as by the provider of the API.


4. Ambiguous order responsibility 🐞 Bug ⚙ Maintainability

The specialInstructions description says order must be preserved “as by the provider of the API”, which is ambiguous in request contexts where the shipper/consumer supplies the list and can confuse implementers about who must preserve ordering.

Agent Prompt

## Issue description `specialInstructions` includes an ordering requirement with awkward/ambiguous phrasing ("preserved as by the provider of the API"). In request schemas, the list is provided by the consumer/shipper, while the API provider may need to preserve ordering when storing/returning. ## Issue Context The wording appears in multiple newly added blocks at booking and requestedEquipment levels. ## Fix Focus Areas - bkg/v2/BKG_v2.0.5.yaml[3192-3201] - bkg/v2/BKG_v2.0.5.yaml[3623-3631] - bkg/v2/BKG_v2.0.5.yaml[4123-4131] - bkg/v2/BKG_v2.0.5.yaml[5469-5476] - bkg/v2/BKG_v2.0.5.yaml[5593-5600] ## Suggested fix Replace with explicit responsibility, e.g.: - "The API provider MUST preserve the order of the items in this array." (or if intended differently, explicitly name consumer vs provider). Apply consistently across all occurrences.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

BKG 2.0: SD-3132: Add Special Instructions

cb53860

HenrikHL requested a review from Copilot August 7, 2026 13:57

Copilot started reviewing on behalf of HenrikHL August 7, 2026 13:58 View session

Copilot AI reviewed Aug 7, 2026

View reviewed changes

qodo-code-review Bot reviewed Aug 7, 2026

View reviewed changes

Navigation Menu

Uh oh!

BKG 2.0: SD-3132: Add Special Instructions - #644

BKG 2.0: SD-3132: Add Special Instructions#644
HenrikHL wants to merge 1 commit into
masterfrom
SD-3132_Add-special-instructions

HenrikHL commented Aug 7, 2026 •

edited by atlassian Bot

Loading

Uh oh!

qodo-code-review Bot commented Aug 7, 2026

Uh oh!

Copilot AI left a comment

Uh oh!

qodo-code-review Bot commented Aug 7, 2026

Uh oh!

qodo-code-review Bot Aug 7, 2026

Uh oh!

qodo-code-review Bot Aug 7, 2026

Uh oh!

qodo-code-review Bot Aug 7, 2026

Uh oh!

qodo-code-review Bot Aug 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

		Condition: The order of the items in this array MUST be preserved
		as by the provider of the API.

Uh oh!

Conversation

HenrikHL commented Aug 7, 2026 • edited by atlassian Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

qodo-code-review Bot commented Aug 7, 2026

PR Summary by Qodo

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

qodo-code-review Bot commented Aug 7, 2026

Code Review by Qodo

Uh oh!

qodo-code-review Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

qodo-code-review Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

qodo-code-review Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

qodo-code-review Bot Aug 7, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

HenrikHL commented Aug 7, 2026 •

edited by atlassian Bot

Loading