You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
SD-1936: Update examples to be more specific and NOT autogenerated by e.g. SwaggerHub
PR Type
Enhancement, Documentation
Description
Add comprehensive request/response examples to PINT, Issuance, and Surrender API specs
Include realistic Transport Document example with full cargo and party details
Add error response examples for various HTTP status codes and scenarios
Provide rejection example for Issuance Response with unknown party scenario
Diagram Walkthrough
flowchart LR
A["OpenAPI Specs"] -->|Add Request Examples| B["PINT v3.0.0"]
A -->|Add Request Examples| C["Issuance v3.0.3"]
A -->|Add Request Examples| D["Surrender v3.0.3"]
B -->|Include Success & Error| E["Response Examples"]
C -->|Include Success & Error| E
D -->|Include Success & Error| E
E -->|Realistic Data| F["Non-autogenerated Examples"]
Loading
File Walkthrough
Relevant files
Documentation
EBL_PINT_v3.0.0.yaml
Add request and error response examples to PINT API
pint/v3/EBL_PINT_v3.0.0.yaml
Add regularSTDExample with complete Transport Document request payload including shipper, carrier, charges, and equipment details
Add error response examples for POST /v3/envelopes endpoint with 500 status code
Add error response examples for PUT /v3/envelopes/{envelopeReference}/additional-documents/{documentChecksum} endpoint
Add error response examples for PUT /v3/envelopes/{envelopeReference}/finish-transfer endpoint
Add error response examples for POST /v3/receiver-validation endpoint with both 404 (unknown party) and 500 (internal error) scenarios
Below is a summary of compliance checks for this PR:
Security Compliance
⚪
Token misuse risk
Description: The example embeds long JWT-like strings for envelopeManifestSignedContent and envelopeTransferChain that could be mistaken for live tokens if copied to non-example contexts; ensure they are clearly non-functional and sanitized across all examples. EBL_PINT_v3.0.0.yaml [206-208]
Description: An embedded base64 PDF blob and JWT-like example value may be large and could be reused inadvertently; confirm these are harmless placeholders and not sensitive or licensed content. EBL_ISS_v3.0.3.yaml [186-189]
Replace autogenerated SwaggerHub examples with specialized, accurate examples for all relevant endpoints in PINT API so conditional requirements are respected (e.g., not showing both consignee and endorsee simultaneously).
⚪
Provide specialized examples for all relevant endpoints in ISS API.
Provide specialized examples for all relevant endpoints in SUR API.
Include realistic request/response examples, including error scenarios, across PINT, ISS, and SUR.
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
Objective: To create a detailed and reliable record of critical system actions for security analysis and compliance.
Status: Audit relevance unclear: The PR adds OpenAPI examples only and does not include runtime logic for logging critical actions, so audit trail compliance cannot be determined from the diff.
Referred Code
application/json:
schema:
$ref: '#/components/schemas/EblEnvelope'examples:
regularSTDExample:
summary: | Endorsing a Transport Document with regular Dry cargodescription: | A **Transport Document** being sent. **Note:** The `envelopeManifestSignedContent` and `envelopeTransferChain` are not computed values but rather random strings (this example cannot be used as is).value:
transportDocument:
transportDocumentReference: 62CD536BA8D34C469AFDshippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9transportDocumentStatus: DRAFTtransportDocumentTypeCode: BOLisShippedOnBoardType: truefreightPaymentTermCode: PREisElectronic: trueisToOrder: true... (clipped 471 lines)
Generic: Robust Error Handling and Edge Case Management
Objective: Ensure comprehensive error handling that provides meaningful context and graceful degradation
Status: Example-only errors: The PR adds structured error response examples but does not show actual error handling logic or validation paths, so robustness cannot be verified from the diff.
Referred Code
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'examples:
errorExample:
summary: | Internal Errordescription: | An Internal error occurred. **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example".value:
httpMethod: PUTrequestUri: /v3/ebl-issuance-requestsstatusCode: 500statusCodeText: Internal ErrorstatusCodeMessage: Internal ErrorproviderCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962errorDateTime: '2025-11-26T09:41:00Z'errors:
- errorCode: 7003... (clipped 77 lines)
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 diff only adds API examples and does not demonstrate logging behavior, so secure logging practices cannot be assessed.
Referred Code
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'examples:
errorExample:
summary: | Internal Errordescription: | An Internal error occurred. **NB**: The `errorCode` is not yet standardized by DCSA. The value `7003` is just a "random example".value:
httpMethod: POSTrequestUri: /v3/ebl-surrender-requestsstatusCode: 500statusCodeText: Internal ErrorstatusCodeMessage: Internal ErrorproviderCorrelationReference: 4426d965-0dd8-4005-8c63-dc68b01c4962errorDateTime: '2025-11-26T09:41:00Z'errors:
- errorCode: 7003... (clipped 54 lines)
Generic: Security-First Input Validation and Data Handling
Objective: Ensure all data inputs are validated, sanitized, and handled securely to prevent vulnerabilities
Status: Validation unspecified: The PR defines request/response examples but does not include input validation or auth controls, making security posture unverifiable from the diff.
Referred Code
application/json:
schema:
$ref: '#/components/schemas/EblEnvelope'examples:
regularSTDExample:
summary: | Endorsing a Transport Document with regular Dry cargodescription: | A **Transport Document** being sent. **Note:** The `envelopeManifestSignedContent` and `envelopeTransferChain` are not computed values but rather random strings (this example cannot be used as is).value:
transportDocument:
transportDocumentReference: 62CD536BA8D34C469AFDshippingInstructionsReference: fc5009a7-25ad-4bb0-9892-4e2dea6bcdd9transportDocumentStatus: DRAFTtransportDocumentTypeCode: BOLisShippedOnBoardType: truefreightPaymentTermCode: PREisElectronic: trueisToOrder: true... (clipped 471 lines)
To improve maintainability, define large, duplicated API examples (like transport documents and error responses) as reusable components in the components/examples section. Then, reference them using $ref in the API endpoints instead of defining them inline.
examples:
regularSTDExample:
summary: | Endorsing a Transport Document with regular Dry cargodescription: | A **Transport Document** being sent. **Note:** The `envelopeManifestSignedContent` and `envelopeTransferChain` are not computed values but rather random strings (this example cannot be used as is).value:
transportDocument:
... (clipped 106 lines)
examples:
regularSTDExample:
summary: | Issuing a Transport Document with regular Dry cargodescription: | A **Transport Document** being issued. **Note:** The `content` in the `eBLVisualisationByCarrier` and `issuanceManifestSignedContent` are not "real" values but rather random strings (this example cannot be used as is).value:
document:
... (clipped 114 lines)
Solution Walkthrough:
Before:
# In pint/v3/EBL_PINT_v3.0.0.yamlpaths:
/v3/envelopes:
post:
requestBody:
content:
application/json:
examples:
regularSTDExample:
summary: Endorsing a Transport Document...value:
transportDocument:
transportDocumentReference: 62CD536BA8D34C469AFD# ... many lines of duplicated example dataresponses:
'500':
content:
application/json:
examples:
errorExample:
value:
# ... duplicated error response fields
After:
# In a shared file or within each file's components sectioncomponents:
examples:
transportDocumentExample:
summary: Endorsing a Transport Document...value:
transportDocument:
transportDocumentReference: 62CD536BA8D34C469AFD# ... many lines of example data defined onceinternalErrorExample:
value:
# ... generic error response fields defined once# In pint/v3/EBL_PINT_v3.0.0.yamlpaths:
/v3/envelopes:
post:
requestBody:
content:
application/json:
examples:
regularSTDExample:
$ref: '#/components/examples/transportDocumentExample'responses:
'500':
content:
application/json:
examples:
errorExample:
$ref: '#/components/examples/internalErrorExample'
Suggestion importance[1-10]: 8
__
Why: The suggestion correctly identifies significant duplication of large example objects across multiple files and proposes using reusable components, which is a standard OpenAPI best practice that greatly improves maintainability.
Medium
General
Fix grammatical error in example
Correct a grammatical error in the termsAndConditions example text from "exist is name only" to "exists in name only".
termsAndConditions: |
- You agree that this transport document exist is name only for the sake of+ You agree that this transport document exists in name only for the sake of
testing your conformance with the DCSA eBL API. This transport document is NOT backed
by a real shipment with ANY carrier and NONE of the requested services will be
carried out in real life.
Unless required by applicable law or agreed to in writing, DCSA provides
this JSON data on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
ANY KIND, either express or implied, including, without limitation, any
warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY,
or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for
determining the appropriateness of using or redistributing this JSON
data and assume any risks associated with Your usage of this data.
In no event and under no legal theory, whether in tort (including negligence),
contract, or otherwise, unless required by applicable law (such as deliberate
and grossly negligent acts) or agreed to in writing, shall DCSA be liable to
You for damages, including any direct, indirect, special, incidental, or
consequential damages of any character arising as a result of this terms or conditions
or out of the use or inability to use the provided JSON data (including but not limited
to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any
and all other commercial damages or losses), even if DCSA has been advised of the
possibility of such damages.
Apply / Chat
Suggestion importance[1-10]: 2
__
Why: The suggestion correctly identifies a grammatical error in a text block within an example, and the fix improves clarity and professionalism.
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
User description
SD-1936: Update examples to be more specific and NOT autogenerated by e.g. SwaggerHub
PR Type
Enhancement, Documentation
Description
Add comprehensive request/response examples to PINT, Issuance, and Surrender API specs
Include realistic Transport Document example with full cargo and party details
Add error response examples for various HTTP status codes and scenarios
Provide rejection example for Issuance Response with unknown party scenario
Diagram Walkthrough
File Walkthrough
EBL_PINT_v3.0.0.yaml
Add request and error response examples to PINT APIpint/v3/EBL_PINT_v3.0.0.yaml
regularSTDExamplewith complete Transport Document request payloadincluding shipper, carrier, charges, and equipment details
/v3/envelopesendpoint with 500status code
/v3/envelopes/{envelopeReference}/additional-documents/{documentChecksum}endpoint
/v3/envelopes/{envelopeReference}/finish-transferendpoint/v3/receiver-validationendpointwith both 404 (unknown party) and 500 (internal error) scenarios
EBL_ISS_v3.0.3.yaml
Add request and response examples to Issuance APIebl/v3/issuance/EBL_ISS_v3.0.3.yaml
regularSTDExamplewith complete Issuance Request includingdocument details, party information, and carrier visualization
rejectedExampleshowing rejection response whenIssueToparty isunknown on receiving platform
/v3/ebl-issuance-requestsendpointwith 500 status code
/v3/ebl-issuance-responsesendpoint with 500 status code
EBL_SUR_v3.0.3.yaml
Add request and error response examples to Surrender APIebl/v3/surrender/EBL_SUR_v3.0.3.yaml
surrenderExamplewith complete Surrender Request includingendorsement chain with action history and party details
/v3/ebl-surrender-requestsendpoint with 500 status code
/v3/ebl-surrender-responsesendpoint with 500 status code
styleguide.json
Update styleguide configuration.stoplight/styleguide.json