EBL 3.0: SD-2500: Add transportDocumentSubReference to Notifications

[HenrikHL]

User description

SD-2500: Add transportDocumentSubReference to TD-Notification

As part of this PR - the transportDocumentSubReference has also been added to the ShippingInstructionsNotification.

One of the example payloads has also been updated to reflect this option.

---

PR Type

Enhancement

---

Description

• Add transportDocumentSubReference field to TD-Notification schema

• Add transportDocumentSubReference field to ShippingInstructionsNotification schema

• Update example payloads to demonstrate new field usage

• Field enables versioning distinction for Transport Documents

---

Diagram Walkthrough

flowchart LR
  A["TD-Notification"] -->|"add field"| B["transportDocumentSubReference"]
  C["ShippingInstructionsNotification"] -->|"add field"| B
  D["Example Payloads"] -->|"updated with"| B

Loading

File Walkthrough

	Relevant files
Enhancement	EBL_v3.0.2.yaml Add transportDocumentSubReference to notification schemas ebl/v3/EBL_v3.0.2.yaml Added transportDocumentSubReference field definition to TD-Notification component schema with string type, max length 100, and pattern validation Added transportDocumentSubReference field definition to ShippingInstructionsNotification component schema with identical constraints Updated three example payloads (issuedPartialStateTransferExample, issuedFullStateTransferExample, and nested transportDocument) to include transportDocumentSubReference: v2 values Field includes description explaining its use for distinguishing between versions of the same Transport Document +17/-0
Configuration changes	styleguide.json Styleguide configuration updates                                                  .stoplight/styleguide.json Minor configuration or style guide updates +1/-1

---

[qodo-code-review]

PR Compliance Guide 🔍

(Compliance updated until commit fd7d465)

Below is a summary of compliance checks for this PR:

