Review of draft 1.0.0 version

[92shreyansh]

Hi All,

Creating this space to have a single space for all current & porspective NPs to raise concern and queries to the current draft version and suggest any improvement, before finalizing the specification.

[NirmalR-protean]

Hi @92shreyansh adding some queries we had for the draft version:

#	API	Use case	Question
1	search	Search with localization info	Can we get some clarity on what is meant here? Is this the language spoken by the driver?
2	on_search	All	Shouldn’t item be tagged to a location? The objects in the location array are not referenced anywhere. Is the location supposed to point to the closest vehicle for the fare product?
3	on_search	Return a mobility catalogue with no provider	The example still have providers. Can we understand more about this use case?
4	on_search	All	Will the list of enums for Fulfillment.vehicle.category be provided?
5	select	All	Provider ID is missing
6	select	All	Is address mandatory in select or any subsequent calls or transmitting the GPS coordinates enough?
7	on_select, on_init, on_confirm, on_status	All	Only item ID and other ID fields are usually sent in calls after on_search. Should the details of the fare product be sent again in all the subsequent calls?
8	on_select	All	Agent details are present in on_select itself in the example. Is this mandatory? Usually only after a ride is confirmed driver allocation happens.
9	on_track	All	Tracking object in schema only has url and status. Content_type is not present.
10	on_track	All	Would there be a JSON structure defined using which the location information would be returned from this URL by all NPs. Should the http method (GET/POST) be specified as well? Or is there a default method to be used.
11	on_status	All	Can the list of possible fulfillment statuses be published? We were able to see both DRIVER_EN_ROUTE_TO_PICKUP and DRIVER_EN_ROUTE in different examples
12	on_cancel	All	If orders with post fulfillment payment are allowed, how will cancellation fees be collected? Usually there can be an option to pay as part of next ride, but this ride can be with another sellerApp/provider
13	on_cancel	Return order cancelled by rider with cancellation charges	Shouldn't the status of fulfillment be some form of cancelled?
14	update, on_update	All	Will update use cases be supported? Updating drop location is a common use case but history of location changes might be required to be transmitted as part of the order which is difficult with just start and stop objects in a single fulfillment object.

[92shreyansh]

Hi @NirmalR-protean Fplease find my comments:

#	API	Use case	Question	Response
1	search	Search with localization info	Can we get some clarity on what is meant here? Is this the language spoken by the driver?	This identifies the language of the customer or the rider/customer who is searching for the cab as he prefers a driver with same language.
2	on_search	All	Shouldn’t item be tagged to a location? The objects in the location array are not referenced anywhere. Is the location supposed to point to the closest vehicle for the fare product?	Tagging of items with multiple locations shall be enabled in next version of beckn 1.X.
3	on_search	Return a mobility catalogue with no provider	The example still have providers. Can we understand more about this use case?	This is the use case where in the BPP itself is the provider or seller on record hence by the construct it is calling out a provider but there is no actual description or entity exists different from the BPP
4	on_search	All	Will the list of enums for Fulfillment.vehicle.category be provided?	Mobility Working Group will decide on this list
5	select	All	Provider ID is missing	Will Update
6	select	All	Is address mandatory in select or any subsequent calls or transmitting the GPS coordinates enough?	address is not manadatory gps coordinates can suffice atleast for the on-demand ride hailing use case for fixed start and end points
7	on_select, on_init, on_confirm, on_status	All	Only item ID and other ID fields are usually sent in calls after on_search. Should the details of the fare product be sent again in all the subsequent calls?	This is mainily considering the item construct being built dynamically with customers inputs, Kindly bring it up on Mobility Working Group Call
8	on_select	All	Agent details are present in on_select itself in the example. Is this mandatory? Usually only after a ride is confirmed driver allocation happens.	Not mandatory but added in case of multiple quote to ride. Kindly bring it up on Mobility Working Group Call
9	on_track	All	Tracking object in schema only has url and status. Content_type is not present.	Will update
10	on_track	All	Would there be a JSON structure defined using which the location information would be returned from this URL by all NPs. Should the http method (GET/POST) be specified as well? Or is there a default method to be used.	Mobility working group can come up with standarding this url or its specifics saying that the current specification carry has the place holder to carry this info via url
11	on_status	All	Can the list of possible fulfillment statuses be published? We were able to see both DRIVER_EN_ROUTE_TO_PICKUP and DRIVER_EN_ROUTE in different examples	The current version is draft only will come to some initial list with the mobility working group call
12	on_cancel	All	If orders with post fulfillment payment are allowed, how will cancellation fees be collected? Usually there can be an option to pay as part of next ride, but this ride can be with another sellerApp/provider	The current Payment model is PoD(Paymnet on Delivery), Other Payment mode considering all workflows like one you mentioned can be considered in next release with the help of mobility working group
13	on_cancel	Return order cancelled by rider with cancellation charges	Shouldn't the status of fulfillment be some form of cancelled?	Will update
14	update, on_update	All	Will update use cases be supported? Updating drop location is a common use case but history of location changes might be required to be transmitted as part of the order which is difficult with just start and stop objects in a single fulfillment object.	Current draft will doesn not support use case of change in location, only fix start and stop point are supported

[NirmalR-protean]

Hi @92shreyansh please let us know when the mobility working group meeting can be held so that we can iron out all the details.

[NirmalR-protean]

Hi @92shreyansh the examples in branch draft-1.x and draft are different.
Swagger hub schema in draft is https://app.swaggerhub.com/apis/ONDC/ONDC-Mobility-API-Specification
The same link given in draft-1.x is https://ondc-official.github.io/mobility-specification/

We were referring to the swaggerhub.com schema till now. Please confirm which we need to refer to.

[shobhanaquickride]

a) In the search API, the context has a "timestamp" field - does this indicate the timestamp at which the request originated or the planned start time of the ride? If it is the former, where can we get the planned start time of the ride?

b) In the on_search API, the sample shows a "message" field containing "locations" with 4 entries. What should these indicate? The search API would be called for only one start and end location. So we are not able to identify what these locations in the on_search API mean.

[NirmalR-protean]

a) The timestamp field in the context object is used for indicating the timestamp when the request was created. The planned start time of the ride should ideally be represented using the fufillment.start.time object.

b) They can be used for showing the closest available rides for the fare product. But I agree in the example they are not tagged to a specific item in the items array. This can be an issue if we have multiple items in the items array and we would need to specify which GPS location(s) is for which fare product.

[PhaniMahidhar]

Hii, Based on the new contract, this is my understanding of the flow :

• user searches with pickup and drop off location via /search
• bpp's responds with all their nearby providers(drivers) locations and cab pricing tier list via /on_search
• user selects from one of the cab tier list of a particular bpp though /select.
• multiple providers(drivers) from that bpp respond with their quote (via multiple /on_select).
• user selects one of the providers basis the quote or the car type and sends /init.
• user receives the final quotation with gst in /on_init for the provider
• user confirms the ride via /confirm.
• provider responds with /on_confirm acknowledging the ride creation and with the latest fulfillment details

Please let me know if there is any gap in understanding?
@92shreyansh