BKG 2.0: SD-3132: Add Special Instructions

[HenrikHL]

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

[qodo-code-review]

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[]"]

Loading

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]

Code Review by Qodo

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

1. 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

---

2. Booking specialInstructions not string ✓ Resolved 📎 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

---

3. Empty instruction strings allowed ⊘ Outdated 🐞 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. Misleading newline example ✓ Resolved 🐞 Bug ⚙ Maintainability ⭐ New

Description

The specialInstructions example uses an unquoted YAML plain scalar containing \n, so YAML
parsers will keep it as a literal backslash+n rather than an actual newline. This can mislead
generated docs/clients into sending \n instead of real line breaks when copying the example
payload.

Code

bkg/v2/BKG_v2.0.5.yaml[3195]

+          example: Inspector on Site\nDo not book VIA Bremerhaven

Evidence

In all three locations, the example is written as an unquoted plain scalar with \n. YAML escape
sequences are only processed in double-quoted scalars (or represented via block scalars), so this
will not produce a newline in the parsed example value.

bkg/v2/BKG_v2.0.5.yaml[3187-3196]
bkg/v2/BKG_v2.0.5.yaml[3604-3613]
bkg/v2/BKG_v2.0.5.yaml[4090-4099]

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` uses `\n` inside an unquoted YAML scalar for the `example`, which YAML will not unescape. The resulting OpenAPI example value becomes the literal characters `\` and `n`, not a multiline string.

## Issue Context
This appears in three schema variants in the same file.

## Fix Focus Areas
- bkg/v2/BKG_v2.0.5.yaml[3195-3195]
- bkg/v2/BKG_v2.0.5.yaml[3612-3612]
- bkg/v2/BKG_v2.0.5.yaml[4098-4098]

## Suggested change
Use either a double-quoted scalar:
```yaml
example: "Inspector on Site\nDo not book VIA Bremerhaven"
```
(or a block scalar for readability):
```yaml
example: |
 Inspector on Site
 Do not book VIA Bremerhaven
```

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

---

5. Ambiguous order responsibility ⊘ Outdated 🐞 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]

Tip of the day

💡 Did you know, you can reply 'qodo' on any finding to push back, ask questions, or dig deeper

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

Previous review results

Review updated until commit 0cae856

Results up to commit cb53860 ⚖️ Balanced

🐞 Bugs (0) 📘 Rule violations (0) 📎 Requirement gaps (1) 🎨 UX issues (0) 🔗 Cross-repo conflicts (0) 📜 Skill insights (0)

1. 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

---

2. Booking specialInstructions not string ✓ Resolved 📎 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

---

3. Empty instruction strings allowed ⊘ Outdated 🐞 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 ⊘ Outdated 🐞 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

---

[HenrikHL]

/agentic-review

[HenrikHL]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 7b17094

[HenrikHL]

/agentic_review

[qodo-code-review]

Code review by qodo was updated up to the latest commit 0cae856