This PR continues to assume that options are passed in as a precondition for decoding, but it throws errors instead of force-unwrapping dictionary entries. Ideally, #382 would incorporate these changes to fix #228.

Finish this sentence.

Some context would be helpful to do it :)

I think I had been going through the PR looking for breaking changes to call out but got distracted. If you see anything else that has changed in the public API besides the first item, feel free to add it here; otherwise, we can remove this item.

Can someone point me to some kind of a doc or explanation about tracepoints in the response and matchings_index, waypoint_index too?

Here’s the Map Matching API documentation, which is more relevant than before, now that this PR hews more closely to the Map Matching API response format.

It isn’t necessary to fix #386 as part of this PR, but I think understanding that issue helped me understand these properties better.

According to that doc, our Match and Tracepoint objects do not reflect the structure described. Is there any special reason why? Or that's what I can safely take care of?

The Map Matching API response format avoids repetition to minimize data transfer, and it’s optimized for a file format (JSON) that has no concept of pointer references. As a result, the response is rife with parallel structures and indices. At the same time, the Directions API response is influenced by the OSRM Router service’s heavily nested response format (maneuvers inside steps inside legs inside routes). As part of developing the “bring your own route” workflow, the Map Matching API adopted most of the Directions API’s format so that the client could duck-type matches as routes. So Map Matching API responses end up with a mix of indexable parallel structures in some places and repetitive, nested structures in other places.

Originally, this library only supported the Directions API, so it adopted that API’s highly nested structure. We also avoided index-based structures, even where the Directions API had them, because of potential out-of-bounds issues and other misuse. Pointer references are more convenient to work with than indices and don’t result in excessive memory consumption. It’s also much more convenient for objects to be self-contained: if the application only cares about the match, it can pass around or archive an individual Match object instead of the entire MatchResponse plus a match index.

In the long term, I think we will want to go all-in on indexed parallel structures, once a future version of the Directions API adopts Valhalla’s more consistently indexed-based structure. When we do that, things like the RouteLeg.segmentRangesByStep property added in #250 will be important for avoiding out-of-bounds issues.

But in the short term, we should keep pushing things like tracepoints down into the individual matches so that the matches are more self-contained.

This is a good example of how I think we want to be deliberate about where this library’s types resemble or differ from the API response. The API response format has a lot of warts, having bent over backwards to preserve backwards compatibility, so we only want to copy what make sense. We prioritized refactoring the waypoint/tracepoint types because they were too different from the corresponding API response objects, leading to some questionable patterns like treating RouteOptions.waypoints like an inout parameter. But I tried to avoid churning other classes were we differed in more minor or more deliberate ways.

OK, so due to some reasonable matters like API structure and JSON format we may not follow the doc strictly but instead "adjust" info we provide to users to have some adequate form.
At the same time, to correctly "keep pushing things like tracepoints down into the individual matches" we need to follow the doc and decode Tracepoint's matchings_index and waypoint_index... I see that previous implementation just copied all tracepoints to all matches, which seem to work only while there is a single Match provided (unless it was removed here).
We may just restore this behavior, but why not improve it to make it "more safe".

If we don't supply a name in a Tracepoint, Map Matching response decoding won't pass this data to RouteResponse and in it's turn resulting Waypoints won't have name too.

A waypoint (or tracepoint) name coming from the API isn’t actually that meaningful. Normally it’s just the name of the street that the waypoint got snapped to. If the application supplied a waypoint name as part of the request, that name is worth preserving. In the past, we’d override the API response’s waypoint names with the request’s waypoint names, where available. Now it’s up to the application to hang onto the request and associate the request’s waypoints with the response’s waypoints in some cases.

Sorry, it's a bit misleading: "that name is worth preserving" and "it’s up to the application to hang onto the request and associate the request’s waypoints with the response’s waypoints" seems to be the opposite statements.
If we are to preserve waypoint name returned by the API (and apparently Route.Waypoint is), Tracepoint should have a name. Otherwise, Waypoints won't be decoded correctly as they depend on Tracepoint data: https://github.com/mapbox/mapbox-directions-swift/pull/388/files#diff-a2198eb412da79c9d8351c4e811b7dc6R63-R66

These values are now decoded using ResponseDisposition, but It is only used internally while parsing the response and is not passed to the user. I assume this is what we want, and these keys inside RouteResponse are not needed?

Comment still actual

I think you’re right, because #418 turns the three fields into an Error in the Result.

I hope I understood correctly how filtering should be applied. I decided to stick to options.legSeparators and filter out decoded waypoints that correspond it.

MatchResponse seems removed in some other PR. I assume it means that that tracepoint filtering should occur in MapMatchingResponse instead?

At the time this PR was originally written, MatchResponse interpreted Map Matching API responses as Map Matching API responses (MatchOptions→Match), whereas MapMatchingResponse interpreted Map Matching API responses as Directions API responses (MatchOptions→Route). It was confusing, so #406 eliminated MapMatchingResponse and renamed MatchResponse to MapMatchingResponse.

There were not originally in the doc, but looks like it is required to have.

These indices are parallel state that can get out of sync with the array of matches or waypoints. This starts to get into #386 territory. I think the filtering suggested in that issue could make these properties unnecessary.

This part is how I understand Map Matching Doc. The idea is to set leg separators explicitly via matchings_index and waypoint_index. Not sure if it is required though or will have any effect at all since routes and waypoints are passed to the user as public properties and waypoints are not modified in this code.
A help/review would be required here.

I assume this is something we can expect to be guaranteed?

There will be fewer leg separators if any of the waypoints in the request had separatesLegs equal to false. A waypoint that doesn’t separate legs is also known as a “silent waypoint” or “via point”: it influences the path of the route but doesn’t get called out specifically as a destination.