Security Compliance
⚪	Sensitive information exposure Description: The new free-text field transportDocumentSubReference may inadvertently expose internal versioning or sensitive operational references in notifications if not vetted; consider documenting allowed values and ensuring no confidential info is placed here. EBL_v3.0.2.yaml [2836-2842] Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1
Ticket Compliance
🟡	🎫 #SD-2500 🟢 Add an optional string field transportDocumentSubReference alongside transportDocumentReference in TD lightweight (notification) payloads. Enforce constraints: pattern ^\S(?:.*\S)?$, maxLength 100, provide example value like 'Version_1'. Update notification examples to include transportDocumentSubReference next to transportDocumentReference to illustrate use in distinguishing versions (e.g., VOIDED vs ISSUED). Ensure OpenAPI documentation/text describes that the field distinguishes versions of the same Transport Document and is optional. ⚪ Confirm that all relevant TD lightweight and ShippingInstructionsNotification endpoints/schemas across the API are consistently updated, not only the shown snippets.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No auditing context: The added schema fields and example payloads do not introduce or reference logging of critical actions, so it is unclear whether related create/update/read events for transport document references are audited. Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1 feedbacks: type: array description: | Feedback that can be provided includes, but is not limited to: - unsupported properties - changed values - removed properties - general information items: $ref: '#/components/schemas/Feedback' shippingInstructions: $ref: '#/components/schemas/ShippingInstructionsFullNotification' updatedShippingInstructions: $ref: '#/components/schemas/UpdatedShippingInstructionsFullNotification' ... (clipped 157 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing validation detail: While the new field includes a pattern and maxLength, the diff does not show how invalid inputs, nulls, or boundary violations are handled in processing or responses. Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: No error exposure spec: The schema changes and examples do not indicate how user-facing errors are phrased or whether internal details are suppressed when validation fails for the new field. Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1 feedbacks: type: array description: | Feedback that can be provided includes, but is not limited to: - unsupported properties - changed values - removed properties - general information items: $ref: '#/components/schemas/Feedback' shippingInstructions: $ref: '#/components/schemas/ShippingInstructionsFullNotification' updatedShippingInstructions: $ref: '#/components/schemas/UpdatedShippingInstructionsFullNotification' ... (clipped 157 lines)
	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: Logging not specified: The additions are schema fields and examples and do not show whether values like transport document references are logged or redacted in logs. Referred Code transportDocumentSubReference: v2 issuedFullStateTransferExample: summary: | Transport Document has been issued (Full State Transfer) description: | A full state transfer notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`) value: specversion: '1.0' id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 source: 'https://member.com/' type: org.dcsa.transport-document.v3 time: '2018-04-05T17:31:00Z' datacontenttype: application/json subscriptionReference: EBL001 data: transportDocumentStatus: ISSUED transportDocumentReference: HHL71800000 transportDocumentSubReference: v2 transportDocument: transportDocumentReference: HHL71800000 transportDocumentSubReference: v2
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Limited validation: The new transportDocumentSubReference includes a regex and length limit but the diff does not show broader input handling, sanitization, or authorization checks for usage of this field. Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1

Compliance status legend

🟢 - Fully Compliant
🟡 - Partial Compliant
🔴 - Not Compliant
⚪ - Requires Further Human Verification
🏷️ - Compliance label

---

Previous compliance checks

Compliance check up to commit fd7d465

Security Compliance
🟢	No security concerns identified No security vulnerabilities detected by AI analysis. Human verification advised for critical code.
Ticket Compliance
🟡	🎫 #SD-2500 🟢 Add an optional field transportDocumentSubReference alongside transportDocumentReference in the Transport Document lightweight notification schema. Ensure the new field follows constraints: type string, pattern ^\S(?:.*\S)?$, maximum length 100, with example like 'Version_1', and help text indicating it distinguishes versions of the same Transport Document. Update example payloads for TD notifications to include the optional transportDocumentSubReference next to the reference to illustrate usage. ⚪ (Context/use case) Enable distinguishing notifications for surrendered (VOIDED) vs amended (ISSUED) TDs using the subreference.
Codebase Duplication Compliance
⚪	Codebase context is not defined Follow the guide to enable codebase context checks.
Custom Compliance
🟢	Generic: Meaningful Naming and Self-Documenting Code Objective: Ensure all identifiers clearly express their purpose and intent, making code self-documenting Status: Passed
	Generic: Security-First Input Validation and Data Handling Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities Status: Passed
⚪	Generic: Comprehensive Audit Trails Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance. Status: No auditing context: The added schema fields and examples introduce a new identifier but do not demonstrate logging of critical actions or audit context, which may be handled elsewhere. Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1 feedbacks: type: array description: | Feedback that can be provided includes, but is not limited to: - unsupported properties - changed values - removed properties - general information items: $ref: '#/components/schemas/Feedback' shippingInstructions: $ref: '#/components/schemas/ShippingInstructionsFullNotification' updatedShippingInstructions: $ref: '#/components/schemas/UpdatedShippingInstructionsFullNotification' ... (clipped 157 lines)
	Generic: Robust Error Handling and Edge Case Management Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation Status: Missing validation flows: The schema adds a new optional field with pattern and maxLength but provides no error handling or edge-case response behavior for invalid inputs in the spec changes shown. Referred Code transportDocumentSubReference: type: string pattern: ^\S(?:.*\S)?$ maxLength: 100 description: | Additional reference that can be optionally used alongside the `transportDocumentReference` in order to distinguish between versions of the same `Transport Document`. example: Version_1
	Generic: Secure Error Handling Objective: To prevent the leakage of sensitive system information through error messages while providing sufficient detail for internal debugging. Status: No user error detail: The diff only adds schema fields and examples and does not indicate how user-facing errors are structured, which may be defined elsewhere. Referred Code data: transportDocumentStatus: ISSUED transportDocumentReference: HHL71800000 transportDocumentSubReference: v2 transportDocument: transportDocumentReference: HHL71800000 transportDocumentSubReference: v2 shippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9
	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: Logging not shown: The changes add a new identifier field and examples but provide no evidence of logging practices or redaction policies in this diff. Referred Code data: transportDocumentStatus: ISSUED transportDocumentReference: HHL71800000 transportDocumentSubReference: v2 issuedFullStateTransferExample: summary: | Transport Document has been issued (Full State Transfer) description: | A full state transfer notification explaining that a `Transport Document` has been issued (`transportDocumentStatus='ISSUED'`) value: specversion: '1.0' id: 3cecb101-7a1a-43a4-9d62-e88a131651e2 source: 'https://member.com/' type: org.dcsa.transport-document.v3 time: '2018-04-05T17:31:00Z' datacontenttype: application/json subscriptionReference: EBL001 data: transportDocumentStatus: ISSUED transportDocumentReference: HHL71800000 transportDocumentSubReference: v2 ... (clipped 3 lines)

[qodo-code-review]

PR Code Suggestions ✨

No code suggestions found for the PR.