CS 1.0: SD-2690: Add carbon footprint

[HenrikHL]

User description

SD-2690: CS Patch - PtoP - Feedback CMA: optional object to provide carbon footprint per solution and per leg
Added some missing descriptions as well

---

PR Type

Enhancement, Documentation

---

Description

• Add carbon footprint emission properties to routing solutions

• Add footprint tracking per individual transport leg

• Include CO2, SOx, NOx, and PM10 emission metrics

• Add missing object descriptions for Timestamp, Vessel, and Barge

• Standardize en-dash formatting in documentation

---

Diagram Walkthrough

flowchart LR
  A["Routing Solution"] -->|"solutionFootprint"| B["CO2, SOx, NOx, PM10"]
  C["Transport Leg"] -->|"footprint"| D["CO2, SOx, NOx, PM10"]
  E["Schema Objects"] -->|"Add descriptions"| F["Timestamp, Vessel, Barge"]

Loading

File Walkthrough

	Relevant files
Enhancement	CS_v1.0.2.yaml Add carbon footprint emissions and schema descriptions      cs/v1/CS_v1.0.2.yaml Add solutionFootprint object to routing solutions with CO2, SOx, NOx, PM10 emission metrics Add footprint object to individual legs with same emission properties Add missing descriptions to Timestamp, Vessel, and Barge schema objects Standardize en-dash formatting in documentation (replace – with -) Minor formatting adjustments and whitespace cleanup +67/-2
Configuration changes	styleguide.json Update styleguide configuration                                                    .stoplight/styleguide.json Configuration file modifications (insufficient detail available) +1/-1

---

[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-2690 🟢 Add an optional carbon footprint object at the routing solution (global solution) level. Add an optional carbon footprint object at the transport leg level (per leg). Do not add any route filtering based on a customer-provided max total footprint. Do not add details about how emissions are calculated (methodology text is up to carriers). 🔴 Include emission metrics for CO2, SOx, NOx, and PM10. Footprint values are expressed per TEU. ⚪ Confirm the intended property naming matches the ticket/proposed schema (e.g., carbonDioxide/sulfurOxide/nitrogenOxide/smallParticle or other agreed naming), since the PR currently uses co2, so, no, pm10 (and descriptions reference "COx" for sulphur oxides). Confirm with stakeholders/carrier expectations that the units and "per TEU" basis are correctly represented in the API spec and examples (the PR adds units but does not explicitly state "per TEU" on the new fields).
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: Unclear field names: The new footprint property names so and no are ambiguous/non-standard for SOx/NOx emissions (and the so description even references COx), reducing self-documentation and risking misuse. Referred Code so: type: number format: double description: | CO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 no: type: number 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 value bounds: The added emissions fields (co2, so, no, pm10) are typed as numbers but do not define basic edge-case constraints (e.g., minimum: 0), which may allow invalid negative emissions unless validated elsewhere. Referred Code co2: type: number format: double description: | CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t / Mg). example: 506.4 so: type: number format: double description: | CO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 no: type: number format: double description: | NO<sub>x</sub> (Nitrogen Oxide) emissions in kilograms (kg). example: 15.4 pm10: type: number format: double ... (clipped 3 lines) 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: Schema validation gaps: The new emissions objects accept any numeric values without additional validation (e.g., non-negative constraints and potentially additionalProperties: false), so it is unclear whether external inputs are sufficiently constrained by the API contract or server-side validation. Referred Code solutionFootprint: type: object description: | Carbon footprint emission calculation for the full routing solution. properties: co2: type: number format: double description: | CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t / Mg). example: 506.4 so: type: number format: double description: | CO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 no: type: number format: double description: | ... (clipped 8 lines) 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

[Copilot]

Pull request overview

This PR adds carbon footprint emission tracking capabilities to the Commercial Schedules API v1.0.2. It introduces emission metrics (CO₂, SOₓ, NOₓ, and PM₁₀) at both the routing solution and individual transport leg levels, enabling users to evaluate environmental impact of different shipping routes.

Key Changes:

• Added solutionFootprint object to routing solutions for aggregate emissions across the entire route
• Added footprint object to individual transport legs for granular emission tracking per segment
• Enhanced schema documentation by adding descriptions to Timestamp, Vessel, and Barge objects

Reviewed changes

Copilot reviewed 1 out of 2 changed files in this pull request and generated 7 comments.

File	Description
CS_v1.0.2.yaml	Adds carbon footprint emission properties to routing solutions and transport legs, includes missing object descriptions, and standardizes en-dash formatting
styleguide.json	Minor configuration update

---

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

[qodo-code-review]

PR Code Suggestions ✨

Latest suggestions up to 856953e

