Clarify parameter definition for third-party location lookups

[deepbluev7]

While 1405184 redefined most fields to be the appropriate object type, it missed one of them.

Signed-off-by: Nicolas Werner [email protected]

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

Preview: https://pr1947--matrix-spec-previews.netlify.app

[richvdh]

Sorry for the delay in reviewing this.

It took me a while to figure out what is going on here; but with reference to a previous discussion thread and the OpenAPI spec, I think I've figured it out. I'll write down my conclusions for the sake of future archaeologists (including myself).

As I understand it, this is replacing the searchFields query-parameter of the GET /_matrix/client/v3/thirdparty/location/{protocol}, which is a string, with a pseudo-parameter named fields, which is specified as an object.

The relevant part of the OpenAPI spec is the definition of the Parameter Object; in particular the rules for serialization of the parameter. The relevant OpenAPI fields are style (which is specified to default to form for query parameters) and explode (which defaults to true when style is form). The style examples table then gives an example serialization of R=100&G=200&B=150 for an object containing keys R, G and B.

[I now see that @deepbluev7 has reached much the same conclusion at https://github.com//issues/560#issuecomment-2344138695.]

It's worth noting that the name of the object parameter (fields) is never actually used in the API. AIUI, this is being changed from searchFields for consistency with the definitions of other, similar, APIs.

Looking at #560, and #1584, this appears to be a correct change.

[richvdh]

I've opened #1993 to track the fact that the spec text makes a mess of this.