Required, optional and reserved keys for "loc" events, and meaning of "v" field in "loc-enhanced" events?

Is there a reference for the required, optional, and reserved keys in “loc” events, when customizing firmware based on tracker-edge?

It seems I was unlucky enough to stumble upon “v” at the top level being a reserved field name which prevents “loc-enhanced” events from being generated.

I couldn’t find this documented anywhere though I may have just overlooked it since it’s tricky to search for the single letter “v”.

I don’t see it mentioned in the main event reference Cloud API | Reference Documentation | Particle and the enhanced location reference doesn’t mention it either (despite the fact that it is added to that event) Cloud API | Reference Documentation | Particle

Oddly, including a “src” field in the “loc” event is allowed and gets silently overwritten in “loc-enhanced” whereas a “v” field inhibits “loc-enhanced” altogether.

I’m not sure if this is a bug that “v” inhibits “loc-enhanced” or if it’s intentional and just needs documentation? And what is the meaning of the “v” field that is added to “loc-enhanced” events?


I also submitted two PRs to improve some of the documentation around location and enhanced location events based on the behavior I’ve observed, separate from this issue: Fix 'enhanced_loc' -> 'loc-enhanced', other style improvements by scottbez1 · Pull Request #1175 · particle-iot/docs · GitHub and Fix "loc.src" -> "src" in enhanced location docs by scottbez1 · Pull Request #1176 · particle-iot/docs · GitHub

The v key is the version of the location object. It’s not documented because it’s currently missing from the schema, but it should be added. Without the version the enhanced location won’t be generated because it assumes the data is the old version that predates location fusion and didn’t have a v key.

I’m not sure why the src is appearing outside of loc. The design doc had it inside so one or the other or wrong, but I don’t know which one is right.

It does make sense that src would be overwritten in the loc_enhanced because that indicates which sources were actually used to generate the enhanced location. For example, you might send up Wi-Fi information for an unknown network, but it should not appear in the src for the enhanced location since it’s unknown.