Category	Suggestion	Impact
Incremental [*]	Prevent negative emission values Add a minimum: 0 constraint to the sox and nox emission fields in the OpenAPI schema to prevent negative values. cs/v1/CS_v1.0.2.yaml [839-850] sox: type: number format: double + minimum: 0 description: | SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 nox: type: number format: double + minimum: 0 description: | NO<sub>x</sub> (Nitrogen Oxide) emissions in kilograms (kg). example: 15.4 Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly points out that emission values cannot be negative and adds a minimum: 0 constraint, which improves the schema's data validation and prevents potential downstream calculation errors.	Medium
	Require and restrict footprint fields In the footprint object schema, add required for all its properties (co2, sox, nox, pm10) and set additionalProperties: false to ensure complete and valid data. cs/v1/CS_v1.0.2.yaml [1638-1666] footprint: type: object description: | Carbon footprint emission values for this particular leg. + additionalProperties: false + required: + - co2 + - sox + - nox + - pm10 properties: co2: type: number format: double description: | CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t / Mg). example: 506.4 sox: type: number format: double description: | SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 nox: type: number format: double description: | NO<sub>x</sub> (Nitrogen Oxide) emissions in kilograms (kg). example: 15.4 pm10: type: number format: double description: | PM<sub>10</sub> (Small Particle) emissions in kilograms (kg). example: 0.8 Apply / Chat Suggestion importance[1-10]: 7 __ Why: The suggestion correctly proposes to make the footprint object's properties required and to disallow additional properties, which enforces a complete and strict data structure, improving API contract clarity and robustness.	Medium
More

---

Previous suggestions

✅ Suggestions up to commit 01f4ff6

Category	Suggestion	Impact
High-level	Define a reusable carbon footprint schema Refactor the duplicated carbon footprint object into a single reusable Footprint schema and use $ref to reference it. Update the descriptions to clarify that emission values are calculated per TEU. Examples: cs/v1/CS_v1.0.2.yaml [828-856] solutionFootprint: type: object description: | Carbon footprint emission calculation for the full routing solution. properties: co2: type: number format: double description: | CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t / Mg). ... (clipped 19 lines) cs/v1/CS_v1.0.2.yaml [1638-1666] footprint: type: object description: | Carbon footprint emission values for this partical leg. properties: co2: type: number format: double description: | CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t / Mg). ... (clipped 19 lines) Solution Walkthrough: Before: # In cs/v1/CS_v1.0.2.yaml components: schemas: RoutingSolution: properties: solutionFootprint: type: object description: Carbon footprint emission calculation for the full routing solution. properties: co2: description: CO2 ... emissions in metric tonnes (t / Mg). # ... other duplicated fields Leg: properties: footprint: type: object description: Carbon footprint emission values for this partical leg. properties: co2: description: CO2 ... emissions in metric tonnes (t / Mg). # ... other duplicated fields After: # In cs/v1/CS_v1.0.2.yaml components: schemas: Footprint: type: object description: Carbon footprint emissions per TEU. properties: co2: description: CO2 ... emissions in metric tonnes (t / Mg) per TEU. # ... other fields RoutingSolution: properties: solutionFootprint: $ref: '#/components/schemas/Footprint' Leg: properties: footprint: $ref: '#/components/schemas/Footprint' Suggestion importance[1-10]: 9 __ Why: The suggestion correctly identifies significant schema duplication and a critical omission of "per TEU" context, improving both API design maintainability and data clarity.	High
General	Require emission fields Make all emission metrics (co2, so, no, pm10) required fields within the solutionFootprint schema. cs/v1/CS_v1.0.2.yaml [828-831] solutionFootprint: type: object + required: + - co2 + - so + - no + - pm10 description: | Carbon footprint emission calculation for the full routing solution. Suggestion importance[1-10]: 6 __ Why: The suggestion proposes making all emission metrics required, which improves data consistency and contract strictness, though it's a design choice rather than a bug fix.	Low
	✅ Correct typo in description Suggestion Impact: Updated the footprint object's description to replace the misspelled word "partical" with "particular". code diff: @@ -1638,7 +1638,7 @@ footprint: type: object description: | - Carbon footprint emission values for this partical leg. + Carbon footprint emission values for this particular leg. properties: Correct the typo "partical" to "particular" in the footprint object's description. cs/v1/CS_v1.0.2.yaml [1640-1641] description: | - Carbon footprint emission values for this partical leg. + Carbon footprint emission values for this particular leg. [Suggestion processed] Suggestion importance[1-10]: 2 __ Why: The suggestion correctly identifies and fixes a minor typo ("partical" to "particular") in the documentation, which improves readability.	Low
Possible issue	✅ Fix typo in emission description Suggestion Impact: The commit updates the description text from "COx" to "SOx" in both places. It also renames the properties from `so` to `sox` (and `no` to `nox`) and fixes an unrelated typo ("partical" -> "particular"). code diff: - so: + sox: type: number format: double description: | - CO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). + SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 - no: + nox: type: number format: double description: | @@ -1638,7 +1638,7 @@ footprint: type: object description: | - Carbon footprint emission values for this partical leg. + Carbon footprint emission values for this particular leg. properties: co2: type: number @@ -1646,13 +1646,13 @@ description: | CO<sub>2</sub> (Carbon Dioxide) emissions in metric tonnes (t / Mg). example: 506.4 - so: + sox: type: number format: double description: | - CO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). + SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 Correct the typo in the so property description from COx to SOx in both the solutionFootprint and footprint objects. cs/v1/CS_v1.0.2.yaml [839-844] so: type: number format: double description: | - CO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). + SO<sub>x</sub> (Sulphur Oxide) emissions in kilograms (kg). example: 12.4 [Suggestion processed] Suggestion importance[1-10]: 4 __ Why: The suggestion correctly identifies a typo in the API documentation where COx is used instead of SOx, which improves clarity and accuracy.	Low

[Copilot]

Pull request overview

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

---

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

[emiliosolanes]

to me it looks fine.

[emiliosolanes]

i leave any techical comment to Pedro or Sangheeta.

[emiliosolanes]

i just realized i used my personal github to comment XD. i was receiving replies in gmail.