CS 1.0: SD-2834: Add addressLines

[HenrikHL]

User description

SD-2834: Add addressLines to P2P Location and Vessel-Schedules TransportCall

---

PR Type

Enhancement

---

Description

• Add addressLines property to Location and TransportCallLocation schemas

• Support unstructured address specification as fallback option

• Include backward compatibility conditions for API v1.0.1 and earlier

• Update documentation to clarify structured vs unstructured address usage

---

Diagram Walkthrough

flowchart LR
  Location["Location Schema"]
  TransportCallLocation["TransportCallLocation Schema"]
  AddressLines["addressLines Property"]
  StructuredAddress["address Property"]
  
  Location -- "adds" --> AddressLines
  TransportCallLocation -- "adds" --> AddressLines
  AddressLines -- "complements" --> StructuredAddress

Loading

File Walkthrough

Relevant files

Enhancement

CS_v1.0.2.yaml Add unstructured addressLines to location schemas                cs/v1/CS_v1.0.2.yaml Added addressLines array property (max 5 items, 250 chars each) to Location schema Added addressLines array property (max 5 items, 250 chars each) to TransportCallLocation schema Updated Location and TransportCallLocation descriptions to document both structured and unstructured address options Added backward compatibility conditions stating addressLines cannot be used as sole location identifier in API v1.0.1 or earlier +35/-2

---

[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-2834 🔴 Add a new free-text field to the `Address` object to capture unstructured addresses.
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: 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: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Misleading description: The newly added addressLines condition text incorrectly refers to identifying the "party" instead of the location, which is misleading documentation for the schema. Referred Code addressLines: type: array maxItems: 5 description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. items: type: string maxLength: 250 description: | One line of an unstructured `Address`. example: "123 Example Rd" 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: Missing empty guard: The new addressLines items constrain length and count but do not prevent empty/whitespace-only address lines, which may allow ambiguous/low-quality input unless validated elsewhere. Referred Code addressLines: type: array maxItems: 5 description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. items: type: string maxLength: 250 description: | One line of an unstructured `Address`. example: "123 Example Rd" 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 may be weak: The new addressLines schema adds basic bounds but does not specify a non-blank pattern/minLength per line, so additional validation/sanitization may be needed in implementation to avoid accepting empty or whitespace-only lines. Referred Code addressLines: type: array maxItems: 5 description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. items: type: string maxLength: 250 description: | One line of an unstructured `Address`. example: "123 Example Rd" 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

[HenrikHL]

@emiliodcsa FYI

[Copilot]

Pull request overview

This PR adds support for unstructured address information through the addressLines property in two location-related schemas. This change enables locations to be specified using unstructured address data as an alternative to structured addresses.

Changes:

• Added addressLines array property to location schemas
• Updated documentation to reflect structured vs. unstructured address options
• Added backward compatibility conditions for API v1.0.1 consumers/providers

---

💡 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
Possible issue	Enforce identifier presence Add an anyOf constraint to the Location schema to enforce that at least one of address, UNLocationCode, or facility must be provided, preventing addressLines from being the sole identifier. cs/v1/CS_v1.0.2.yaml [1710-1751] properties: locationName: type: string facilityName: type: string address: $ref: '#/components/schemas/Address' addressLines: type: array maxItems: 5 items: type: string UNLocationCode: type: string facility: $ref: '#/components/schemas/Facility' +anyOf: + - required: ["address"] + - required: ["UNLocationCode"] + - required: ["facility"] Apply / Chat Suggestion importance[1-10]: 8 __ Why: This suggestion correctly translates a requirement from the description into a machine-enforceable schema rule using anyOf. This significantly improves the API's robustness by preventing invalid data combinations that are only documented as text.	Medium
High-level	Define addressLines as a reusable schema Extract the duplicated addressLines property definition from the Location and TransportCallLocation schemas into a new, reusable schema to improve maintainability. Examples: cs/v1/CS_v1.0.2.yaml [1724-1736] addressLines: type: array maxItems: 5 description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. items: type: string maxLength: 250 ... (clipped 3 lines) cs/v1/CS_v1.0.2.yaml [1779-1791] addressLines: type: array maxItems: 5 description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. items: type: string maxLength: 250 ... (clipped 3 lines) Solution Walkthrough: Before: # In cs/v1/CS_v1.0.2.yaml ... Location: properties: ... addressLines: # Duplicated definition type: array maxItems: 5 description: | Unstructured address lines... items: type: string maxLength: 250 ... TransportCallLocation: properties: ... addressLines: # Duplicated definition type: array maxItems: 5 ... After: # In cs/v1/CS_v1.0.2.yaml components: schemas: AddressLines: # New reusable schema type: array maxItems: 5 description: | Unstructured address lines... items: type: string maxLength: 250 Location: properties: ... addressLines: $ref: '#/components/schemas/AddressLines' TransportCallLocation: properties: ... addressLines: $ref: '#/components/schemas/AddressLines' Suggestion importance[1-10]: 6 __ Why: The suggestion correctly identifies duplicated schema definitions and proposes a valid refactoring to improve maintainability, which is a good practice for API specifications.	Low
General	Add validation for address lines Add validation to the addressLines property by setting minItems: 1 and adding a pattern to the string items to prevent empty or whitespace-only values. cs/v1/CS_v1.0.2.yaml [1724-1736] addressLines: type: array maxItems: 5 + minItems: 1 description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. items: type: string maxLength: 250 + pattern: ^\S(?:.*\S)?$ description: | One line of an unstructured `Address`. example: "123 Example Rd" Apply / Chat Suggestion importance[1-10]: 6 __ Why: The suggestion improves data integrity by adding validation to addressLines, ensuring the array is not empty and its items are not blank strings. This makes the new field more robust.	Low
	✅ Correct inconsistent wording in description Suggestion Impact: Updated the addressLines description text to replace "party" with "location" (applied in both occurrences shown in the diff). code diff: @@ -1727,7 +1727,7 @@ description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. - **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. + **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location. items: type: string maxLength: 250 @@ -1782,7 +1782,7 @@ description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. - **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. + **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location. items: In the description for addressLines, change the word "party" to "location" to correctly reflect that the field is used to identify a location, not a party. cs/v1/CS_v1.0.2.yaml [1727-1730] description: | Unstructured address lines, used as a fallback when structured address fields are unavailable. - **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the party. + **Condition:** Providers **or** consumers on API v1.0.1 (or earlier): `addressLines` cannot be used as the only property to identify the location. [Suggestion processed] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies a copy-paste error in the description of addressLines where "party" is used instead of "location". Correcting this improves documentation clarity and consistency.	Low
Update

[Copilot]

Pull request overview

Copilot reviewed 1 out of 1 changed files in this pull request and generated no new comments.

---

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