Duplicate `id`s in `item` and `fulfillment` objects

[NikithShetty]

Problem The proposed metro schedule catalog represents items and fulfillments with duplicated objects so as to accommodate same ticket type linked to multiple routes and same route having multiple schedules respectively, which leads to confusion and is not immediately apparent, since id is an unique identifier for an object and here we are duplicating id for different objects.

The idea is that item maps to a ticket - Single Journey Ticket and fulfillment maps to a route - station1-to-station2 with multiple arrival and departure timings per station. Here item and fulfillment have 1 to many relationship. However, we also have price value which can differ per item - fulfillment pair which causes issue with this form of item.id duplication, since each item object in the catalog can have a unique price.

Sample on_search request

{
    "context": {
        "domain": "nic2004:60221",
        "country": "IND",
        "city": "std:080",
        "action": "on_search",
        "core_version": "0.9.1",
        "bap_id": "https://mock_bap.com/",
        "bap_uri": "https://mock_bap.com/beckn/",
        "bpp_id": "https://mock_bpp.com/",
        "bpp_uri": "https://mock_bpp.com/beckn/",
        "transaction_id": "1209849124",
        "message_id": "12341242343",
        "timestamp": "2021-03-23T10:00:40.065Z"
    },
    "message": {
        "catalog": {
            "bpp/descriptor": {
                "name": "KMRL"
            },
            "bpp/providers": [
                {
                    "id": "1",
                    "descriptor" : {
                        "name": "KMRL"
                    },
                    "locations": [
                        {
                            "id": "station-1",
                            "descriptor" : {
                                "name" : "Station 1",
                                "code" : "STN1"
                            },
                            "gps": "12.9349377,77.6055586"
                        },
                        {
                            "id": "station-2",
                            "gps": "12.9349377,77.6055586",
                            "descriptor" : {
                                "name" : "Station 3",
                                "code" : "STN3"
                            }
                        },
                        {
                            "id": "station-3",
                            "gps": "12.9349377,77.6055586",
                            "descriptor" : {
                                "name" : "Station 3",
                                "code" : "STN3"
                            }
                        }
                    ],
                    "items": [
                        {
                            "id": "1",
                            "descriptor" : {
                                "name" : "Single Journey Ticket",
                                "code" : "SJT"
                            },
                            "location_id": "station-1",
                            "fulfillment_id" : "station-1-to-station-2",
                            "price" : {
                                "currency" : "INR",
                                "value" : "20"
                            }
                        },
                        {
                            "id": "1",
                            "descriptor" : {
                                "name" : "Single Journey Ticket",
                                "code" : "SJT"
                            },
                            "location_id": "station-1",
                            "fulfillment_id" : "station-1-to-station-3",
                            "price" : {
                                "currency" : "INR",
                                "value" : "30"
                            }
                        },
                        {
                            "id": "1",
                            "descriptor" : {
                                "name" : "Single Journey Ticket",
                                "code" : "SJT"
                            },
                            "location_id": "station-3",
                            "fulfillment_id" : "station-3-to-station-2",
                            "price" : {
                                "currency" : "INR",
                                "value" : "20"
                            }
                        }
                    ],
                    "fulfillments" : [
                        {
                            "id" : "station-1-to-station-2",
                            "start" : {
                                "location" : {
                                    "id" : "station-1"
                                },
                                "time" : "10:00"
                            },
                            "end" : {
                                "location" : {
                                    "id" : "station-2"
                                }
                            },
                            "./komn-mobility-0_9_3.distance" : "12 km"
                        },
                        {
                            "id" : "station-1-to-station-3",
                            "start" : {
                                "location" : {
                                    "id" : "station-1"
                                },
                                "time" : "10:00"
                            },
                            "end" : {
                                "location" : {
                                    "id" : "station-3"
                                }
                            },
                            "./komn-mobility-0_9_3.distance" : "22 km"
                        },
                        {
                            "id" : "station-3-to-station-2",
                            "start" : {
                                "location" : {
                                    "id" : "station-3"
                                },
                                "time" : "10:20"
                            },
                            "end" : {
                                "location" : {
                                    "id" : "station-2"
                                }
                            },
                            "./komn-mobility-0_9_3.distance" : "12 km"
                        }
                    ]
                }
            ]
        }
    }
}

Proposed change I understand that there aren't any unique id generated by BPP for these items in the on_search request, and its also not feasible to uniquely generate and track them for search, where the volumes are high and conversion to confirm are lower comparatively.

With these in mind, I would propose to represent a ticket as item.type which refers to the type of the ticket - Single Journey Ticket, avoiding the usage of item.id. To confirm a ticket, BAP can send item.type and fulfillment.id as part of confirm API call.

For fulfillment, we should make use of schedule object and support arrival and departure schedules using fufillments.start.time.schedule and fulfillment.end.time.schedule arrays. We can specify that the array elements be ordered and fufillments.start.time.schedule and fulfillment.end.time.schedule array elements match to form pairs of arrival and departure time as part of network policy.

[pkapustin]

Agree with @NikithShetty here. Duplicate ids on both items and fulfillments easily lead to confusion, also this is error-prone in implementations as all references by ids that are duplicated become invalid.

Adding an example of the structure proposed.

{
   "items": [
       {
           "type": "SJT",
           "descriptor": {
               "name": "Single Journey Ticket",
               "code": "SJT"
           },
           "fulfillment_id": "station-1-to-station-2",
           "price": {
               "currency": "INR",
               "value": "20"
           }
       },
       {
           "type": "SJT",
           "descriptor": {
               "name": "Single Journey Ticket",
               "code": "SJT"
           },
           "fulfillment_id": "station-1-to-station-3",
           "price": {
               "currency": "INR",
               "value": "30"
           }
       }
   ],
   "fulfillments": [
       {
           "id": "station-1-to-station-2",
           "start": {
               "location": {
                   "id": "station-1"
               },
               "time": {
                   "schedule": {
                       "times": [
                           "2021-10-15T00:32:19.000Z",
                           "2021-10-15T01:42:19.000Z",
                           "2021-10-15T02:57:59.000Z",
                       ]
                   }
               }
           },
           "end": {
               "location": {
                   "id": "station-2"
               },
               "time": {
                   "schedule": {
                       "times": [
                           "2021-10-15T00:43:21.000Z",
                           "2021-10-15T01:53:21.000Z",
                           "2021-10-15T03:09:01.000Z",
                       ]
                   }
               }
           },
           "./metro-0_9_3.distance": "12 km"
       },
       {
           "id": "station-1-to-station-3",
           "start": {
               "location": {
                   "id": "station-1"
               },
               "time": {
                   "schedule": {
                       "times": [
                           "2021-10-15T00:32:19.000Z",
                           "2021-10-15T01:42:19.000Z",
                           "2021-10-15T02:57:59.000Z"
                       ]
                   }
               }
           },
           "end": {
               "location": {
                   "id": "station-3"
               },
               "time": {
                   "schedule": {
                       "times": [
                           "2021-10-15T00:43:21.000Z",
                           "2021-10-15T01:53:21.000Z",
                           "2021-10-15T03:09:01.000Z",
                       ]
                   }
               }
           },
           "./metro-0_9_3.distance": "22 km"
       }
   ]
}