fix: Transition cart.id to be omitted in update requests instead of a required field (#633)

* Correct cart.id schema to be omitted in requests instead of required for update. Also updated validation scripts logic to apply any transition annotations on the core schema (validation should be done against the /to/ field instead of /from/).

* Augment main.py to also support transition annotation in schemas.

* Revert back inconsistent style fixes applied onto the files.

* Revert premature test updates and will be split out into a separate PR when the transition schema is finalized.

* Add deprecation tags in documents to call out the field will be dropped before the next release.

Author: jingyli

docs/specification/cart-rest.md

@@ -313,7 +313,7 @@ All REST endpoints **MUST** be served over HTTPS with minimum TLS version 1.3.
     Content-Type: application/json
 
     {
-      "id": "cart_abc123",
+      "id": "cart_abc123",  // deprecated: id is provided in URL path
       "line_items": [
         {
           "item": {

docs/specification/discount.md

@@ -403,7 +403,7 @@ to the order as a whole and uses `type: "discount"` in totals.
     <!-- ucp:example schema=shopping/cart op=update direction=request -->
     ```json
     {
-      "id": "...",
+      "id": "...",  // deprecated: id is provided in URL path
       "line_items": [ ... ],
       "discounts": {
         "codes": ["SAVE10"]
@@ -448,7 +448,7 @@ to line items, and an automatic shipping discount at the order level.
     <!-- ucp:example schema=shopping/cart op=update direction=request -->
     ```json
     {
-      "id": "...",
+      "id": "...",  // deprecated: id is provided in URL path
       "line_items": [ ... ],
       "discounts": {
         "codes": ["SUMMER20"]
@@ -519,7 +519,7 @@ but not in `discounts.applied`.
     <!-- ucp:example schema=shopping/cart op=update direction=request -->
     ```json
     {
-      "id": "...",
+      "id": "...",  // deprecated: id is provided in URL path
       "line_items": [ ... ],
       "discounts": {
         "codes": ["SAVE10", "EXPIRED50"]

main.py

@@ -643,8 +643,22 @@ def _field_requirement(field_name, ucp_request, required_list):
       diff_request = {}
       for op in ("create", "update", "complete"):
         val = ucp_request.get(op)
-        if val and val != response:
-          diff_request[op] = val
+        if val:
+          disp_val = None
+          if isinstance(val, str):
+            if val != response:
+              disp_val = word.get(val, val)
+          elif isinstance(val, dict) and "transition" in val:
+            transition = val["transition"]
+            to_state = transition.get("to")
+            from_state = transition.get("from")
+            from_disp = word.get(from_state, from_state)
+            to_disp = word.get(to_state, to_state)
+            disp_val = f"transitioning from {from_disp} to {to_disp}"
+
+          if disp_val:
+            diff_request[op] = disp_val
+
       if not diff_request:
         return base_disp
 
@@ -659,9 +673,7 @@ def _field_requirement(field_name, ucp_request, required_list):
           groups[-1][1].append(op)
         else:
           groups.append((val, [op]))
-      clauses = [
-        f"{word.get(val, val)} on {' & '.join(ops)}" for val, ops in groups
-      ]
+      clauses = [f"{val} on {' & '.join(ops)}" for val, ops in groups]
       if not clauses:
         return base_disp
       return f"{base_disp}; {', '.join(clauses)}"

source/schemas/shopping/cart.json

@@ -47,7 +47,13 @@
       "description": "Unique cart identifier.",
       "ucp_request": {
         "create": "omit",
-        "update": "required"
+        "update": {
+          "transition": {
+            "from": "required",
+            "to": "omit",
+            "description": "Id should be omitted in requests to favour transport level identifications (no duplication needed)."
+          }
+        }
       }
     },
     "line_items": {